how we build · part five

Testing as Chain Verification

Unit tests named with scenario names. Contract tests at Epic boundaries. Visual regression. QA's craft before and beyond the scenarios. Accessibility. Product analytics as the prediction's measurement instrument. SLOs as observable promises.

Events in this phase. Daily over the board continues — test failures surface as red cards. Pair sessions happen ad-hoc when a developer needs help reading a failure at the right altitude. Tests live inside every story's flow, not in a separate phase.

Unit tests — scenarios as executable specifications

This is where meaning becomes machine-checkable. Every scenario written in the amigos session has a corresponding unit test. The test name carries the scenario name. This is not a naming convention — it is the mechanism that makes a failing test tell you which specification was violated, not just which code broke.

// concurrent-submit scenario from STORY-05 amigos session:
//   "Given a student submits while offline,
//    when the connection restores mid-submit,
//    then only one submission is recorded"

describe('exam-grading / concurrent-submit', () => {
  it('records exactly one submission when two arrive simultaneously', () => {
    // ...
  });
});

When this test fails six months from now, the developer reads the name and knows: the concurrent-submit scenario from exam-grading. They find the Given-When-Then in JIRA, the wireframe state in Figma, the ADR that governs idempotency. No conversation required.

Contract tests — Epic boundary verification

Contract tests verify that two systems specified to work together actually do — before integration, not after. The contract was written in Volume III as part of technical shaping. The test verifies both sides honour it. A contract test failure means one system changed without telling the other. Found here: an afternoon of conversation. Found in production: a P1 incident, a client who lost trust, and an operations team managing chaos at 2am.

Integration testing — systems you don't control

When the system integrates with a third party — a school system for Gal's grade submission, a payment provider for Uri's billing — the testing discipline changes. You cannot fix the other system's bugs. You can only map its failure modes and design your retry and fallback strategies around what it actually does, not what its documentation promises.

Test against the provider's sandbox environment in your pipeline. Map known failure modes (rate limits, timeouts, validation errors) as explicit test cases. Use the API contract from Volume III as the specification — but verify it against real behaviour. When the provider changes without notice, your contract tests catch the drift before your users do.

Next — QA's execution craft →