diff options
Diffstat (limited to 'docs/testing.md')
| -rw-r--r-- | docs/testing.md | 156 |
1 files changed, 156 insertions, 0 deletions
diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 0000000..d01b82c --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,156 @@ +# Testing and examples + +Configure isolated Linux display-server integration tests with Weston and +Xwayland installed: + +```sh +meson setup build-test -Dintegration_tests=true +meson test -C build-test --print-errorlogs +``` + +The harness starts and cleans up its own servers. It checks explicit requests, +automatic selection, fallback, both backends in one process, frame lifetimes, +callback copying, clipboard ownership, and timers. It also runs the beginner +and tablet examples on both backends. On macOS the option enables native window, +input ownership, keyboard/text/scroll, cursor, tablet, and example tests; these +require a desktop session. Linux results do not verify Cocoa behavior. + +For memory/undefined-behavior checks use a separate build: + +```sh +meson setup build-sanitize -Db_sanitize=address,undefined -Dintegration_tests=true +meson test -C build-sanitize --print-errorlogs +``` + +Default tests need no desktop connection. C++ header coverage is built when a +C++ compiler is available. On Linux and macOS, the shared-export test ensures +only installed API declarations are exported. Test disabled-backend configurations separately with +`-Dwayland=disabled` or `-Dx11=disabled`; the combined integration harness needs +both backends. + +Keyboard tests check physical identities, distinct keypad/modifier keys, layout +labels, Shift/Caps Lock, shortcut text suppression, AltGr, dead-key composition, +repeat, and composition reset. The X11 integration test changes and restores +the isolated server's keymap to verify that labels change while physical keys +retain their identity. The X11 text fallback is also checked without an input +method, including Latin-1, Cyrillic, and non-BMP characters encoded as UTF-8. +Scroll tests cover both axes, fractional Wayland offsets, +duplicate protocol representations, and X11 core/XInput wheel directions. +Cocoa integration tests cover UTF-16 labels, modifier-only events, native text +commit routing, and diagonal precise scrolling. Native IME interaction and +hardware gestures still need testing on the target desktop. +Clipboard tests cover Latin-1 interoperability, empty transfers, and rejection +of malformed UTF-8 on Linux. + +## Cocoa validation + +On macOS 14 or newer, use a logged-in desktop session with a Metal-capable +device. Configure `-Dintegration_tests=true`, compile, and run the full suite. +Cross-compiling with an Apple SDK checks compilation and linking; run +`meson test -C build-macos public-exports` to check the dylib's exports on the +build machine. A cross file should provide an `nm` that can read Mach-O, such +as `llvm-nm`. These checks do not execute the native window and input tests. + +To move an already compiled, unsanitized Cocoa suite to another Mac without +rebuilding it: + +```sh +python3 tests/helpers/package_cocoa_tests.py build-macos cocoa-tests.tar.gz +``` + +On the matching Mac, extract the archive and run: + +```sh +tar -xzf cocoa-tests.tar.gz +python3 yasl-cocoa-tests/run.py +``` + +The bundle includes the dylib, every executable test registered by Meson, and +the license. The build-machine export check is separate. The runner checks file +hashes, enforces each test's timeout, saves output under `logs/`, and writes +`results.json`. A nonzero exit means validation failed. `--list` lists the +bundled tests without running them. Use Python 3.8 or newer and a bundle matching +its architecture; Apple Silicon uses `aarch64`, Intel uses `x86_64`. + +## Tablet drawing example + +Build and run the same C application on Wayland, X11, or Cocoa: + +```sh +meson setup build +meson compile -C build +./build/yasl-tablet +./build/yasl-tablet --backend wayland +./build/yasl-tablet --backend x11 +# On macOS: +./build/yasl-tablet --backend cocoa +``` + +Draw with the pen tip: pressure controls brush width. Flip to the eraser to +remove ink. The window shows the selected backend, tool, contact state, raw +pressure (0..65535), percentage, and tilt in degrees, with a live pressure bar, +brush outline, and tilt vector. The system cursor is hidden so the brush overlay +serves as the drawing cursor. Mouse drawing uses a fixed width. Press C or +Space to clear and Escape to quit. Resizing and display scale changes preserve +the drawing. `--smoke-test` presents one frame and exits for automated checks. + +[`examples/tablet.c`](../examples/tablet.c) includes only `<yasl/yasl.h>` and the C +standard library. It uses CPU framebuffers and `yasl_surface_input_poll()` on +every backend. Tablet events arrive as `YASL_INPUT_MOUSE`, distinguished by +`mouse.device == YASL_PTR_DEV_PEN` or `YASL_PTR_DEV_ERASER`; `mouse.pen` contains +pressure and signed tilt. Button 0 is tip contact on every backend. Track tip +press/release events: zero pressure alone does not mean release. Hover and side +buttons do not paint, and focus loss, leave, or `YASL_INPUT_RESET` cancels a stroke. +Stationary pressure changes arrive as motion events and update the brush too. + +The example uses portable physical keys: C and Space clear, Escape exits. +Letter names describe US positions, so the clear key follows the C position +when the user selects another layout. + +`YASL_CAP_TABLET` indicates backend/protocol support, not whether a tablet is +plugged in or which axes it has. Missing axes are zero. Wayland requires the +compositor's `zwp_tablet_manager_v2`; X11 requires XInput 2 and driver-provided +`Abs Pressure`/`Abs Tilt X`/`Abs Tilt Y` valuators. Cocoa handles both tablet mouse +subtypes and native tablet point/proximity events. X11 identifies erasers by +the Wacom tool property or the driver's device name. Hardware and driver +support determine which readings are available. The example displays a message +when the server has no tablet protocol and still allows mouse drawing. + +The test suite checks synthetic Wayland/XInput samples and the drawing behavior +without hardware, including pressure-only changes, sparse axes, eraser input, +hover, release, reset, and scale changes. Linux integration tests launch the +example on isolated Wayland and X11 servers; macOS integration tests also check +Cocoa tablet event translation. Physical tablet testing is still needed to +validate a particular device/driver combination. + +For an end-to-end X11 pressure test without hardware, install Xorg's `dummy` +video driver and `inputtest` input driver, then run: + +```sh +meson configure build -Dx11_tablet_tests=true +meson test -C build tablet-x11-native --print-errorlogs +``` + +This starts an isolated Xorg server with virtual pen and eraser devices, sends +real driver samples, checks YASL's shared events through the example, and verifies +its presented window pixels. It checks stationary pressure changes, release +without valuators, and eraser identification through the driver's tool property. +The test disables automatic physical input/GPU attachment and cleans up its +server. Set `YASL_XORG_MODULE_PATH` to a comma-separated module search path if +the test drivers are outside Xorg's default directories. + +## Benchmarks + +`yasl-benchmark` measures queue, timer, and surface-operation costs. Results +depend on the build, backend, and display server; they do not measure confirmed +screen presentation latency. + +```sh +# Run via meson test runner +meson test -C build --benchmark --verbose + +# Or invoke the executable directly +ninja -C build tests/yasl-benchmark +./build/tests/yasl-benchmark +``` + |