prebid Integration Tests from Stubs
Derive integration tests from existing unit test xfails (Bucket A: "requires real DB") and UNSPECIFIED stubs that exercise DB-dependent paths. Each stub's expected behavior is absolute truth — if the integration test fails, fix production code, never adjust the expected behavior.
Args
/integrate <entity-name-1> [entity-name-2] ...
Entity names (space-separated): creative, media-buy, delivery.
Each must already have a unit test suite from /surface.
Hard Gate: Pre-Check
The catalog atom checks if tests/unit/test_{entity}.py exists. If not:
┌──────────────────────────────────────────────────────────┐
│ STOP: No entity test suite for {entity}. │
│ │
│ Run `/surface {entity}` first to create the │
│ test surface map with obligations and stubs. │
│ │
│ Integration tests derive from the surface — no surface, │
│ nothing to derive from. │
└──────────────────────────────────────────────────────────┘
Protocol
Step 1: Cook the molecule
python3 .claude/scripts/cook_formula.py \
--formula .claude/formulas/integration-from-stub.yaml \
--var "ENTITY_NAMES={all_args}" \
--epic-title "Integrate: {all_args}"
Dry run first (recommended):
python3 .claude/scripts/cook_formula.py \
--formula .claude/formulas/integration-from-stub.yaml \
--var "ENTITY_NAMES={all_args}" \
--epic-title "Integrate: {all_args}" \
--dry-run
Step 2: Walk the molecule
bd ready → bd show <atom-id> → read description → execute → bd close <atom-id> → repeat
Each entity goes through 9 atoms:
catalog → review → triage → architect → write-integration → fix-green → reconcile-xfail → verify → commit
Barrier serialization: Entities execute in parallel within each atom phase,
but write-integration waits for ALL entities' commit from the previous
barrier (if any) to complete. This prevents merge conflicts.
Step 3: Done when all atoms closed
All entities committed. Finalize atom runs ./run_all_tests.sh and reports
remaining xfails.
Atom Details
| # | Atom | What It Does |
|---|---|---|
| 1 | catalog | Read unit test suite, classify xfails into Bucket A (needs DB) vs B (not implemented), select batch |
| 2 | review | Verify stub fidelity, fixture design, batch scope, no duplicates with existing integration tests |
| 3 | triage | Route: ALL_LOW → proceed, NEEDS_REFINEMENT → adjust, NEEDS_USER_INPUT → block |
| 4 | architect | Read 7 architecture docs, trace code paths per test, map layer boundaries, document violations as FINDINGs, design fixtures and adapter mocking strategy |
| 5 | write-integration | Create tests/integration/test_{entity}_v3.py following the architect plan exactly |
| 6 | fix-green | Fix production code for failing integration tests (stub is truth, code is wrong) |
| 7 | reconcile-xfail | Remove xfails for tests now covered by passing integration tests |
| 8 | verify | make quality + integration tests pass + xfail count reconciled |
| 9 | commit | Commit integration tests + production fixes |
The Architect Atom (Why It Matters)
The architect atom is the key differentiator from regular /remediate. It:
- Reads documented architecture — 7 specific documents define the layer boundaries, error handling contracts, and data flow expectations
- Traces real code paths — for each stub, maps wrapper → _impl → DB → adapter
- Cross-references CRIT findings — checks if the code path touches any of the 11 critical issues from the migration review
- Documents violations — uses FINDING format when existing code violates architecture, rather than silently encoding broken behavior into tests
- Does NOT copy patterns — "match existing patterns" is explicitly forbidden. Existing code may violate the architecture.
Required Reading for Architect
CLAUDE.md— 9 critical patternsdocs/development/structural-guards.md— 6 AST-enforced invariantsarchive/code-reviews/00-migration-summary.md— CRIT-1..CRIT-11archive/code-reviews/01-schema-model-layer.md— schema constraintsarchive/code-reviews/02-api-boundary-layer.md— boundary constraintsarchive/code-reviews/04-adapter-layer.md— adapter contractsdocs/development/architecture.md— system architecture
Iron Rule: Stub Intent Is Absolute Truth
The unit test stub defines WHAT to test. The integration test verifies the SAME behavior with real PostgreSQL. If the integration test fails, the production code is wrong — not the stub.
| Outcome | Action |
|---|---|
| Integration test passes | Behavior works end-to-end |
| Fails with AssertionError | Production code bug → fix in fix-green atom |
| Fails with setup error | Fixture needs work → fix the fixture |
| Code violates architecture | FINDING → discuss before encoding into test |
NEVER adjust the expected behavior to match current code.
Anti-Patterns
- Don't skip the architect atom — it catches architecture violations that unit tests with mocks cannot see
- Don't copy existing integration test patterns blindly — verify they follow the architecture
- Don't design tests to match broken code — document as FINDING
- Don't combine write-integration and fix-green — tests must exist before fixes
- Don't include Bucket B xfails ("not yet implemented") — those need production code, handled by B2
- Don't over-fixture — module-scope for expensive setup, function-scope for test-specific state
See Also
/surface— Create entity test suites (prerequisite)/verify-spec— Verify test expectations against AdCP spec (run after surface)/remediate— Fill unit test stubs (different from integration derivation)/mol-execute— Execute individual beads tasks/guard— Structural guards that protect the architecture