Merge pull request #50 from mathisloge/ml/docs

Refactor cmake & add first docs to setup quite

Author: mathisloge

CMakeLists.txt

@@ -28,6 +28,7 @@ include(GenerateExportHeader)
 include(FeatureSummary)
 include(GNUInstallDirs)
 include(GetGitRevisionDescription)
+include(CMakeDependentOption)
 
 set(CMAKE_CXX_SCAN_FOR_MODULES OFF)
 set(CMAKE_CXX_EXTENSIONS OFF)
@@ -36,13 +37,35 @@ set(CMAKE_VISIBILITY_INLINES_HIDDEN 1)
 set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/runtime")
 
-option(QUITE_BUILD_PROBES "Decides if the probes should be build" ON)
+option(QUITE_BUILD_PROBE_QT "Decides if the probes should be build" ON)
+option(QUITE_BUILD_TEST_API "Decides if the testing API should be build" ON)
+cmake_dependent_option(
+    QUITE_BUILD_PYTHON_TEST_API
+    "Decides if the python testing API should be build"
+    ON
+    QUITE_BUILD_TEST_API
+    OFF
+)
+option(
+    QUITE_BUILD_REMOTE_MANAGER
+    "Decides if the remote manager should be build"
+    ON
+)
+
+add_feature_info(QtProbe QUITE_BUILD_PROBE_QT "Build probeqt")
+add_feature_info(TestingApi QUITE_BUILD_TEST_API "Build testing API")
 add_feature_info(
-    Studio
-    QUITE_BUILD_STUDIO
-    "The studio provides a way to interactively explore the objects in the app."
+    TestingPythonApi
+    QUITE_BUILD_PYTHON_TEST_API
+    "Build testing API"
 )
