Skip to content

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 ​

bash
# All Rust tests
cargo test --workspace

# Frontend unit tests
npm --prefix apps/config/ui test

Parallel 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:

bash
cargo test -p zonedeck-core -- --test-threads=1

Rust 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 PID field, and round-trip serialisation of regex rules;
  • Clamping of click counts and the multi-click interval;
  • Round-tripping of Command / Response and their snake_case tags;
  • Language tag parsing and preference normalisation (zh-Hant → zh-TW, untranslated languages falling back to auto, 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):

AreaWhat is tested
Window enumeration / hiding / showingRound trip against a real window
Hotkey parsingString → RegisterHotKey parameters
Hotkey interceptionPure keyboard-hook decision logic: modifiers must match exactly, holding fires once, a swallowed press also swallows its release
Single-instance mutexNamed mutex
Named pipeServer send/receive; the back-to-back reconnect race (a client that connects before ConnectNamedPipe must still be served)
Process freezingSuspending / resuming a real child process
Power statsA real child process taken through freezing / efficiency mode, checked against the file on disk; reset over IPC
MutingThe Core Audio COM path; session matching and bookkeeping decisions
Media pausingMatching an SMTC AUMID against an image path
HideControllerMock injection verifying the muting / freezing / media-pausing orchestration
StartupPlain registry-key logic + a real schtasks accepting the task XML
Crash logsWriting / rotation / the panic hook
Crash recoverySnapshot persistence round trip + mock recovery orchestration
Icon encodingCRC32 / Adler-32 / base64 known vectors + PNG structure parsing + extraction from a real explorer.exe
End-to-end IPCIPC and crash-recovery tests driving a real agent through PipeClient
String catalogEvery 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 common or the frontend lib/, with unit tests.
  • Integration tests for system behaviour: for windows / COM / pipes, create real resources and verify a round trip, using mocks (the Effects / WindowManager traits) to isolate side effects where needed.
  • Make sure the tests pass locally before committing; see the contribution guide.