Testing Guidelines

Testing Doctrine

Two types of tests are preferred:

1. True integration tests — use real runtimes, real filesystems, real network calls. No mocks, stubs, or fakes. These prove the system works end-to-end.
2. Unit tests on pure/isolated logic — test pure functions or well-isolated modules where inputs and outputs are clear. No mocks needed because the code has no external dependencies.

Unit tests are located colocated with the source they test as ".test.ts[x]" files.

Integration tests are located in tests/, with these primary harnesses:

• tests/ipc — tests that rely on the IPC and are focussed on ensuring backend behavior.
• tests/ui — frontend integration tests that use the real IPC and happy-dom Full App rendering.
• tests/e2e - end-to-end tests using Playwright which are needed to verify browser behavior that can't be easily tested with happy-dom.

Additionally, we have stories in src/browser/stories that are primarily used for human visual