-add_feature_info(Testing BUILD_TESTING "Build all tests.")
+add_feature_info(
+    RemoteManager
+    QUITE_BUILD_REMOTE_MANAGER
+    "Build remote manager"
+)
+
+add_feature_info(Testing BUILD_TESTING "Build all tests")
 add_feature_info(
     SharedLibraries
     BUILD_SHARED_LIBS
@@ -56,55 +79,61 @@ message(STATUS "git_branch: ${git_branch}")
 find_package(Sanitizers REQUIRED)
 ### NOTE: Set CPM_USE_LOCAL_PACKAGES or CPM_LOCAL_PACKAGES_ONLY to true if you want to use system packages or a package manager like vcpkg.
 include(get_cpm)
-set(BOOST_VERSION "1.88.0")
+set(BOOST_VERSION "1.89.0")
 list(APPEND BOOST_INCLUDE_LIBRARIES asio process)
 cpmaddpackage(
   NAME Boost
   VERSION "${BOOST_VERSION}"
   URL https://github.com/boostorg/boost/releases/download/boost-${BOOST_VERSION}/boost-${BOOST_VERSION}-cmake.tar.xz
-  URL_HASH SHA256=f48b48390380cfb94a629872346e3a81370dc498896f16019ade727ab72eb1ec
+  URL_HASH SHA256=67acec02d0d118b5de9eb441f5fb707b3a1cdd884be00ca24b9a73c995511f74
   EXCLUDE_FROM_ALL ON
   SYSTEM ON
   FIND_PACKAGE_ARGUMENTS "CONFIG"
   OPTIONS "BOOST_ENABLE_CMAKE ON" "BOOST_PROCESS_USE_STD_FS ON" "BOOST_SKIP_INSTALL_RULES ${CMAKE_SKIP_INSTALL_RULES}"
 )
 cpmaddpackage("gh:fmtlib/fmt#11.2.0")
-cpmaddpackage("gh:odygrd/quill@10.0.1")
+cpmaddpackage("gh:odygrd/quill@10.1.0")
 cpmaddpackage(URI "gh:skypjack/[email protected]" NAME "EnTT" FIND_PACKAGE_ARGUMENTS "CONFIG")
-cpmaddpackage(URI "gh:CLIUtils/[email protected]" OPTIONS "CLI11_PRECOMPILED ON")
-cpmaddpackage(URI "gh:NVIDIA/stdexec#0d0a15c669cbd2571248536a7e70524d8b7071aa" NAME "stdexec" VERSION 0.11 FIND_PACKAGE_ARGUMENTS "CONFIG" OPTIONS "STDEXEC_BUILD_TESTS OFF" "STDEXEC_BUILD_EXAMPLES OFF" "STDEXEC_ENABLE_ASIO ON"
+cpmaddpackage(URI "gh:NVIDIA/stdexec#daf12bcc46438f88b3c78212363f7b6531338780" NAME "stdexec" VERSION 0.11 FIND_PACKAGE_ARGUMENTS "CONFIG" OPTIONS "STDEXEC_BUILD_TESTS OFF" "STDEXEC_BUILD_EXAMPLES OFF" "STDEXEC_ENABLE_ASIO ON"
 )
 cpmaddpackage(URI "gh:Tradias/[email protected]" FIND_PACKAGE_ARGUMENTS "CONFIG" VERSION 3.4.0)
 cpmaddpackage(URI "gh:nlohmann/[email protected]" FIND_PACKAGE_ARGUMENTS "CONFIG" NAME "nlohmann_json")
 cpmaddpackage(URI "gh:nothings/stb#f0569113c93ad095470c54bf34a17b36646bbbb5" NAME Stb
 )
+find_package(gRPC CONFIG REQUIRED)
 set(Stb_INCLUDE_DIR "$<BUILD_INTERFACE:${Stb_SOURCE_DIR}>")
-cpmaddpackage(URI "gh:pybind/[email protected]" FIND_PACKAGE_ARGUMENTS "CONFIG" VERSION 3.0.0)
+if(QUITE_BUILD_REMOTE_MANAGER OR BUILD_TESTING)
+    cpmaddpackage(URI "gh:CLIUtils/[email protected]" OPTIONS "CLI11_PRECOMPILED ON")
+endif()
 if(BUILD_TESTING)
     cpmaddpackage("gh:vector-of-bool/cmrc#952ffddba731fc110bd50409e8d2b8a06abbd237"
     )
-    cpmaddpackage("gh:catchorg/[email protected]")
     cpmaddpackage("gh:boost-ext/[email protected]")
 endif()
 
-find_package(
-    Qt6
-    REQUIRED
-    COMPONENTS Core Gui Qml Quick Widgets
-    REQUIRED
-)
-find_package(gRPC CONFIG REQUIRED)
+if(QUITE_BUILD_PROBE_QT)
+    find_package(
+        Qt6
+        REQUIRED
+        COMPONENTS Core Gui Qml Quick Widgets
+        REQUIRED
+    )
+endif()
+add_subdirectory(libs)
 if(BUILD_TESTING)
-    list(APPEND CMAKE_MODULE_PATH "${Catch2_SOURCE_DIR}/extras")
-    include(Catch)
+    add_subdirectory(simple_tester)
 endif()
 
-add_subdirectory(libs)
-add_subdirectory(python)
-add_subdirectory(remote-manager)
+if(QUITE_BUILD_PYTHON_TEST_API)
+    cpmaddpackage(URI "gh:pybind/[email protected]" FIND_PACKAGE_ARGUMENTS "CONFIG" VERSION 3.0.0)
+    add_subdirectory(python)
+endif()
+
+if(QUITE_BUILD_REMOTE_MANAGER)
+    add_subdirectory(remote-manager)
+endif()
 if(BUILD_TESTING)
-    add_subdirectory(integration_test)
-    add_subdirectory(test)
+    add_subdirectory(example)
 endif()
 
 feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES DESCRIPTION "Features:")

CMakePresets.json

@@ -13,10 +13,13 @@
             "generator": "Ninja",
             "installDir": "${sourceDir}/dist",
             "cacheVariables": {
-                "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
+                "CMAKE_EXPORT_COMPILE_COMMANDS": true,
                 "Python3_FIND_VIRTUALENV": "FIRST",
                 "Python3_EXECUTABLE": "${sourceDir}/venv",
-                "BUILD_SHARED_LIBS": "ON"
+                "BUILD_SHARED_LIBS": true,
+                "QUITE_BUILD_PROBE_QT": true,
+                "QUITE_BUILD_TEST_API": true,
+                "QUITE_BUILD_PYTHON_TEST_API": true
             }
         },
         {
@@ -83,8 +86,6 @@
             ],
             "cacheVariables": {
                 "BUILD_SHARED_LIBS": false,
-                "QUITE_BUILD_STUDIO": false,
-                "QUITE_BUILD_PROBES": true,
                 "QUITE_EXAMPLES": false
             }
         },

