From c396853a9290314ab657ac4414a21f26dc1fa6d5 Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Thu, 13 Aug 2026 10:03:29 +0200 Subject: docs: never run test binaries without the offscreen platform tests/CMakeLists.txt sets QT_QPA_PLATFORM=offscreen for ctest only, so a binary invoked directly inherits the desktop's setting and throws real windows onto the user's screen. Each test function builds its own MainWindow, so one direct run of test_mainwindow flashes over a hundred windows. Launching the application unasked is the same problem: running it is a hand test and belongs to the user. --- CLAUDE.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 152b9e7..67c0794 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,9 +10,27 @@ cmake --build build ctest --test-dir build --output-on-failure ``` -Run a single test binary directly for a tighter loop: `./build/tests/test_keymap`. +Run a single test binary directly for a tighter loop, **always with the +offscreen platform**: + +```bash +QT_QPA_PLATFORM=offscreen ./build/tests/test_keymap +``` + Or by ctest name (the name is the suffix, not the binary): `ctest --test-dir build -R keymap`. +**Never run a test binary without `QT_QPA_PLATFORM=offscreen`, and never launch +`./build/src/qtmaildir` unasked.** `tests/CMakeLists.txt` sets that variable for +ctest only, so a binary invoked directly inherits the desktop's own setting +(`wayland;xcb` here) and throws real windows onto the user's screen. Each test +function builds its own `MainWindow`, so one direct run of `test_mainwindow` +flashes over a hundred windows across the desktop. This is not cosmetic: the +user has asked for it to stop, having been given a headache by it. + +The same applies to the application. Running it is a hand test and belongs to +the user; ask rather than launching it, and when a change genuinely needs +looking at, say what to look for and let them run it. + Adding a test: create `tests/test_.cpp` and add `add_qtmaildir_test()` to `tests/CMakeLists.txt`. That function links `qtmaildir_lib` and `Qt6::Test` and registers the test. Fixture-driven tests get `FIXTURE_DIR` via `target_compile_definitions` (see -- cgit v1.2.3