---
name: migration-tests
description: Generate the migration TEST PLAN document docs/migration/NNN-tests-<component>.md from an existing NNN-research-<component>.md, for any legacy component being migrated (service, front-end, API, library, …). Produces a detailed, implementable test-first spec (TDD unit tests, integration/UI tests, and compatibility tests) with a coverage matrix, canonical inputs, and seams the implementation must expose. Step 2 of the 3-document migration pipeline (research → tests → plan). Invoke explicitly only.
disable-model-invocation: true
---

# migration-tests

Step 2 of the migration documentation pipeline. Input: the research doc
`docs/migration/NNN-research-<component>.md`. Output: `docs/migration/NNN-tests-<component>.md`
(same `NNN` and `<component>`).

Works for any component type — adapt the test kinds to it (unit + HTTP/integration for a
service or API; unit + UI/component/e2e for a front-end; unit + contract for a library).

Canonical worked example to match: **`docs/migration/001-tests-ZPS.NServiceBusProxy.md`**
(a WCF service — one instance of the general pattern). Read it and the matching
`001-research-*` first.

## Core rules

- **Test-first.** The document is an executable specification written *before* the
  implementation — tests describe required behaviour and drive TDD. State this up top.
- **Implementable, not vague.** Each test has a name, Arrange/Act/Assert (or
  request/expected), and concrete asserted values. A reader must be able to type it
  out without further design decisions.
- **Pin the 1:1 behaviour.** Re-state the exact behaviour/data mapping from the research
  doc as the reference for the tests (fields/types/nullability where data applies; observable
  behaviour/markup/routes otherwise).
- **Name the seams.** List the production elements the implementation must expose for
  tests to be possible (interfaces/classes to mock, `Program` visibility, test doubles).
- **Right-sized.** Scale the number of tests to the service; do not pad. Mark
  infra-dependent tests so they can be excluded from default CI.

## Procedure

1. Read `NNN-research-<component>.md`; extract the operations/routes/features, mapping,
   risks, target architecture and boundary.
2. Choose the test stack consistent with the target (framework, mocking, integration
   harness) and record it.
3. Write `docs/migration/NNN-tests-<service>.md` using the format below.

## Required format

Mirror `001-tests-*`. Sections:

1. **Title** + link to the matching research doc.
2. **TDD principle** — why tests come first; red → green → refactor.
3. **Test stack & project** — table (framework, mocking, integration, assertions) +
   any production requirement (e.g. `public partial class Program`).
4. **Seams (SUT)** — the classes/interfaces/endpoints the implementation must expose.
5. **1:1 mapping reference** — per-message field table (name, target, type) for asserts.
6. **Canonical test data** — fixed payloads (incl. edge cases like null/omitted fields),
   chosen so a swapped field is caught.
7. **Level 1 – unit tests (TDD)** — table: `# | name | Arrange | Act | Assert`.
8. **Level 2 – integration tests** — harness setup + table of cases (status codes,
   headers, routing, validation/negative cases).
9. **Level 3 – compatibility/other** — wire/contract tests, tagged and excluded from
   default CI when they need real infrastructure.
10. **Coverage matrix** — table: requirement → test IDs.
11. **Conventions** — naming (`Method_Scenario_Expected`), traits/categories, AAA.
12. **Out of scope** — what is deliberately not tested and why.