# 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
```