Testing Strategy

Forge interacts with Git, processes, SQLite, realtime streams, and external agents. Tests must make those boundaries reliable without making CI depend on model APIs.

Test pyramid

Domain unit tests

Pure, fast tests for state transitions and invariants. No database, filesystem, Git, or provider.

Storage tests

Real temporary SQLite databases. Test migrations, constraints, transactions, pragmas, query behavior, and upgrade fixtures.

Git/worktree integration tests

Real temporary Git repositories and the installed git executable. No fake Git for core lifecycle behavior.

Operation/recovery tests

Exercise idempotency and injected failures at boundaries. Restart/reconcile tests are first-class.

Adapter contract tests

A shared suite defines what each capability means. The deterministic fake adapter is the reference harness. Live adapters additionally use captured protocol fixtures where appropriate.

Frontend tests

Component/route tests for important interaction states and a small number of end-to-end flows against the fake agent/core.

Fake agent

The fake adapter must be programmable, not merely “always succeeds.” A test script should be able to:

• emit messages;
• emit tool events;
• change files through the test execution environment;
• request a Decision;
• wait for resolution;
• emit malformed/unknown data;
• duplicate or delay events;
• crash;
• complete normally.

This makes CI deterministic and lets us test difficult timing/recovery paths.

Crash boundary tests

Important examples:

• Operation committed, side effect not started;
• worktree created, outcome persistence interrupted;
• provider started, Run still STARTING;
• Decision persisted while provider waits;
• provider turn finished, revision capture incomplete;
• verification process finished, DB update interrupted.

We do not need every test in the first milestone. Add them as each boundary becomes real.

Migration fixtures

Keep representative old databases under test fixtures once releases/schema versions exist. Every new release must be able to open and migrate them.

Performance regression tests

Once realtime/activity exists, include deterministic large-history tests so we do not reintroduce per-delta quadratic UI behavior.

Definition of done

A course lesson is done only when its listed tests pass and the relevant docs describe the implemented behavior.