RankFlow AI — Test-Driven Development Plan

for AI Agent Coding & Empirical Verification#

Version: 1.0.0 Date: 2026-06-13 Purpose: Transform all specs into test-driven, verifiable blueprints so every AI coding task has empirical pass/fail gates.

---

1. Philosophy: Binary Gates for Every Task#

Every task delegated to an AI coding agent MUST end with a verifiable test. No task is "done" until the test passes. This document defines:

• Test Strategy: What kinds of tests apply where
• Success Criteria Format: Standardized, unambiguous pass/fail statements
• Agent Context Blocks: What state must exist before/after each task
• Verification Methods: How to empirically confirm completion

---

2. Test Taxonomy#

---

3. Success Criteria Template (Mandatory for Every Spec)#

Every feature in every spec MUST append a ### Test Plan & Verification section using this format:

### Test Plan & Verification

#### Unit Tests
| Test | Input | Expected Output | File |
|------|-------|-----------------|------|
| `testName` | ... | ... | `src/__tests__/unit/...` |

#### Integration Tests
| Test | Setup | Action | Assertion | File |
|------|-------|--------|-----------|------|
| `testName` | ... | ... | ... | `src/__tests__/integration/...` |

#### E2E Tests
| Flow | Steps | Expected End State | File |
|------|-------|-------------------|------|
| `flowName` | 1. ... 2. ... | ... | `e2e/...` |

#### Success Criteria (Binary)
- [ ] Criterion 1: Measurable, verifiable condition
- [ ] Criterion 2: Measurable, verifiable condition

#### Agent Context (Pre-conditions)
- Required DB state: ...
- Required env vars: ...
- Required external mocks: ...

#### Verification Commands
```bash
# Run tests for this feature
pnpm test:unit -- src/__tests__/unit/feature.test.ts
pnpm test:integration -- src/__tests__/integration/feature.test.ts
pnpm test:e2e -- e2e/feature.spec.ts

---

## 4. Context Maintenance Rules for AI Agents

When delegating implementation tasks, each agent MUST receive:

1. **Role Label**: e.g., `Backend_API_Developer`, `GBP_Integration_Specialist`
2. **Guidance**: The spec section + this test plan
3. **Context**: Upstream outputs (DB schema, API contracts, previous test results)
4. **Mission**: Clear task with testable deliverable

**Context Propagation Chain:**

Spec → Test Plan → Implementation → Tests → Verification Report → Next Task

**Never start a task without:**
- A failing test that defines the expected behavior (TDD)
- Mock data for all external dependencies
- A `VERIFY.md` file in the task workspace documenting pass/fail

---

## 5. File Structure

docs/ ├── specs/ # Existing specs (to be augmented) │ ├── backend-api.md │ ├── user-dashboard-ui.md │ ├── ai-services.md │ ├── citation-network.md │ ├── job-queue-workflows.md │ └── ... ├── test-specs/ # NEW: Test specifications per domain │ ├── TEST-backend-api.md │ ├── TEST-user-dashboard-ui.md │ ├── TEST-ai-services.md │ ├── TEST-citation-network.md │ ├── TEST-job-queue-workflows.md │ ├── TEST-onboarding-e2e.md │ ├── TEST-reporting-compliance.md │ └── TEST-admin-observability.md ├── business_flow_map.md # Existing (to be augmented with verification columns) └── test-plan.md # This file

---

## 6. Verification Pipeline per Stage

| Stage | Entry Gate | Exit Gate | Test Command |
|-------|-----------|-----------|--------------|
| **Schema Design** | Prisma schema approved | `prisma generate` succeeds | `pnpm prisma generate` |
| **API Router** | Schema exists | All router integration tests pass | `pnpm test:integration -- routers` |
| **UI Component** | Design spec approved | Visual regression + interaction tests pass | `pnpm test:ui` |
| **External Integration** | API credentials configured | Contract tests pass against mocks | `pnpm test:contract` |
| **Workflow** | Individual services tested | E2E flow completes in < target time | `pnpm test:e2e -- onboarding` |
| **Deployment** | All tests pass | Health checks + smoke tests pass | `pnpm test:smoke` |

---

## 7. Test Data Strategy

### Mock Factories (Required)
Every test MUST use factory functions, never hardcoded IDs:

```typescript
// src/__tests__/factories/practice.ts
export const createMockPractice = (overrides?: Partial<Practice>) => ({
  id: `prac_${faker.string.nanoid(8)}`,
  businessName: faker.company.name(),
  category: "DENTIST",
  plan: "STANDARD",
  status: "TRIAL",
  subdomain: faker.internet.domainWord(),
  ...overrides,
});

Mock External Services#

---

8. Compliance & Medical Safety Tests#

---

9. Execution Plan#

Phase 1: Foundation (Week 1)#

1. Set up Vitest + Playwright + MSW in repo
2. Create mock factories for all entities
3. Create mock handlers for all external services
4. Write first unit tests for Zod schemas

Phase 2: Router Tests (Week 2)#

1. Unit tests for all 14 tRPC routers
2. Integration tests for auth + practice routers
3. Contract tests for external API clients

Phase 3: Workflow Tests (Week 3)#

1. E2E test: Onboarding flow (signup → dashboard)
2. E2E test: Content approval → publish
3. E2E test: Citation submission (mocked)

Phase 4: Automation Tests (Week 4)#

1. BullMQ job processor tests
2. Inngest workflow step tests
3. Review monitor + auto-reply tests
4. Report generation + PDF tests

Phase 5: Compliance & Performance (Week 5)#

1. Medical content filter tests
2. Consent logging tests
3. Performance benchmarks (LLM latency, page load)
4. Load tests for concurrent job processing

---

10. Agent Task Template#

When delegating a coding task to an AI agent, use this template:

## Task: [Feature Name]
**Role**: [Specialist Label]
**Guidance**: Read [spec file] and [test spec file]
**Context**: [Upstream outputs, DB schema, previous test results]
**Mission**:
1. Write a FAILING test first (TDD)
2. Implement the feature
3. Make the test pass
4. Run the verification command
5. Report: PASS / FAIL with evidence

**Deliverables**:
- [ ] Implementation code
- [ ] Test file(s)
- [ ] VERIFY.md with test output

---

End of Test Plan — RankFlow AI v1.0.0