Testing strategy
ZoneDeck is covered by several layers of tests, from pure-logic unit tests to system-level integration tests. CI runs the whole suite on every PR and push.
Running the tests
# All Rust tests
cargo test --workspace
# Frontend unit tests
npm --prefix apps/config/ui testParallel core tests can crash on COM
Some zonedeck-core tests initialise COM (the muting path, for example) and can crash when run in parallel. When that happens, run them single-threaded:
cargo test -p zonedeck-core -- --test-threads=1Rust coverage
zonedeck-common
Pure-logic unit tests for the models, configuration, matching and protocol, plus integration tests for reading and writing the configuration file. For example:
- Configuration parsing and defaults, and migration of old configurations (flat bindings → window rules, old mouse switches → click triggers);
- Compatibility of the uppercase
PIDfield, and round-trip serialisation of regex rules; - Clamping of click counts and the multi-click interval;
- Round-tripping of
Command/Responseand their snake_case tags; - Language tag parsing and preference normalisation (
zh-Hant→zh-TW, untranslated languages falling back toauto, and so on); - Data folder resolution and migration (portable copies staying in place / installed copies using the user folder / falling back with a stated reason when not writable / recognising the marker file and the uninstaller / the old configuration being moved across, an original that cannot be deleted, an existing config at the destination not being overwritten);
- Atomicity of configuration writes (a failed write neither truncates the previous file nor leaves a temporary one behind, and the error names the path).
zonedeck-core
Integration tests of system behaviour (mostly creating real resources and verifying a round trip):
| Area | What is tested |
|---|---|
| Window enumeration / hiding / showing | Round trip against a real window |
| Hotkey parsing | String → RegisterHotKey parameters |
| Hotkey interception | Pure keyboard-hook decision logic: modifiers must match exactly, holding fires once, a swallowed press also swallows its release |
| Single-instance mutex | Named mutex |
| Named pipe | Server send/receive; the back-to-back reconnect race (a client that connects before ConnectNamedPipe must still be served) |
| Process freezing | Suspending / resuming a real child process |
| Power stats | A real child process taken through freezing / efficiency mode, checked against the file on disk; reset over IPC |
| Muting | The Core Audio COM path; session matching and bookkeeping decisions |
| Media pausing | Matching an SMTC AUMID against an image path |
| HideController | Mock injection verifying the muting / freezing / media-pausing orchestration |
| Startup | Plain registry-key logic + a real schtasks accepting the task XML |
| Crash logs | Writing / rotation / the panic hook |
| Crash recovery | Snapshot persistence round trip + mock recovery orchestration |
| Icon encoding | CRC32 / Adler-32 / base64 known vectors + PNG structure parsing + extraction from a real explorer.exe |
| End-to-end IPC | IPC and crash-recovery tests driving a real agent through PipeClient |
| String catalog | Every message non-empty in all three languages, English distinct from Chinese, placeholders consistent across languages |
About restricted environments
The schtasks startup integration tests may fail in restricted or unprivileged CI and sandbox environments. That is an environment limitation, not a functional regression; they should pass locally with the necessary privileges.
Frontend tests (vitest)
The frontend keeps its pure logic in ui/src/lib/, with matching vitest unit tests:
hotkey.test.js— hotkey parsing / formatting;pointer.test.js— mouse clicks / the multi-click interval;grouping.test.js— adding, removing and filtering window / process rules;theme.test.js— theme preference logic;i18n.test.js— language resolution, and key-set / placeholder alignment across the three catalogs.
The UI components (components/) stay thin; the complexity lives in the testable lib/.
Conventions for writing tests
- Prefer unit tests for pure logic: anything that can be extracted into a pure function belongs in
commonor the frontendlib/, with unit tests. - Integration tests for system behaviour: for windows / COM / pipes, create real resources and verify a round trip, using mocks (the
Effects/WindowManagertraits) to isolate side effects where needed. - Make sure the tests pass locally before committing; see the contribution guide.