pi-dev-team 0.2.0

package/knowledge/test-stack-profiles/bdd-frameworks.md

@@ -0,0 +1,235 @@
+# BDD Frameworks — per-language wire-in
+
+The minimal steps to wire a BDD runner into a project, one section per supported
+language. Use this **after** `../references/bdd-value-guide.md` recommends
+`bdd-runner` mode — this file is the mechanics, not the decision.
+
+Every runner here outputs JUnit-XML (or an equivalent the CI already understands),
+so the BDD suite plugs into the existing pipeline without new reporting.
+
+**Directory naming (issue #1462).** Every canonical destination named below —
+`features/`, `Features/`, `src/test/resources/features/` — ends in a name
+`scripts/detect_bdd_convention.py`'s `_CONVENTIONAL_FEATURE_DIR_NAMES`
+allowlist recognizes (`features`, `feature`, `specs`, `spec`, `bdd`,
+`acceptance`, case-insensitive). That script's feature-file scan only
+signals a project's existing `.feature` directory as "the" convention when
+at least one path component matches this allowlist — an incidental
+`.feature` root elsewhere in the repo, under an unrelated directory name,
+is not treated as evidence of a repo-wide convention. Adding a new stack
+below with a differently-named destination requires adding that name to the
+allowlist too (`tests/scripts/test_detect_bdd_convention.py::TestConventionalNameAllowlistSync`
+enforces the two tables stay in sync).
+
+---
+
+## JS/TS — Cucumber.js
+
+- **Framework:** [@cucumber/cucumber](https://github.com/cucumber/cucumber-js) (v11+).
+- **Install:** `npm install --save-dev @cucumber/cucumber`
+- **Directory layout:**
+  - `features/` — `.feature` files.
+  - `features/support/` — step definitions and world/hooks.
+- **Runner config** — `cucumber.yaml` (or `cucumber.js`) at repo root:
+
+  ```yaml
+  default:
+    require:
+      - features/support/**/*.js
+    format:
+      - "junit:reports/cucumber-junit.xml"
+  ```
+
+- **Step stub (pending):**
+
+  ```js
+  import { Given } from "@cucumber/cucumber";
+  Given("a precondition", function () {
+    return this.pending(); // marks the step (and scenario) pending
+  });
+  ```
+
+- **Run:** `npx cucumber-js`
+- **CI note:** the `junit` formatter writes `reports/cucumber-junit.xml`; point the existing JUnit reporter at it. Cucumber.js runs alongside Vitest/Jest — they are complementary, not alternatives.
+
+---
+
+## Java / Maven — Cucumber-JVM
+
+- **Framework:** [Cucumber-JVM](https://github.com/cucumber/cucumber-jvm) on the JUnit 5 platform.
+- **Install** — add to `pom.xml`:
+
+  ```xml
+  <dependency>
+    <groupId>io.cucumber</groupId>
+    <artifactId>cucumber-java</artifactId>
+    <version>7.18.1</version>
+    <scope>test</scope>
+  </dependency>
+  <dependency>
+    <groupId>io.cucumber</groupId>
+    <artifactId>cucumber-junit-platform-engine</artifactId>
+    <version>7.18.1</version>
+    <scope>test</scope>
+  </dependency>
+  ```
+
+- **Directory layout:**
+  - `src/test/resources/features/` — `.feature` files.
+  - `src/test/java/.../steps/` — step-definition classes.
+- **Runner config** — a suite entry point:
+
+  ```java
+  import org.junit.platform.suite.api.*;
+
+  @Suite
+  @IncludeEngines("cucumber")
+  @SelectClasspathResource("features")
+  public class RunCucumberTest {}
+  ```
+
+  (add `import static io.cucumber.junit.platform.engine.Constants.*;` only if you also set `@ConfigurationParameter` options such as the `pretty` plugin.)
+- **Step stub (pending):**
+
+  ```java
+  import io.cucumber.java.en.Given;
+  import io.cucumber.java.PendingException;
+
+  public class Steps {
+    @Given("a precondition")
+    public void a_precondition() { throw new io.cucumber.java.PendingException(); }
+  }
+  ```
+
+- **Run:** `mvn test` (Surefire discovers the JUnit 5 suite automatically).
+- **CI note:** Surefire emits JUnit XML under `target/surefire-reports/` — no extra config.
+
+---
+
+## Java / Gradle — Cucumber-JVM
+
+Same engine as Maven; only the wiring differs.
+
+- **Install** — add to `build.gradle`:
+
+  ```groovy
+  testImplementation 'io.cucumber:cucumber-java:7.18.1'
+  testImplementation 'io.cucumber:cucumber-junit-platform-engine:7.18.1'
+  testImplementation 'org.junit.platform:junit-platform-suite:1.10.2'
+  ```
+
+- **Runner config** — ensure the `test` task uses the JUnit Platform and sees the feature resources:
+
+  ```groovy
+  test {
+    useJUnitPlatform()
+    systemProperty 'cucumber.junit-platform.naming-strategy', 'long'
+  }
+  ```
+
+  Keep `.feature` files under `src/test/resources/features/` (same suite class as Maven).
+- **Step stub:** identical to Maven (`io.cucumber.java.PendingException`).
+- **Run:** `./gradlew test`
+- **CI note:** Gradle writes JUnit XML under `build/test-results/test/`.
+
+---
+
+## C# — Reqnroll
+
+- **Framework:** [Reqnroll](https://reqnroll.net/) — the actively-maintained, MIT-licensed successor to SpecFlow. **Prefer Reqnroll over SpecFlow:** identical API, but SpecFlow requires a commercial license for teams larger than one, while Reqnroll is free.
+- **Install:** `dotnet add package Reqnroll.xUnit` (or `Reqnroll.NUnit` / `Reqnroll.MsTest` to match the project's test runner) **and** `dotnet add package Reqnroll.Tools.MsBuild.Generation`. The second package is required, not optional — it's the `.feature` → C# code generator; the runtime-bindings package alone leaves `.feature` files silently uncompiled (`dotnet test` reports "No test is available," with no error at all).
+- **Directory layout:**
+  - `Features/` — `.feature` files. The default MSBuild wildcard include only reaches `.feature` files under the test project's own directory tree. To reference files living outside it (e.g. a shared `features/` convention dir consumed by multiple projects), add them explicitly as `ReqnrollFeatureFile` items — **not** `AdditionalFiles` (that's a Roslyn-source-generator convention; MSBuild-based Reqnroll codegen doesn't key on it):
+
+    ```xml
+    <ItemGroup>
+      <ReqnrollFeatureFile Include="..\..\features\*.feature" Link="Features\%(Filename)%(Extension)" />
+    </ItemGroup>
+    ```
+
+  - `StepDefinitions/` — `[Binding]` step classes.
+- **Runner config** — `reqnroll.json` at the project root:
+
+  ```json
+  { "language": { "feature": "en" } }
+  ```
+
+- **Step stub (pending):** throw `PendingStepException` directly — this is Reqnroll's own auto-suggested stub for an undefined step. (`ScenarioContext.StepIsPending()` is deprecated as of Reqnroll 3.3.4 and will be removed in v4; it is also a **static** method, not an instance method, despite older examples showing it called via constructor-injected `ScenarioContext`.)
+
+  ```csharp
+  using Reqnroll;
+
+  [Binding]
+  public class Steps {
+    [Given("a precondition")]
+    public void GivenAPrecondition() => throw new PendingStepException();
+  }
+  ```
+
+- **Run:** `dotnet test`
+- **CI note:** `dotnet test --logger "junit;LogFilePath=reports/reqnroll-junit.xml"` (via the JUnit test logger) produces JUnit XML for the pipeline.
+
+---
+
+## Python — pytest-bdd / behave
+
+- **Framework:** [pytest-bdd](https://github.com/pytest-dev/pytest-bdd) (scenarios run as ordinary pytest tests — preferred when pytest is already the runner) or [behave](https://github.com/behave/behave) (standalone Gherkin runner).
+- **Install:** `pip install pytest-bdd` or `pip install behave` (declare in `pyproject.toml` or `requirements*.txt`).
+- **Directory layout:**
+  - `features/` — `.feature` files (both tools' convention).
+  - pytest-bdd: step definitions in `tests/step_defs/test_*.py`, bound with `scenarios("../../features")`.
+  - behave: step definitions in `features/steps/*.py`.
+- **Step stub (pending):**
+
+  ```python
+  # pytest-bdd
+  import pytest
+  from pytest_bdd import given
+
+  @given("a precondition")
+  def a_precondition():
+      pytest.skip("pending")  # marks the step (and scenario) pending
+
+  # behave
+  from behave import given
+
+  @given("a precondition")
+  def step_a_precondition(context):
+      raise NotImplementedError("pending")
+  ```
+
+- **Run:** `pytest` (pytest-bdd) or `behave --junit --junit-directory reports/` (behave).
+- **CI note:** pytest-bdd scenarios surface through the existing pytest JUnit reporter (`--junitxml`); behave's `--junit` flag writes per-feature JUnit XML the pipeline can pick up directly.
+
+---
+
+## Go — Godog
+
+- **Framework:** [Godog](https://github.com/cucumber/godog) — the official Cucumber implementation for Go.
+- **Install:** `go get github.com/cucumber/godog/cmd/godog@latest` (the library is pulled in transitively; the CLI is optional).
+- **Directory layout:**
+  - `features/` — `.feature` files.
+  - step definitions live in a `*_test.go` file beside the suite entry point.
+- **Runner config** — a suite entry point in `*_test.go` so Godog runs inside `go test` (no separate binary):
+
+  ```go
+  func TestFeatures(t *testing.T) {
+    suite := godog.TestSuite{
+      ScenarioInitializer: InitializeScenario,
+      Options: &godog.Options{Format: "junit", Paths: []string{"features"}, TestingT: t},
+    }
+    if suite.Run() != 0 { t.Fatal("non-zero status returned, failed to run feature tests") }
+  }
+  ```
+
+- **Step stub (pending):**
+
+  ```go
+  func aPrecondition() error { return godog.ErrPending }
+
+  func InitializeScenario(sc *godog.ScenarioContext) {
+    sc.Step(`^a precondition$`, aPrecondition)
+  }
+  ```
+
+- **Run:** `go test ./...` (the suite runs as an ordinary Go test).
+- **CI note:** with the `TestingT` option set (above), scenario failures surface as normal `go test` results, so the existing pipeline already sees them. For a separate JUnit-XML artifact, point `Options.Output` at a file writer (e.g. `f, _ := os.Create("reports/godog-junit.xml"); opts.Output = f`) with `Format: "junit"`.

package/knowledge/test-stack-profiles/django.md

@@ -0,0 +1,13 @@
+# Stack profile — Django / Python
+
+Resolves `test-design-advisor`'s abstract layer (`test-pyramid.md`) to the canonical Django/Python tool.
+
+| Layer | Tool | How to assert |
+|-------|------|---------------|
+| Unit | pytest (or `unittest`); `unittest.mock` only for a blocker collaborator (`internal-collaborator-doubling.md`) | call functions/methods directly; no DB |
+| Component / Service | `pytest-django` + DRF `APIClient` / Django `Client` | drive the view/endpoint in-process; double outbound deps |
+| Integration | `pytest-django` with the real test DB (transactional fixtures) | models, migrations, ORM queries, serializers against a real DB |
+| Contract | Pact (Python) or `schemathesis` against the OpenAPI spec | provider/consumer agreement (`microservice-testing.md`) |
+| E2E | Playwright (Python) / Selenium | critical journeys only |
+
+**Notes.** `freezegun` (or inject a clock) for time; **VCR.py** (`vcrpy`) for outbound HTTP — the preferred record-and-replay tool — double the **owned adapter**, not the third-party SDK; `responses`/`httpx` mock remains a documented fallback alternative for teams already depending on it. See `../virtual-service-libraries.md` for the full preferred/backup catalog. Use `pytest.mark.django_db` deliberately; a test that doesn't need the DB shouldn't take it (speed). For Flask/FastAPI substitute the app's test client (`app.test_client()` / `TestClient`) at the component layer — the layer mapping is identical.

package/knowledge/test-stack-profiles/dotnet.md

@@ -0,0 +1,18 @@
+# Stack profile — .NET (C#)
+
+Resolves `test-design-advisor`'s abstract layer (`test-pyramid.md`) to the canonical .NET tool.
+
+| Layer | Tool | How to assert |
+|-------|------|---------------|
+| Unit | xUnit (or NUnit) + FluentAssertions; Moq / NSubstitute only for a blocker collaborator (`internal-collaborator-doubling.md`) | call the class directly; inject collaborators |
+| Component / Service (API Provider — inbound HTTP) | `WebApplicationFactory<TEntryPoint>` (in-memory `TestServer`) + `HttpClient` | drive the API in-process; replace externals in the test host's DI |
+| Component / Service (API Consumer — outbound HTTP) | Stub `HttpMessageHandler` + `IHttpClientFactory` (`ConfigurePrimaryHttpMessageHandler`) + Polly bound to `FakeTimeProvider` | drive the adapter; assert request shape captured by the stub + the resilience policy under doubled failures (`../references/csharp-http-client-testing.md`) |
+| Integration | Testcontainers-dotnet (real DB/broker) or `EF Core` against a real provider | repository/EF mappings/SQL against a real dependency |
+| Contract (HTTP — request/response shape) | Stub `HttpMessageHandler` driving the owned adapter | structural deserialization of captured request + canned response; queue retry sequences (`../references/csharp-http-client-testing.md`) |
+| Contract (consumer↔provider agreement) | PactNet | consumer-driven contracts across owned service boundaries (`microservice-testing.md`) |
+| E2E | Playwright for .NET | critical journeys only |
+| BDD (optional) | Reqnroll — Unit + Component scenarios | `[Binding]` step classes bound to `.feature` files; runs on xUnit/NUnit/MSTest |
+
+**Notes.** Override services in `WebApplicationFactory.WithWebHostBuilder(...ConfigureTestServices)` to double outbound dependencies pre-merge without config. Inject `TimeProvider` (or an `IClock`) for time determinism; never `DateTime.Now` in logic — pair with Polly v8 bound to the same `TimeProvider` so retry/backoff/circuit-breaker policies advance virtual time deterministically. For the **API Consumer** side (your service calling out), the canonical pre-merge seam is `HttpMessageHandler` — not `WebApplicationFactory`, not Kestrel on a port — wrapped behind a thin owned adapter; WireMock.Net is the preferred implementation of that seam when installed — the same `IHttpClientFactory`/`ConfigurePrimaryHttpMessageHandler` configuration point is used to point the client at WireMock.Net's server URL, but the resulting call is a real loopback HTTP request, not an in-memory interception — with the hand-rolled `StubHttpMessageHandler` kept as backup; see `../references/csharp-http-client-testing.md` for the full pattern (`StubHttpMessageHandler`, request-shape assertions, retry sequencing, off-the-shelf alternatives, smells, and the WireMock.Net preferred/backup detail, including the loopback-socket reconciliation). Avoid the in-memory EF provider for anything relational — it hides SQL bugs; use Testcontainers or SQLite-in-memory deliberately and know its limits.
+
+**BDD.** Use Reqnroll when non-technical stakeholders need to read or co-author scenarios (see `../references/bdd-value-guide.md` for the decision rubric) — BDD scenarios typically sit at the Unit and Component boundaries. **Prefer Reqnroll over SpecFlow:** identical API, but SpecFlow requires a commercial license for teams larger than one, while Reqnroll is the MIT-licensed, actively-maintained fork. Install (`dotnet add package Reqnroll.xUnit` / `.NUnit` / `.MsTest`) and the `ScenarioContext.StepIsPending()` stub: `bdd-frameworks.md`.

package/knowledge/test-stack-profiles/go.md

@@ -0,0 +1,16 @@
+# Stack profile — Go
+
+Resolves `test-design-advisor`'s abstract layer (`test-pyramid.md`) to the canonical Go tool. Go's standard `testing` package covers most layers; reach for libraries sparingly.
+
+| Layer | Tool | How to assert |
+|-------|------|---------------|
+| Unit | `testing` + table-driven tests; interfaces only for a blocker collaborator (`internal-collaborator-doubling.md`) | call the function; stdlib `if got != want` or testify/assert |
+| Component / Service | `net/http/httptest` (`httptest.NewServer` / `ResponseRecorder`) | drive the handler in-process; double outbound deps via interfaces |
+| Integration | Testcontainers-go (real DB/broker) | repository/SQL/driver against a real dependency |
+| Contract | Pact-go | consumer↔provider agreement (`microservice-testing.md`) |
+| E2E | `rod` / `chromedp`, or `go test` driving the built binary | critical journeys only |
+| BDD (optional) | Godog — component/service + E2E scenarios | `godog.TestSuite{}.Run(t)` inside `go test`; steps drive the same in-process handlers |
+
+**Notes.** Define narrow interfaces at the consumer and substitute them only when the collaborator matches a blocker (`internal-collaborator-doubling.md`) — idiomatic Go doubling, no mock framework needed (generate with `moq`/`mockgen` only when hand-writing is tedious). For outbound HTTP, **`go-vcr`** is the preferred record-and-replay tool for that adapter — see `../virtual-service-libraries.md` for the full preferred/backup catalog. Inject a clock (`func() time.Time`) rather than calling `time.Now()` in logic. Use the race detector (`go test -race`) on concurrency-bearing code. Fuzzing is built in (`func FuzzX(f *testing.F)`) — see `../testing-techniques/fuzz.md`.
+
+**BDD.** Use Godog when non-technical stakeholders need to read or co-author scenarios (see `../references/bdd-value-guide.md` for the decision rubric). Godog wires directly into `go test` via `godog.TestSuite{}.Run(t)` — no separate test binary required. Install steps and the `godog.ErrPending` stub: `bdd-frameworks.md`.

package/knowledge/test-stack-profiles/node.md

@@ -0,0 +1,16 @@
+# Stack profile — Node.js backend (Express/Fastify/Nest)
+
+Resolves `test-design-advisor`'s abstract layer (`test-pyramid.md`) to the canonical Node tool. For the browser/UI side see `react.md` / `vue.md` / `ssr-htmx.md`.
+
+| Layer | Tool | How to assert |
+|-------|------|---------------|
+| Unit | Vitest or Jest (or `node:test`); doubles only for a blocker collaborator (`internal-collaborator-doubling.md`) | call the module directly; fake timers for time |
+| Component / Service | supertest against the app instance (no live port) + Nock for outbound HTTP (MSW as fallback) | drive the route in-process; double the service's externals |
+| Integration | Testcontainers (real DB/broker) or an ephemeral DB | the repository/driver/SQL/serialization actually works |
+| Contract | Pact (JS) or `openapi`-driven checks | consumer↔provider agreement (`microservice-testing.md`) |
+| E2E | Playwright | critical journeys only |
+| BDD (optional) | Cucumber.js — component/service scenarios | `.feature` files with step defs in `features/support/`; drives the public surface via supertest |
+
+**Notes.** `supertest(app)` exercises the full middleware/routing stack in-process — the workhorse component test. Mock outbound HTTP with **Nock** — the preferred record-and-replay tool (request-level) — rather than stubbing the HTTP client, so serialization is real; **MSW** remains a documented fallback alternative for teams already depending on it. See `../virtual-service-libraries.md` for the full preferred/backup catalog. Fake timers (`vi.useFakeTimers()` / `jest.useFakeTimers()`) and inject a clock for determinism. Nest: use `Test.createTestingModule(...)` to assemble the component, doubling only a provider that matches a blocker (`internal-collaborator-doubling.md`).
+
+**BDD.** Use Cucumber.js when non-technical stakeholders need to read or co-author scenarios (see `../references/bdd-value-guide.md` for the decision rubric). Wire Cucumber.js **alongside** your existing Vitest/Jest suite — they are complementary, not alternatives: Cucumber drives the public surface (typically through supertest), xUnit drives internals. Install (`@cucumber/cucumber`) and the `this.pending()` stub: `bdd-frameworks.md`.

package/knowledge/test-stack-profiles/react.md

@@ -0,0 +1,12 @@
+# Stack profile — React (CSR / SPA)
+
+Resolves `test-design-advisor`'s abstract layer (`test-pyramid.md`) for a client-side React app. Backend layers live in `node.md` (or the API's own profile).
+
+| Layer | Tool | How to assert |
+|-------|------|---------------|
+| Unit | Vitest/Jest | pure hooks/reducers/utils called directly — no render |
+| Component | React Testing Library + **MSW** for network | render, interact via role/label queries, assert on the DOM the user sees; API mocked at the network |
+| Integration (UI↔API) | RTL + MSW with realistic handlers, or a running test API | data fetching, cache, error/loading states |
+| E2E | Playwright / Cypress against the running app | critical journeys only |
+
+**Notes.** Query by **accessible role/label/text**, not test-ids or class names (resilient + doubles as an a11y check) — see `a11y-review`. Mock the network with **MSW**, not by stubbing `fetch`/`axios`, so serialization and request shape stay real. Don't snapshot whole component trees as a correctness crutch (brittle); for genuine visual fidelity use `../testing-techniques/screenshot.md`. Test behavior (what the user does/sees), never internal state or implementation details.

package/knowledge/test-stack-profiles/spring-boot.md

@@ -0,0 +1,16 @@
+# Stack profile — Spring Boot (Java/Kotlin)
+
+Resolves `test-design-advisor`'s abstract layer (`test-pyramid.md`) to the canonical Spring tool. Names tools by role; pick the team's actual assertion library.
+
+| Layer | Tool | How to assert |
+|-------|------|---------------|
+| Unit | JUnit 5 + AssertJ; Mockito only for a blocker collaborator (`internal-collaborator-doubling.md`) | call the class directly, **no Spring context** — keep it fast |
+| Component / Service | `@WebMvcTest` + MockMvc (web slice) or `@SpringBootTest(webEnvironment=RANDOM_PORT)` + TestRestTemplate | drive the endpoint in-process; double the service's own externals |
+| Integration | Testcontainers (real DB/broker) + `@DataJpaTest` / `@SpringBootTest` | assert the adapter/SQL/serialization against a real dependency |
+| Contract | Spring Cloud Contract or Pact | verify consumer↔provider agreement (`microservice-testing.md`), not E2E |
+| E2E | Playwright / Selenium against the deployed app | critical journeys only |
+| BDD (optional) | Cucumber-JVM — component/service scenarios | `.feature` files run inside JUnit 5 via `cucumber-junit-platform-engine` |
+
+**Notes.** Prefer slice annotations (`@WebMvcTest`, `@DataJpaTest`) over full `@SpringBootTest` — faster context, sharper scope. Inject a fixed `Clock` bean for time determinism. Wrap third-party clients in an owned adapter and double the adapter (`cd-test-architecture.md`), never the SDK. For outbound HTTP, **WireMock** is the preferred record-and-replay tool for that adapter — see `../virtual-service-libraries.md` for the full preferred/backup catalog. Kotlin: same tools; MockK is an idiomatic alternative to Mockito.
+
+**BDD.** Use Cucumber-JVM when non-technical stakeholders need to read or co-author scenarios (see `../references/bdd-value-guide.md` for the decision rubric). Wire it via `cucumber-junit-platform-engine` so Cucumber runs inside JUnit 5 — Maven Surefire and the Gradle `test` task pick it up automatically (the Maven and Gradle dependency sets differ slightly). Full wiring for both build tools and the `PendingException` stub: `bdd-frameworks.md`.

package/knowledge/test-stack-profiles/ssr-htmx.md

@@ -0,0 +1,14 @@
+# Stack profile — SSR + HTMX / Alpine / Turbo
+
+Resolves `test-design-advisor`'s abstract layer (`test-pyramid.md`) for server-rendered apps with hypermedia-driven dynamic swaps. The server uses its own stack profile (`spring-boot` / `django` / `node` / …); this profile covers the **frontend/swap** layer those don't.
+
+| Layer | Tool | How to assert |
+|-------|------|---------------|
+| Unit (server) | the server stack's unit tools | template-data/logic |
+| Integration (server) | the server's component tools (TestClient/MockMvc/supertest) | the endpoint mutates state and returns the **right HTML fragment** |
+| Frontend (template/wiring) | **JSDOM + MSW** — parse the rendered fragment in Node | the fragment carries the correct `hx-target` / `hx-swap` / `hx-trigger` / Alpine `x-data` attributes, without a browser |
+| Browser (swap seam) | **Playwright (REQUIRED — Gate C)** | the swap actually updates the DOM in a real browser: right target, no stale swap, scripts re-init after swap |
+
+**Recipe — testing the swap without a browser (the cheap 80%).** Request the fragment from the server (or render the template), load the HTML into **JSDOM**, and assert the hypermedia attributes and structure. This catches wrong/missing `hx-*` wiring fast and deterministically. It does **not** prove the browser applies the swap — that is Gate C's required Playwright test (`test-layer-gates.md`), because integration gives the client-side seam *zero* coverage.
+
+**Notes.** Don't unit-test HTMX itself — test *your* attributes and *your* fragment. Visual fidelity of a swapped fragment → `../testing-techniques/screenshot.md`; markup correctness → `approval.md`. The advisor flags the browser requirement and defers harness/pipeline design to `cd-test-architecture`.

package/knowledge/test-stack-profiles/vue.md

@@ -0,0 +1,12 @@
+# Stack profile — Vue (CSR / SPA)
+
+Resolves `test-design-advisor`'s abstract layer (`test-pyramid.md`) for a client-side Vue app. Backend layers live in `node.md` (or the API's profile).
+
+| Layer | Tool | How to assert |
+|-------|------|---------------|
+| Unit | Vitest | composables/stores (Pinia)/utils called directly — no mount |
+| Component | Vue Testing Library (preferred) or `@vue/test-utils` + **MSW** | mount, interact via role/label queries, assert on rendered DOM; API mocked at the network |
+| Integration (UI↔API) | Testing Library + MSW with realistic handlers | fetching, store wiring, error/loading states |
+| E2E | Playwright / Cypress | critical journeys only |
+
+**Notes.** Prefer **Vue Testing Library** (role/label queries) over `test-utils`' `findComponent`/`wrapper.vm` access — querying by what the user sees is more resilient and a11y-aware (`a11y-review`). Mock the network with **MSW**, not stubbed `fetch`/`axios`. Test Pinia stores as plain units. For visual fidelity use `../testing-techniques/screenshot.md`; don't lean on full-DOM snapshots for correctness.

package/knowledge/test-strategy.md

@@ -0,0 +1,70 @@
+# Test Strategy
+
+Reference file for `test-review`, `test-smell-review`, and the `test-design-advisor` skill. Where `test-smells.md` catalogues what to *avoid* and `test-doubles.md` covers *which collaborator stand-in* to use, this file covers the **up-front strategic choices** made before and while building a test: how the fixture is organized, how the test is driven, and how it reaches the system under test (SUT).
+
+Source taxonomy: Gerard Meszaros, *xUnit Test Patterns* (xunitpatterns.com), "Test Strategy" patterns. Language- and framework-agnostic — described by role, not by any tool's API.
+
+Core principle: **default to the simplest, most isolated strategy, and only trade isolation away under measured pressure.** Minimal + Fresh fixtures, scripted tests, and front-door interaction are the defaults; every step away from them buys speed or reach at the cost of clarity or coupling, and must be justified.
+
+---
+
+## 1. Test Fixture Strategy
+
+The fixture is everything the test needs in place before it acts. Two independent decisions:
+
+**A. Design — how much fixture?**
+
+| Strategy | What it is | Use when | Cost / risk |
+|---|---|---|---|
+| **Minimal Fixture** | Build only what *this* test uses | **Default.** Always start here | — (this is the safe choice) |
+| **Standard Fixture** | One fixture *design* reused across many tests (a "big design up front" for the suite) | Many tests genuinely share the same shape and a common design reduces duplication | Drifts into the **General Fixture** smell if it builds more than each test needs (see `test-smells.md`) |
+
+**B. Lifecycle — how long does the instance live?** (orthogonal to A)
+
+| Strategy | What it is | Use when | Cost / risk |
+|---|---|---|---|
+| **Fresh Fixture** | A new instance built and torn down per test — every test starts from a clean slate | **Default.** Guarantees isolation | Slow if setup is heavy (esp. persistent/DB fixtures) |
+| **Immutable Shared Fixture** | One instance reused across tests but never mutated (read-only) | Fresh is too slow *and* tests only read the fixture | Requires discipline that nothing writes to it |
+| **Shared Fixture** | One mutable instance reused across many tests / runs | Last resort, when even an immutable shared fixture won't do | Inter-test coupling, order-dependence, **Interacting Tests / Unrepeatable Test / Test Run War** (see `test-smells.md`) |
+
+**Decision flow:** Minimal + Fresh → if too slow, make it an **Immutable Shared Fixture** → only then a mutable **Shared Fixture**, and if shared+persistent, isolate it (per-test DB sandbox / partition scheme) so runs can't collide. Standard vs ad-hoc is a separate axis: a Shared Fixture is always Standard, but a Standard Fixture can still be built Fresh per test.
+
+---
+
+## 2. Test Automation Strategy
+
+How the test is written and driven.
+
+| Strategy | What it is | Use when | Cost / risk |
+|---|---|---|---|
+| **Scripted Test** | Test programs written by hand (the test code you write in any xUnit) | **Default**, and the only option that can *drive* development (TDD) — there's nothing to record before the code exists | Needs programming skill; not for non-technical authors |
+| **Data-Driven Test** | A common interpreter holds the logic; cases live as rows in an external data table (one line per case) | Many cases vary only by input/expected data; lets non-programmers add cases (e.g. Fit/Fitnesse) | Interpreter is itself code to maintain; failures can be opaque; easy to over-build |
+| **Recorded Test** | Capture interactions with a running SUT (usually through the UI) and replay them | Regression-testing a **finished, stable** app where little will change | Brittle to UI/behavior change; can't drive development; high re-record cost |
+| **Test Automation Framework** | The harness that discovers, runs, verifies, and reports tests; you supply only test-specific logic | You **use** one (xUnit, etc.) — rarely build one | Building your own is almost always wasted effort |
+
+Rule of thumb: **scripted by default; data-driven when the variation is purely data; recorded only for regression on something already done.**
+
+---
+
+## 3. SUT Interaction Strategy
+
+How the test reaches the system under test.
+
+| Strategy | What it is | Use when | Cost / risk |
+|---|---|---|---|
+| **Layer Test** | Treat each layer of a layered architecture as its own SUT; test layer *n* with tests standing in for *n+1* and (optionally) a Test Double for *n-1* | The system is layered and you want precise per-layer coverage | Requires real layer boundaries (see `hexagonal-architecture`); misses cross-layer integration bugs unless complemented by broader tests |
+| **Back Door Manipulation** | Set up pre-state or verify post-state by bypassing the SUT's public API — direct DB/file/registry access | Front-door setup/verification is impractical, slow, or so verbose it obscures the test's intent | Couples the test to the SUT's internal state representation; can mask real integration defects — use sparingly and deliberately |
+
+**Front-door first.** Prefer driving and checking the SUT through its real API; reach for a back door only when the front door makes the test unclear or infeasible.
+
+> **Reconciling with the "Test Logic in Production" smell.** `test-smell-review` flags back doors *baked into shipped code* (`if (testMode)`, test-only endpoints) — that is always a smell. **Back Door Manipulation is different:** it is the *test* reaching around the API to touch state the SUT owns, with no change to production code. The first is production code that knows it's being tested; the second is a test that knows the SUT's internals. The former is banned; the latter is a costed trade-off. Don't conflate them in review.
+
+---
+
+## How this connects to the rest of the toolkit
+
+- **`test-doubles.md`** — once Layer Test or Back Door Manipulation needs a collaborator stand-in, choose the double there.
+- **`test-smells.md`** — the failure modes these strategies guard against (General Fixture, Interacting Tests, Mystery Guest, Test Logic in Production).
+- **`test-pyramid.md`** — *where* a check belongs (granularity); this file is *how* the test at that layer is built.
+- **`testability-patterns.md`** — the seams (dependency injection, etc.) that make Fresh Fixtures and front-door interaction possible without back doors.
+- **`cd-test-architecture.md` / `microservice-testing.md`** — applying fixture and interaction strategy in a CD / distributed context.