v0.2.0 (13/N): qmltestrunner harness + CI wiring + close out v0.2.0 plan

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_<feature>.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) <noreply@anthropic.com>

.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 \

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 <destination>` 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=<minutes>`. 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=<n>` 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_<feature>.qml`. Wired into `make qmltest` (skeleton + example/todo) and into the Gitea Actions `Quality` job after qmllint.
 
 ### Changed
 

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.<timestamp>.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)
 

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

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()

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)

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 <QtQuickTest/quicktest.h>
+
+QUICK_TEST_MAIN(qml_unit_tests)

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_<feature>.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")
+    }
+}

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