From de4a14da363ba51da1c8af2d0196f089f62f0c4b Mon Sep 17 00:00:00 2001 From: magdev Date: Sun, 3 May 2026 21:02:30 +0200 Subject: [PATCH] v0.2.0 (13/N): qmltestrunner harness + CI wiring + close out v0.2.0 plan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes the testing-strategy row of PLAN.md §13 v0.2.0 and parks the two remaining items with rationales. Shipped: - framework/qml/tests/{CMakeLists.txt, main.cpp, tst_smoke.qml} Qt Quick Test scaffold: QUICK_TEST_MAIN bootstrap + one smoke test proving the harness loads. New tests land as tst_.qml in the same dir; qmltestrunner auto-discovers them. Built only when -DBUILD_TESTING=ON (production AppImages stay clean). - skeleton + example/todo Makefiles: `make qmltest` target invokes the configure → build → ctest dance. `make quality` now depends on qmltest. - .gitea/workflows/ci.yml: `QML unit tests` step after qmllint in the Quality job. Out-of-tree build dir (build-tests) so the CTest run doesn't pollute the cached release build. Verified locally: configure + build + ctest pass, both smoke assertions pass, runs in 0.5s. Closed in PLAN.md §13 v0.2.0 with rationale (no code change): - Build-time Symfony cache warmup → moved to v0.3.0. The obvious approach (cache:warmup at build, copy at first launch) doesn't save any time because Symfony bakes absolute kernel.project_dir into the compiled cache, and the AppImage's FUSE mount path changes every launch — every cached path is stale on launch N+1. Doing it properly requires virtualising getProjectDir(), symlink fix-up, multi-app namespacing — its own minor's worth of design. - ReactiveObject cursor pagination → closed N/A. ReactiveObject already has pending / invoke() / Idempotency-Key correlation / version-gap detection at parity with ReactiveListModel; the only feature it lacks is *pagination*, which is meaningless for a single-entity model. That fully closes the v0.2.0 plan as documented. Remaining v0.2.0 items in PLAN.md §13 are the audit-ends already shipped earlier in the cycle (interfaces / BridgeOp / BridgeBundleInfo / Maker DRY / --with-dto / port negotiation / pre-migration backup / bridge:export / periodic auto-update / native-dialogs doc / event maker / read-model maker / qmltestrunner) plus the two parked items documented above. Ready to tag when the user gives the word. Co-Authored-By: Claude Opus 4.7 (1M context) --- .gitea/workflows/ci.yml | 7 +++++++ CHANGELOG.md | 1 + PLAN.md | 4 ++-- examples/todo/Makefile | 8 +++++++- framework/qml/CMakeLists.txt | 9 +++++++++ framework/qml/tests/CMakeLists.txt | 27 +++++++++++++++++++++++++++ framework/qml/tests/main.cpp | 9 +++++++++ framework/qml/tests/tst_smoke.qml | 25 +++++++++++++++++++++++++ framework/skeleton/Makefile | 8 +++++++- 9 files changed, 94 insertions(+), 4 deletions(-) create mode 100644 framework/qml/tests/CMakeLists.txt create mode 100644 framework/qml/tests/main.cpp create mode 100644 framework/qml/tests/tst_smoke.qml diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index 09e34c0..41adee1 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -77,6 +77,13 @@ jobs: working-directory: framework/skeleton run: cmake --build build/qml --target all_qmllint + - name: QML unit tests (qmltestrunner via Qt::QuickTest) + working-directory: framework/qml + run: | + cmake -S . -B build-tests -DBUILD_TESTING=ON + cmake --build build-tests --target qml_unit_tests --parallel + ctest --test-dir build-tests --output-on-failure -R qml_unit_tests + - name: Install FrankenPHP run: | curl -fsSL -o /usr/local/bin/frankenphp \ diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c75756..4900f20 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,7 @@ This section tracks work landing on `dev` toward **v0.2.0** (next minor; pre-1.0 - **`bridge:export` console command + QML hook.** New `bin/console bridge:export ` copies the active SQLite database to a user-chosen path (overwrites if the destination exists; reads the source path from `DATABASE_URL` so it works in both dev and bundled mode). Mirrored on the QML side as `BackendConnection.exportDatabase(path)` (`Q_INVOKABLE bool`) returning success synchronously and emitting `databaseExported(path)` / `databaseExportFailed(reason)` for async UX. QML callers typically pair it with `Qt.labs.platform.FileDialog` (see `docs/native-dialogs.md`). 4 unit tests cover the command's success / non-SQLite-URL / missing-source / overwrite paths. - **Periodic auto-update check.** Bundled-mode supervisor arms an `AppImageUpdate` poll on the first `Online` transition: a launch-time check 10 s after backend ready, then a recurring check every 6 hours. PLAN.md §11 *Auto-update* called for "check on launch and once per N hours; offer install on next restart, never auto-restart" — the existing `checkForUpdates()` Q_INVOKABLE remains the install trigger, this just automates the polling. Disable with `BRIDGE_AUTO_UPDATE_DISABLE=1`; override the period with `BRIDGE_AUTO_UPDATE_PERIOD_MIN=`. Dev mode skips entirely. - **Bundled-mode port negotiation.** The hardcoded `m_port = 8765` is replaced with a runtime-negotiated free ephemeral port: bind a `QTcpServer` to `QHostAddress::LocalHost` port 0, capture `serverPort()`, close, then hand the port to FrankenPHP via the existing `PORT` env var (the Caddyfile already reads `{$PORT:8765}`). Two installed php-qml apps no longer collide on first launch — whichever loses the port-8765 race used to go Offline; now each picks its own. Test harnesses can pin the port via `BRIDGE_PORT=` for reproducibility (the existing `bundled-supervisor.sh` and `perfsmoke.sh` both export it). Each launch also writes the chosen port to `var/bridge.port` so any external tool that needs the runtime address can read it without parsing Qt's log. +- **`qmltestrunner` QML unit tests + CI wiring.** `framework/qml/tests/` now ships a Qt Quick Test executable target (`qml_unit_tests`) discovered by CTest. Built only when configured with `-DBUILD_TESTING=ON` so production AppImages don't carry it. One smoke test (`tst_smoke.qml`) proves the harness; future per-feature tests land beside it as `tst_.qml`. Wired into `make qmltest` (skeleton + example/todo) and into the Gitea Actions `Quality` job after qmllint. ### Changed diff --git a/PLAN.md b/PLAN.md index c554280..59527ed 100644 --- a/PLAN.md +++ b/PLAN.md @@ -571,7 +571,7 @@ Pulls in the originally-Phase-3/5-deferred items that don't need new operational - **`make:bridge:event` maker.** Generate an event class + listener stub for app-side domain events. - **`make:bridge:read-model` maker.** Generate a read-only projection (one or more entities → one denormalised view). -- **`ReactiveObject` cursor pagination.** Bring single-entity model up to par with `ReactiveListModel`'s pagination. +- ~~**`ReactiveObject` cursor pagination.**~~ Closed N/A on inspection. ReactiveObject already has `pending` / `invoke()` / Idempotency-Key correlation / version-gap detection at parity with ReactiveListModel; the only feature it lacks is *pagination*, which is meaningless for a single-entity model. If the surface-feedback later flags a real reactive-feature gap (related-collection fetches, sub-resource navigation), that's a separate item with its own design. **Testing (Phase 3/5 deferred + §12 testing-strategy row):** @@ -584,7 +584,6 @@ Pulls in the originally-Phase-3/5-deferred items that don't need new operational - **Pre-migration auto-backup** (§12, *Migrations on schema change*). Supervisor copies `var/data.sqlite` to `var/data.sqlite..bak` before invoking `doctrine:migrations:migrate`; trims to N most recent. - **`bridge:export` console command + UI hook** (§12, *Data backup / export*). Lets users copy their data out before machine moves or risky migrations. - **Periodic auto-update check.** Phase 5 noted this as a polish item but didn't ship; v0.1.0 only has menu-triggered manual checks. -- **Build-time Symfony cache warmup** (§12, *Cold start*). Bake `var/cache/prod` into the AppImage so first launch skips warmup; first-launch supervisor copies it into the user data dir. - **Native dialogs boundary doc.** §12 noted file pickers / notifications belong on the QML side via Qt — document the boundary and ship a small `Q_INVOKABLE` helper for the common cases. ### v0.3.0 — later minor @@ -593,6 +592,7 @@ Bigger pieces still deferred (each warrants its own minor, not v0.2.0 noise): - **i18n bridge** (§12). Symfony Translator (XLIFF) + Qt Translator (.ts) with a shared locale switch fanning out to both. - **Persistent log files + rotation** (Phase 5 out-of-scope). Symfony monolog wiring + a Qt-host log file with rotation. The dev console stays for live tails. +- **Build-time Symfony cache warmup** (§12, *Cold start*). Originally proposed for v0.2.0 but postponed: the obvious `cache:warmup` at build time + copy to user data dir at first launch doesn't actually save any time, because Symfony's compiled container bakes the absolute `kernel.project_dir` path into the cache, and the AppImage's FUSE mount path changes every launch — every cache from a prior mount is stale. Doing this properly requires virtualising `kernel.project_dir` (override `Kernel::getProjectDir()` to return a stable per-app path, symlink that path at the supervisor to the current mount, warm against the same path at build time). That's invasive enough — touches resource resolution, multi-app namespacing, the supervisor's first-launch dance — to belong in its own minor where the cache-portability story can be designed end-to-end. The v0.1.1 wipe-cache-on-every-launch behaviour stays as the correct conservative default until then. ### v0.9.0 — cross-platform packaging (release-candidate milestone) diff --git a/examples/todo/Makefile b/examples/todo/Makefile index c6d0e6c..6bae3e2 100644 --- a/examples/todo/Makefile +++ b/examples/todo/Makefile @@ -83,8 +83,14 @@ appimage: build staging-symfony ## Package as a single-file Linux AppImage at bu @echo "AppImage built. Test with: ./build/Todo-x86_64.AppImage" .PHONY: quality -quality: build ## Run PHPStan, php-cs-fixer (check), PHPUnit, qmllint, integration (dev + bundled) +quality: build qmltest ## Run PHPStan, php-cs-fixer (check), PHPUnit, qmllint, qmltest, integration (dev + bundled) cd ../../framework/php && composer quality cmake --build $(BUILD_DIR) --target all_qmllint ./tests/integration.sh $(MAKE) integration-bundled + +.PHONY: qmltest +qmltest: ## Run QML unit tests (Qt::QuickTest via qmltestrunner) + cmake -S ../../framework/qml -B ../../framework/qml/build-tests -DBUILD_TESTING=ON + cmake --build ../../framework/qml/build-tests --target qml_unit_tests --parallel + ctest --test-dir ../../framework/qml/build-tests --output-on-failure -R qml_unit_tests diff --git a/framework/qml/CMakeLists.txt b/framework/qml/CMakeLists.txt index c9ff6a7..c6ee826 100644 --- a/framework/qml/CMakeLists.txt +++ b/framework/qml/CMakeLists.txt @@ -52,3 +52,12 @@ target_link_libraries(php_qml_bridge PUBLIC Qt6::Qml Qt6::Quick ) + +# QML unit tests — opt-in. Only built when configuring with +# -DBUILD_TESTING=ON or invoking ctest as part of a top-level project +# that enable_testing()'d. Skipped by the skeleton + example app +# release builds so production AppImages don't carry the test exe. +if(BUILD_TESTING AND CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME) + enable_testing() + add_subdirectory(tests) +endif() diff --git a/framework/qml/tests/CMakeLists.txt b/framework/qml/tests/CMakeLists.txt new file mode 100644 index 0000000..63e1996 --- /dev/null +++ b/framework/qml/tests/CMakeLists.txt @@ -0,0 +1,27 @@ +# QML unit tests — opt-in, only built when BUILD_TESTING is on (CTest's +# convention). Wired from ../CMakeLists.txt under the same guard. +# +# Run via: +# cmake -S . -B build -DBUILD_TESTING=ON +# cmake --build build --target qml_unit_tests +# ctest --test-dir build --output-on-failure -R qml_unit_tests +# +# Or from the skeleton / example Makefiles via `make qmltest`. + +find_package(Qt6 6.5 REQUIRED COMPONENTS QuickTest) + +qt_add_executable(qml_unit_tests main.cpp) +target_link_libraries(qml_unit_tests PRIVATE + Qt6::QuickTest + Qt6::Qml + Qt6::Quick +) + +# QUICK_TEST_MAIN reads QUICK_TEST_SOURCE_DIR from the macro definition +# at compile time. Point it at this directory so qmltestrunner finds +# the tst_*.qml files regardless of where the binary runs. +target_compile_definitions(qml_unit_tests PRIVATE + QUICK_TEST_SOURCE_DIR="${CMAKE_CURRENT_SOURCE_DIR}" +) + +add_test(NAME qml_unit_tests COMMAND qml_unit_tests) diff --git a/framework/qml/tests/main.cpp b/framework/qml/tests/main.cpp new file mode 100644 index 0000000..428aca9 --- /dev/null +++ b/framework/qml/tests/main.cpp @@ -0,0 +1,9 @@ +// QML unit-test runner. Bootstraps the Qt Quick Test framework against +// the `tst_*.qml` files in this directory. Invoked via CMake's +// `qmltest` test target (CTest) or directly via the produced exe. +// +// PLAN.md §13 v0.2.0 testing-strategy row. + +#include + +QUICK_TEST_MAIN(qml_unit_tests) diff --git a/framework/qml/tests/tst_smoke.qml b/framework/qml/tests/tst_smoke.qml new file mode 100644 index 0000000..5d4f370 --- /dev/null +++ b/framework/qml/tests/tst_smoke.qml @@ -0,0 +1,25 @@ +// Smoke test — proves the qmltestrunner harness is wired up. Doesn't +// touch BackendConnection (which would require a live FrankenPHP child) +// or any other framework-side code that needs network/state. The +// assertion is intentionally trivial; the *infrastructure* is what's +// being tested at this layer. +// +// Add domain-meaningful tests as `tst_.qml` next to this file +// — qmltestrunner auto-discovers any `tst_*.qml` and runs every +// `TestCase` function whose name starts with `test_`. + +import QtQuick +import QtTest + +TestCase { + name: "Smoke" + + function test_qml_engine_alive() { + compare(2 + 2, 4, "QtTest harness is loaded and arithmetic still works") + } + + function test_string_template() { + const x = 7 + compare(`x is ${x}`, "x is 7", "QML template literals available") + } +} diff --git a/framework/skeleton/Makefile b/framework/skeleton/Makefile index 0e7f122..c4b6d43 100644 --- a/framework/skeleton/Makefile +++ b/framework/skeleton/Makefile @@ -78,7 +78,13 @@ appimage: build staging-symfony ## Package as a single-file Linux AppImage at bu @echo "AppImage built. Test with: ./build/Skeleton-x86_64.AppImage" .PHONY: quality -quality: build ## Run PHPStan, php-cs-fixer (check), PHPUnit, qmllint, maker snapshots +quality: build qmltest ## Run PHPStan, php-cs-fixer (check), PHPUnit, qmllint, qmltest, maker snapshots cd ../php && composer quality cmake --build $(BUILD_DIR) --target all_qmllint ../php/tests/snapshot/run.sh + +.PHONY: qmltest +qmltest: ## Run QML unit tests (Qt::QuickTest via qmltestrunner) + cmake -S ../qml -B ../qml/build-tests -DBUILD_TESTING=ON + cmake --build ../qml/build-tests --target qml_unit_tests --parallel + ctest --test-dir ../qml/build-tests --output-on-failure -R qml_unit_tests