README.md

@@ -3,7 +3,7 @@
 </div
 
 quite is a new UI testing framework specifically designed for applications built on the Qt framework.
-It aims to provide developers and testers with an efficient way to automate the testing of Qt application user interfaces.
+It aims to provide developers and testers with an efficient way to automate the testing of Qt user interfaces.
 
 I welcome any feedback, suggestions, and contributions that can help make quite a robust and reliable native UI testing framework!
 
@@ -13,6 +13,15 @@ I welcome any feedback, suggestions, and contributions that can help make quite
 > Changes may occur without notice, and existing code may become incompatible with future versions.
 > Until v2 I will not mark any change as breaking change.
 
+# Documentation
+
+Full documentation is available at [quite.rocks](https://quite.rocks).
+
+Some useful starting points:
+
+- [Getting Started](https://quite.rocks/getting-started) – install quite and run your first test
+- [Building from Source](https://quite.rocks/building) – instructions for compiling
+
 # Release and branch strategy
 
 All PRs should be target the develop branch.

docs/building.md

@@ -0,0 +1,73 @@
+# Building
+
+## Build against system packages
+
+By default, most dependencies are fetched with [CPM.cmake](https://github.com/cpm-cmake/CPM.cmake).
+
+If you prefer to use **system-installed packages** instead of downloading them directly, configure CPM with one of these options:
+
+- `CPM_USE_LOCAL_PACKAGES=ON`
+- `CPM_LOCAL_PACKAGES_ONLY=ON`
+
+See the [CPM reference](https://github.com/cpm-cmake/CPM.cmake?tab=readme-ov-file#cpm_use_local_packages) for details.
+
+!!! tip
+    Use `CPM_LOCAL_PACKAGES_ONLY=ON` when integrating with package managers such as **Conan** or **vcpkg**.
+    This ensures CPM won’t try to fetch sources remotely.
+
+---
+
+## General dependencies
+
+* [Boost](https://www.boost.org/) >= `1.83.0`
+* [gRPC](https://grpc.io/) >= `1.51.1`
+* [fmt](https://fmt.dev) >= `11.0.0`
+* [Quill](https://github.com/odygrd/quill) >= `10.0.0`
+* [EnTT](https://github.com/skypjack/entt) >= `3.15.0`
+* [stdexec](https://github.com/NVIDIA/stdexec) >= `daf12bcc46438f88b3c78212363f7b6531338780`
+* [asio-grpc](https://github.com/Tradias/asio-grpc) >= `3.3.0`
+* [JSON for Modern C++](https://json.nlohmann.me/) >= `3.11.0`
+* [stb](https://github.com/nothings/stb) >= `f0569113c93ad095470c54bf34a17b36646bbbb5`
+
+---
+
+## CMake options
+
+The build can be customized with several **CMake options**:
+
+### `QUITE_BUILD_REMOTE_MANAGER`
+
+- **Default:** `ON`
+- **Description:** Builds the remote-manager application.
+- **Introduced dependencies:**
+    - [CLI11](https://cliutils.github.io/CLI11/book/) ≥ `2.4.0`
+
+---
+
+### `QUITE_BUILD_TEST_API`
+
+- **Default:** `ON`
+- **Description:** Builds the C++ testing API.
+
+---
+
+### `QUITE_BUILD_PYTHON_TEST_API`
+
+- **Default:** `ON`
+- **Description:** Builds the Python testing API module.
+- **Dependencies:** Requires `QUITE_BUILD_TEST_API=ON`.
+- **Introduced dependencies:**
+    - [pybind11](https://pybind11.readthedocs.io/en/stable/) ≥ `3.0.0`
+
+See [Python Usage](python-usage.md) for details.
+
+---
+
+### `QUITE_BUILD_PROBE_QT`
+
+- **Default:** `ON`
+- **Description:** Builds the Qt probe.
+- **Introduced dependencies:**
+    - [Qt](https://www.qt.io/) ≥ `6.5.0`
+
+---

docs/getting-started.md

@@ -0,0 +1,83 @@
+# Getting Started
+
+## Introduction
+
+**quite** is an end-to-end testing framework for Qt applications.
+
+It provides a simple API that you can use from **C++** or **Python**, while still letting you choose your preferred test framework (e.g. GoogleTest, pytest, Catch2, etc.).
+
+With quite, you can:
+
+- Stimulate your application (e.g. trigger UI actions).
+- Capture screenshots of controls.
+- Query properties from your application.
+
+To use quite, you’ll need to install two parts:
+
+1. **The Probe** – code injected into your Application Under Test (AUT).
+2. **The Test API** – the library you use in your test code to talk to the AUT.
+
+[:material-arrow-right: Probe Installation](#probe)
+[:material-arrow-right: Test API Installation](#test-api)
+
+!!! info "Minimum language and Qt version"
+    * Only **Qt 6.5** and onward is supported.
+    * **C++23** required to compile the project.
+    * **C++17** required to consume the testing API.
+    * **gcc-13** required to compile the project.
+    * currently only tested with gcc and linux.
+
+---
+
+## Installation
+
+### Probe
+
+The probe runs **inside your AUT** and sets up a gRPC server that quite uses to communicate with your application.
+
+You’ll need to add the probe to your application during build time.
+
+#### Install with vcpkg
+
+```bash
+vcpkg install quite[probeqt]
+```
+
+### Install with CPM.cmake
+
+```cmake
+cpmaddpackage(
+  NAME quite
+  URI "gh:mathisloge/[email protected]"
+  OPTIONS "QUITE_BUILD_PROBE_QT ON"
+)
+```
+
+## Test API
+
+The test API is what your test code uses to talk to the AUT’s probe.
+
+You can install it for C++ or Python.
+
+### vcpkg
+
+```bash
+vcpkg install quite[testapi]
+```
+
+### CPM.cmake
+
+```cmake
+cpmaddpackage(
+  NAME quite
+  URI "gh:mathisloge/[email protected]"
+  OPTIONS "QUITE_BUILD_TEST_API ON"
+)
+
+```
+
+### Python
+
+```bash
+pip3 install https://github.com/mathisloge/quite/archive/refs/tags/v1.3.0.zip
+```

docs/index.md

@@ -1,3 +1,5 @@
 # Home
+**quite** enables reliable end-to-end testing for qt applications.
 
-For full documentation visit [github.com/mathisloge/quite](https://github.com/mathisloge/quite).
+[GET STARTED](getting-started.md){ .md-button .md-button--primary }
+[Github](https://github.com/mathisloge/quite){ .md-button target="_blank" rel="noopener" }

docs/probe-setup.md

@@ -0,0 +1,31 @@
+# Probe setup
+
+Currently only a compile time link setup is supported.
+However in the future a `LD_PRELOAD` step is supported.
+See [#51](https://github.com/mathisloge/quite/issues/51).
+
+## C++
+
+```cmake
+
+find_package(quite CONFIG REQUIRED)
+
+add_executable(myApp)
+
+target_link_libraries(myApp PRIVATE
+    quite::probe_qt
+)
+```
+
+```cpp
+#include <quite/probe_qt/probe_qt.hpp>
+
+int main()
+{
+    auto& probe = quite::probe::setup_qt_probe(quite::GrpcServer{.server_address = "unix:///tmp/grpc_probe.sock"});
+
+    // normal application setup
+    // no more to do
+}
+
+```