Feature Test Planning

Input

The user has provided the following context:

$ARGUMENTS

Test Planning Process

Step 1: Locate and Review the Feature Specification

First, identify the feature research document:

• If a file path is provided: Read the research document directly
• If a Jira/Confluence URL is provided: Search for associated research documents
• If neither: Ask the user for the path to the feature research document

Read the document thoroughly. Extract:

• Feature requirements and acceptance criteria
• Codebase impact analysis (files to create or modify)
• Architecture considerations and integration points
• Any existing testing considerations mentioned in the research or design documents

Also check for companion documents in the same directory:

• <feature-name>-design.md — may contain a test strategy to build upon
• <feature-name>-tasks.md — may inform which components need tests

Step 2: Study Existing Test Patterns in the Codebase

Before proposing any test cases, study how the codebase currently tests similar functionality:

Test Organization:

• Use the Explore agent or direct file searches to find existing test files related to the feature area
• Identify the project's test file naming conventions (*_test.go placement, test helper locations)
• Note how test packages are structured (same package vs. _test package)

Test Patterns in Use:

• Look for table-driven test patterns and how they're structured
• Identify which assertion libraries are used (standard testing, testify/assert, testify/require, testify/suite)
• Check for test helper functions, fixtures, and factories
• Note how mocking is done (interfaces, golang/mock, hand-rolled mocks)
• Look for embedded Postgres patterns, test database setup/teardown
• Identify any shared test utilities in internal/pkg/ or core/

Test Infrastructure:

• Find existing test helpers that your tests should reuse
• Identify test fixtures or seed data patterns
• Note how tests handle configuration and environment

Document what you find. Your test cases must be consistent with established patterns.

Step 3: Map Feature Requirements to Testable Behaviors

For each requirement or acceptance criterion from the feature spec, identify:

1. The behavior to verify — What observable outcome should the test assert?
2. The test level — Is this a unit test, integration test, or does it need both?
3. The component under test — Which specific function, method, or service?
4. The value justification — Why does this test need to exist? What does it protect against?

Apply your guiding principles aggressively here:

• If a behavior is already covered by existing tests, note it and move on
• If a behavior can be verified by a unit test, do not propose an integration test
• If a test would be inherently flaky (timing-dependent, network-dependent), design around the flakiness or exclude it with an explanation

Step 4: Design Test Cases

For each testable behavior, design concrete test cases:

For Unit Tests:

• Identify the function or method under test
• Define inputs, expected outputs, and error conditions
• Design table-driven test cases where multiple scenarios apply
• Specify which dependencies need mocking and what interfaces to use
• Include edge cases and boundary conditions, but only meaningful ones

For Integration Tests:

• Justify why unit tests are insufficient for this behavior
• Define the scope of integration (which real components, which mocked)
• Specify setup and teardown requirements
• Design for reliability — no timing dependencies, no external service calls

For Each Test Case, Document:

• A clear, descriptive name following Go conventions (TestComponentName_MethodName_Scenario)
• What it verifies and why that matters (the value justification)
• Input conditions and expected outcomes
• Any test infrastructure it requires (helpers, fixtures, mocks)

Step 5: Identify Test Infrastructure Needs

Determine what new test infrastructure is needed:

• New mock implementations — What interfaces need mocks that don't exist yet?
• Test helpers — Are there common setup/teardown patterns that warrant a helper?
• Test fixtures — What test data is needed? Can it be generated or must it be static?
• Shared utilities — Should any test utilities be added to shared packages?

Only propose new infrastructure when it serves multiple tests. A helper used by one test is not a helper — it's unnecessary indirection.

Step 6: Assess Risks and Gaps

Identify:

• Untestable areas — Parts of the feature that are difficult to test and why. Propose design changes if they would make testing feasible.
• Reliability risks — Any proposed tests that might be flaky and how to mitigate
• Coverage gaps — Behaviors that should be tested but can't be with current patterns, and what would need to change
• Dependencies on other work — Tests that can't be written until specific implementation tasks are complete

Output

Append the test plan to the bottom of the engineering implementation planning document as a new top-level section. If the document already has numbered sections (e.g., Sections 1-6), number this section as the next in sequence.

