Testing and CI
Run make check, make lint, make format-check, and make test before you open a pull request. They cover Svelte, TypeScript, Rust, formatting, and the generated IPC bindings, and they match what CI runs. Tests are lean and aimed at product behavior. The repository rule is to add no trivial tests and no tests for one-off scripts.
Commands
Section titled “Commands”Run everything from the repository root.
| Goal | Command |
|---|---|
| All type checks and the bindings drift check | make check |
| All tests | make test |
| All lint | make lint |
| Verify formatting | make format-check |
| Apply formatting | make format |
After frontend changes, run make frontend-check and make frontend-lint. After Rust changes, run make desktop-format, then make desktop-check and make desktop-lint.
Frontend
Section titled “Frontend”| Tool | Command | Notes |
|---|---|---|
| Bun test runner | make frontend-test or bun run test |
Regenerates bindings first, then runs bun test over tests/ |
svelte-check |
make frontend-check or bun run check |
Runs bun run bindings, svelte-kit sync, then svelte-check with tsconfig.json |
| ESLint | make frontend-lint |
Flat config, zero warnings allowed. It also enforces that Bits UI is imported only inside src/lib/components/ui |
| Prettier | make frontend-format and make frontend-format-check |
Svelte 5 plugin. Covers src, tests, config files, and config/*.jsonc |
| Knip | bun run check:unused |
Optional audit for unreachable files. Not part of CI |
Prettier and ESLint skip src/lib/generated/, because Specta owns that format.
| Tool | Command |
|---|---|
| Tests | make desktop-test (cargo test --manifest-path src-tauri/Cargo.toml) |
| Type check | make desktop-check (cargo check) |
| Clippy | make desktop-lint (cargo clippy --all-targets --all-features -- -D warnings) |
| Formatting | make desktop-format and make desktop-format-check |
Run a subset with a path filter, for example cargo test --manifest-path src-tauri/Cargo.toml licensing::.
Bindings check
Section titled “Bindings check”The IPC contract is owned by Rust, and src/lib/generated/bindings.ts is committed. make bindings-check runs the exporter into a temporary file and compares it with the committed file. It fails with a diff when they differ. Run make bindings and commit the result when a command, event, serialized type, or build-time JSONC value changes. Ordinary tests never rewrite source files. See Architecture.
Test layout
Section titled “Test layout”Frontend tests
Section titled “Frontend tests”tests/*.test.ts hold roughly two dozen focused tests. They exercise controllers and pure state modules, not rendered components. Controllers take an environment argument for IPC and event functions, so tests replace those at the boundary. Typical subjects are the capture controller and its status projection, configuration session behavior, History navigation, Profile and provider state, model catalog and picker state, licensing, notification and screen-capture permission handling, and the shortcut recorder.
Name a test after the behavior it covers. Prefer observable behavior over internals, and avoid mocks that replace so much of the system that the test stops exercising real code.
Rust tests
Section titled “Rust tests”Rust tests live next to the code in #[cfg(test)] modules, with a few larger suites in sibling files:
| Location | Covers |
|---|---|
config/controller_tests.rs, config/inference_transaction_tests.rs |
Transactional configuration, shortcut transitions, rollback, Profile and provider changes |
config/storage.rs, config_jsonc.rs, application_config.rs |
Parsing, defaults, unknown fields, JSONC rules, and validity of the build-time configuration |
inference/tests.rs, inference/params.rs |
Prompt rendering, options, and provider requests |
capture.rs, capture/backend.rs |
The capture pipeline with fake inference and clipboard, split-stage ordering, failure and cancellation paths, selection outcomes |
rendering/, clipboard/ |
Sanitization, style policy, image crops, plain text, clipboard payloads. See HTML output |
history.rs |
SQLite store, pruning limits, and tray menu |
licensing/commercial_tests.rs |
Offline evaluation and license lifecycle against a mock protocol |
local_models/ |
Catalog validity, download resume, checksum verification, and reservations |
Fixtures are in src-tauri/fixtures/. Use fakes at the platform boundary (CaptureBackend, ClipboardWriter, ShortcutRuntime, the secret store) instead of the real macOS APIs.
Native behavior still needs a manual check in the desktop app. Screen Recording permission, region selection and cancellation, global shortcuts, the system clipboard, and the native image picker cannot be validated by a browser preview or by unit tests.
Ignored and opt-in tests
Section titled “Ignored and opt-in tests”Tests marked #[ignore] need weights, a native GPU runtime, a network download, or credentials. cargo test skips them, and CI never runs them. Run one with -- --ignored and its environment variable.
| Test | Needs |
|---|---|
inference::local::tests::live_limits_cancellation_and_recovery |
Qwen3.5-2B weights and projector. Set ISOBOARD_LOCAL_MODEL_DIR to the bundle directory and add --features local-probe |
inference::local_worker::tests::live_setup_warm_up_reuses_model_for_capture |
A downloaded isOCR bundle. Set ISOBOARD_LOCAL_MODELS_ROOT |
capture::tests::live_local_capture_lifecycle |
Downloaded isOCR and Qwen development models. Set ISOBOARD_LOCAL_MODELS_ROOT |
local_models::service::tests::live_download_cancel_resume |
Downloads a pinned bundle. Set ISOBOARD_DOWNLOAD_TEST_ROOT to a fresh directory, and optionally ISOBOARD_DOWNLOAD_TEST_MODEL |
licensing::commercial_tests::production_validation_and_native_keychain_lifecycle |
Maintainer-only. See below |
The live local tests use real weights and are covered in Local models.
The licensing production test calls Polar’s production validation endpoint once and exercises isolated Keychain storage, offline restoration, and local removal. It reads its input from stdin, and it is a release-verification step for maintainers with an authorized key. Contributors do not need it. The offline lifecycle and protocol tests in the same module run by default and cover the behavior you are likely to change. Never commit a license key, place one in an example command, or paste one into a log or issue. See Licensing.
Continuous integration
Section titled “Continuous integration”.github/workflows/ci.yml runs on every pull request and on pushes to main. It has one job, check, on macos-15 with a 60-minute timeout. Superseded runs for the same ref are cancelled. The workflow has read-only repository permissions, and third-party actions are pinned to commit hashes. It sets CARGO_PROFILE_DEV_DEBUG=line-tables-only to keep caches small and links fast while keeping readable panic backtraces.
Steps in order:
- Check out the code.
- Install Bun 1.3.6.
- Install the stable Rust toolchain with
rustfmtandclippy. - Restore the Cargo cache for
src-tauri. make install.bunx vite build. Tauri embeds the frontend at compile time, so the build output must exist before any Cargo step. The committed bindings are enough for Vite.make format-check.make lint.make bindings-check.- Type-check with
svelte-kit sync,svelte-check, andmake desktop-check. CI calls the tools directly because the package scripts regenerate bindings and CI already verified them. - Test with
bun testandmake desktop-test.
Reproduce a CI failure locally with the matching make target. Only macOS is a supported CI target today. Add Windows and Linux jobs when those platforms are validated.
Release workflow
Section titled “Release workflow”.github/workflows/release.yml builds, notarizes and drafts a GitHub release when a version tag is pushed. It runs make release with secrets from the release environment. See Releases and notices.
Contributor Agreement workflow
Section titled “Contributor Agreement workflow”.github/workflows/contributor-agreement.yml runs on pull_request_target (opened, synchronized, closed) and on issue comments. It asks each pull request author to accept the Contributor Agreement once, by posting a fixed comment, and records the acceptance in a private signatures repository. The check never checks out pull request code, which is why running it with pull_request_target is safe. Keep it that way: do not add a checkout of the pull request head or run untrusted code in this workflow.
The agreement text is fixed by a protected Git tag, isoboard-contributor-v1. The repository owner and bots are allowlisted. Contributors comment recheck to refresh the status. See CONTRIBUTING.md for the contributor view. The pull request template asks for the change, the checks you ran, and contribution rights.