Testing and Quality

Testing and quality

Two things keep OpenNote reliable: a layered test plan, and a quality gate called CHECKS that every file change must pass. The plan is in section 6 of the development plan, and CHECKS is in docs/CHECKS.md.

Test layers

Each layer arrives with the phase that needs it. Today, main runs the CHECKS tests, the UI unit tests, and the Rust tests.

Layer	Tools	What it covers
Unit	cargo test, Vitest	Functions and modules in isolation, on every commit
Property-based	proptest, fast-check	Random documents and edits. Save and reload must give identical results.
Component	Vitest with Testing Library, axe-core	Each interface control, including accessibility rules
End-to-end	WebdriverIO with tauri-driver	The real app on Windows, key tasks from start to finish
Golden image	Playwright screenshots, PDF rendering	Layout, pagination, PDF export, charts, and math
Performance	Custom benchmarks	Every budget below
Fuzzing	cargo-fuzz	The file reader and importers never crash on bad input
Soak	Scripted random editing	Memory leaks, slowdowns, and crashes over time
Crash safety	Kill-during-save harness	No page is ever damaged or lost
Manual	Checklists	Pen feel, screen readers, and real devices

Every bug fix adds a test that failed before the fix. Performance tests fail the build if a result is more than 10% worse than the last release.

Performance budgets

A feature that breaks a budget on the reference laptop doesn't ship. The reference laptop has 4 cores, 8 GB of memory, integrated graphics, and a 1080p screen at 125% scaling.

Measure	Budget
Pen to screen	Stroke drawn in the next frame, and 25 ms or less end to end on a 60 Hz screen
Typing	A key press shows within 16 ms
Feedback	Any tap, click, or key shows a response within 50 ms
Frame rate	60 frames per second, never two dropped frames in a row
Page open	150 ms for a typical page
Search	Results within 100 ms across 10,000 pages
Start-up	Window within 1 second
Memory	Under 400 MB with a 1,000-page notebook open
Crash safety	At most 1 second of work lost

The pen and typing budgets are still under review. See Phase 1 spike results.

The CHECKS gate

CHECKS runs on your machine before each commit, and again in CI on every push and pull request. Errors block the commit and fail CI. Warnings are review notes.

Rule	Covers
hygiene	Trailing spaces, line endings, leaked keys, and large files
spelling	American spelling in docs and code comments
grammar	Serial commas, articles, repeated words, and similar slips
ai-markers	Chatbot leftovers, stock AI phrases, and formulaic lists
redundancy	Wordy phrases and repeated sentences
length	Long sentences, paragraphs, sections, and code lines
readability	Reading grade per section, and acronyms defined on first use
usability	One title, no skipped heading levels, working links, and alt text
modifiability	File and function length, nesting, and TODOs without an issue link
brand-consistency	UI code must use design tokens, not raw values
layout	SVG graphics checked in a headless browser
brand-tokens	Both themes match, contrast targets are met, and motion stays under 400 ms

Run it with these commands:

npm run checks        # files changed since origin/main
npm run checks:all    # every file
npm run checks:fix    # apply safe automatic fixes

To suppress a finding when a rule is wrong, put <!-- checks-disable-next-line <rule-id>: <reason> --> on the line before it. A suppression without a reason is itself an error.

Before you push

npm run tokens:check
npm run typecheck
npm run lint
npm run format:check
npm test
npm run checks

If you changed Rust code, also run npm run app:build, then cargo fmt --all -- --check, cargo clippy --workspace --all-targets -- -D warnings, and cargo test --workspace. CI treats every Clippy warning as an error.

Related pages

• Development process
• Releasing, which adds the release checklist
• Developer guide