Before writing, read the current state of the planning document to determine the correct section number and ensure you're appending to the latest version.

Use this structure:

---

## [N]. Test Plan

**Test Planning Date:** [Date]
**Test Planner Principles:** Unit-first · Self-cleaning · Value-justified · Reliability-required · Production-quality test code

---

### [N].1 Existing Test Patterns

[Summary of test patterns found in the codebase that this plan follows. Reference specific files as examples.]

**Assertion Library:** [What's used — e.g., testify/assert + testify/require]
**Mock Strategy:** [How mocking is done — e.g., interface-based with golang/mock]
**Test Helpers:** [Relevant existing helpers that tests should reuse]

---

### [N].2 Test Cases — Unit Tests

Tests are grouped by component. Each test case includes its value justification.

#### [N].2.1 [Component/Package Name]

**File:** `path/to/component_test.go`
**Component Under Test:** `package.ComponentName`

| Test Name                               | Verifies        | Value Justification     | Approach                       |
| --------------------------------------- | --------------- | ----------------------- | ------------------------------ |
| `TestComponentName_Method_HappyPath`    | [What behavior] | [Why this test matters] | [Table-driven / direct / etc.] |
| `TestComponentName_Method_InvalidInput` | [What behavior] | [Why this test matters] | [Approach]                     |
| `TestComponentName_Method_EdgeCase`     | [What behavior] | [Why this test matters] | [Approach]                     |

**Mock Dependencies:**

- `InterfaceName` — [What it mocks and why mocking is appropriate here]

**Table-Driven Test Design** (where applicable):

```go
// Example structure — not implementation, just the shape
tests := []struct {
    name     string
    input    InputType
    expected OutputType
    wantErr  bool
}{
    // [Describe the categories of test cases]
}
```

Setup/Teardown Notes: [Any special considerations for test lifecycle]

[Repeat for each component...]

[N].3 Test Cases — Integration Tests

Only tests where unit testing is insufficient. Each entry justifies why integration-level testing is needed.

[N].3.1 [Integration Scenario Name]

Justification: [Why unit tests cannot cover this behavior] Scope: [Which real components are involved, which are mocked] File: path/to/integration_test.go

Cleanup Requirements: [How the test cleans up after itself]

[Repeat for each integration scenario...]

[N].4 Test Infrastructure

New Mock Implementations

New Test Helpers

Test Fixtures

[N].5 Tests Explicitly NOT Included

[List behaviors or components where you consciously decided NOT to write tests, and why. This is as important as the tests themselves.]

[N].6 Test Implementation Sequence

[Recommended order for implementing the tests, considering dependencies]

1. [First] — [Why this comes first — e.g., "Creates shared test helpers used by all subsequent tests"]
2. [Second] — [What it depends on]
3. [Third] — [Continue...]

[N].7 Open Questions

[Test-related questions that need answers before implementation]

1. [Question] — Affects: [Which test cases]. [Why it matters for testing.]

## Important Guidelines

1. **Consistency with the codebase** — Your test cases must follow the patterns already established in the project. Do not introduce new test frameworks, assertion styles, or patterns without explicit justification.

2. **Concrete, not abstract** — Every test case should be specific enough that a developer could implement it without guessing your intent. Include function names, input shapes, and expected outcomes.

3. **Justify every test** — The "Value Justification" column is mandatory. "Increases coverage" is not a valid justification. "Catches regressions if the sorting algorithm is changed to an unstable sort" is.

4. **Justify every exclusion** — Section [N].5 (Tests Explicitly NOT Included) is mandatory. Thoughtful exclusions demonstrate rigor.

5. **Prefer fewer, better tests** — Ten well-designed test cases that cover meaningful behaviors are worth more than fifty shallow tests that check trivial properties.

6. **Name tests clearly** — Test names should read as specifications: `TestProvisioner_SelectForWorkflow_ReturnsErrorWhenNoMatchingDriver` tells you exactly what's being verified.

7. **Design for maintenance** — Every test you propose will need to be maintained for years. Avoid coupling tests to implementation details that change frequently.