Skip to content

Developer guide

Test a source change

Run focused checks, protect the retained default database, and finish with product-level acceptance when the change needs it.

Match the proof to the change: a focused unit test is the fast loop, a real database path belongs on a disposable scratch instance, and a user-visible change isn't finished until it runs through a claimed Server and the actual client.

Start narrow

bun test <path-to-focused-test>
bun run --cwd <workspace> test:unit
bun run --cwd <workspace> typecheck
bun run --cwd <workspace> lint

For a repository-wide pass, run the same tasks from the root, plus bun run test:integration for full coverage — the integration runner isolates each test file in its own process so global mocks and app instances don't leak across files.

Keep fixture writes away from default

Database-backed tests use a disposable instance ID when their fixture bootstrap runs, and a shared guard refuses fixture writes against the retained default instance unless something explicitly bypasses it or the process is CI. Treat CI as ephemeral — never normalize that bypass into a shell profile or a copied command.

If the scratch instance itself looks stale or corrupted, inspect the failure first, then reset it deliberately with opencircle dev reset-test-cruft --yes — that recreates the whole scratch instance and is not a first response to a failing assertion.

Finish at the product boundary

Tests don't replace acceptance once a change touches the Server, the client, authentication, setup, provider routing, or multi-user behavior. Use one of the paths in Run OpenCircle from source — usually a copy of the claimed default into a fresh named instance — then confirm the right instance is running, setup is ready, the known owner can sign in, the changed path works through the real client, and a model-backed turn succeeds when that's in scope.

Record the exact instance, command, and result in the pull request; "tests pass" alone isn't enough when the real proof happened in one specific environment.

Database changes need a second decision

Before applying a new migration to retained data, walk the database migration safety decision tree — a clean merge and a green test suite don't prove two migration histories can be replayed safely against the same database.