From fcaac4631ec26b33d09f38a069c682dee85b6393 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Thu, 27 Aug 2026 19:28:49 -0600 Subject: [PATCH] docs: add Test Completed Work page (#2782) Replace the Testing Options catalog with a decision-oriented completed-work guide at /build/test-completed-work/. Redirect /reference/testing/, list the page in the Build sidebar after Checkpoint a Change, and close the Reference sidebar-order gap. Claims are grounded in bmad-qa-generate-e2e-tests; TEA workflow catalogs stay on the TEA site. --- docs/build/build-a-change.md | 3 + docs/build/test-completed-work.md | 111 ++++++++++++++++++++++++++++++ docs/reference/build-auto.md | 2 +- docs/reference/testing.md | 106 ---------------------------- website/astro.config.mjs | 11 +++ 5 files changed, 126 insertions(+), 107 deletions(-) create mode 100644 docs/build/test-completed-work.md delete mode 100644 docs/reference/testing.md diff --git a/docs/build/build-a-change.md b/docs/build/build-a-change.md index 4cdba6c3e..c493deb2b 100644 --- a/docs/build/build-a-change.md +++ b/docs/build/build-a-change.md @@ -124,6 +124,9 @@ different approach. - An implementation record for the run, kept beside the parent spec or story when there is one +For generated API and end-to-end coverage of the finished work, see +[Test Completed Work](test-completed-work.md). + ## Deferred Work Each run stays focused on one goal. If your request contains several independent diff --git a/docs/build/test-completed-work.md b/docs/build/test-completed-work.md new file mode 100644 index 000000000..39f13a7d7 --- /dev/null +++ b/docs/build/test-completed-work.md @@ -0,0 +1,111 @@ +--- +title: 'Test Completed Work' +description: Choose a testing path after implementation — built-in QA for generated coverage, or TEA when you need strategy, traceability, or release gates. +sidebar: + order: 3 +--- + +After a change is implemented, decide whether it needs more automated +coverage and which BMad path should produce it. The built-in skill is +`bmad-qa-generate-e2e-tests`. It generates API and end-to-end tests for +code that already exists. If you need test strategy, risk-based planning, +or a release gate, install the Test Architect (TEA) module instead. See +[how a run works](#run-bmad-qa-generate-e2e-tests). + +This is generated coverage of finished work. It is not code review, and it +is not the manual observations in [Checkpoint a Change](checkpoint-a-change.md). + +## Which Path? + +| Factor | Built-in QA | TEA | +| --- | --- | --- | +| **Best for** | Coverage for implemented features | Strategy, traceability, or a release gate | +| **Setup** | Included with BMM | Install the TEA module | +| **Approach** | Generate tests from the code that exists | Plan first, then generate with traceability | +| **What it covers** | API and E2E tests | Design, ATDD, automation, review, NFRs, and gates | +| **Strategy** | Happy path plus a few critical errors | Risk-based (P0–P3) | + +:::tip[Start with built-in QA] +Most projects should start with `bmad-qa-generate-e2e-tests`. Install TEA +when you need a test strategy, quality gates, or requirements traceability +that this skill does not produce. +::: + +## Run `bmad-qa-generate-e2e-tests` + +Open a **fresh chat** and name the skill. You can say what to test before, +with, or after the command — a feature, a directory, or "discover what is +untested." + +```text +/bmad-qa-generate-e2e-tests +``` + +```text +/bmad-qa-generate-e2e-tests Create API and E2E tests for the login flow. +``` + +It uses whatever test framework the project already has. If there is none, +it looks at the stack and suggests one. + +### What a run does + +1. **Detect the test framework** — scans dependencies and existing tests + (Playwright, Jest, Vitest, Cypress, and similar). +2. **Identify features** — asks what to test, or auto-discovers features in + the codebase. +3. **Generate API tests** when there are endpoints — status codes, response + shape, happy path, and one or two error cases. +4. **Generate E2E tests** when there is a UI — user workflows with semantic + locators (roles, labels, text) and visible-outcome assertions. +5. **Run the tests** and fix failures immediately. +6. **Write a summary** of what was generated and what is still uncovered. + +Generated tests stay simple on purpose: standard framework APIs, independent +cases, no hardcoded waits, descriptions that read as feature documentation. + +## What You Get + +- Test files under the project's `tests/` directory +- A test summary at `tests/test-summary.md` in your implementation artifacts + directory +- Tests that were run once in this session and made to pass + +## Limits + +`bmad-qa-generate-e2e-tests` generates tests only. It does not review the +implementation — that is `bmad-build` during the run, or `bmad-code-review` +if you want another pass. + +It does not produce a test strategy, risk ranking, requirements +traceability, NFR evidence, or a go/no-go gate. It does not load a PRD or +architecture to map coverage back to requirements. Happy path plus a few +critical errors is the ceiling; more edge cases are follow-up work. + +## When to Use TEA + +Install TEA when the built-in skill is not enough: + +- The project needs requirements traceability or compliance evidence +- Tests must be prioritized by risk across many features +- A formal quality gate decides whether a release ships +- Test strategy has to exist before tests are written +- The work has outgrown one generate-and-run skill + +TEA is a separate module. Its current workflows, commands, and setup live +in the [TEA documentation](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/). +Install it with the rest of BMad; see [Official Modules](../reference/modules.md) +for how modules are selected. + +## Where It Fits + +[`bmad-build`](build-a-change.md) implements a change and, if a suite +already exists, aims to leave those tests passing. This page is the next +testing decision: generate additional API and E2E coverage for that +finished work, or step up to TEA. + +You can run built-in QA after one change. You do not have to wait for an +epic to finish. A typical sequence is implement with `bmad-build`, +optionally [walk through the result](checkpoint-a-change.md), then generate +coverage here. After a whole epic, `bmad-retrospective` is a different +check — it judges the epic against its spec, not the test suite. diff --git a/docs/reference/build-auto.md b/docs/reference/build-auto.md index b883cd021..8845b7546 100644 --- a/docs/reference/build-auto.md +++ b/docs/reference/build-auto.md @@ -2,7 +2,7 @@ title: Autonomous Development Loops description: Reference for automating the Build implementation model with bmad-build-auto as the single-iteration worker. sidebar: - order: 7 + order: 6 --- `bmad-build-auto` is the unattended worker for one session-sized unit in the diff --git a/docs/reference/testing.md b/docs/reference/testing.md deleted file mode 100644 index 168e6c1be..000000000 --- a/docs/reference/testing.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Testing Options -description: Comparing the built-in QA workflow with the Test Architect (TEA) module for test automation. -sidebar: - order: 6 ---- - -BMad provides two testing paths: a built-in QA workflow for fast test generation and an installable Test Architect module for enterprise-grade test strategy. - -## Which Should You Use? - -| Factor | Built-in QA | TEA Module | -| --- | --- | --- | -| **Best for** | Small-medium projects, quick coverage | Large projects, regulated or complex domains | -| **Setup** | Nothing to install -- included in BMM | Install separately via `npx bmad-method install` | -| **Approach** | Generate tests fast, iterate later | Plan first, then generate with traceability | -| **Test types** | API and E2E tests | API, E2E, ATDD, NFR, and more | -| **Strategy** | Happy path + critical edge cases | Risk-based prioritization (P0-P3) | -| **Workflow count** | 1 (Automate) | 9 (design, ATDD, automate, review, trace, and others) | - -:::tip[Start with built-in QA] -Most projects should start with the built-in QA workflow. If you later need test strategy, quality gates, or requirements traceability, install TEA alongside it. -::: - -## Built-in QA Workflow - -The built-in QA workflow (`bmad-qa-generate-e2e-tests`) is part of the BMM (Agile suite) module, available through the Developer agent. It generates working tests quickly using your project's existing test framework -- no configuration or additional installation required. - -**Trigger:** `QA` (via the Developer agent) or `bmad-qa-generate-e2e-tests` - -### What It Does - -The QA workflow (Automate) walks through five steps: - -1. **Detect test framework** -- scans `package.json` and existing test files for your framework (Jest, Vitest, Playwright, Cypress, or any standard runner). If none exists, analyzes the project stack and suggests one. -2. **Identify features** -- asks what to test or auto-discovers features in the codebase. -3. **Generate API tests** -- covers status codes, response structure, happy path, and 1-2 error cases. -4. **Generate E2E tests** -- covers user workflows with semantic locators and visible-outcome assertions. -5. **Run and verify** -- executes the generated tests and fixes failures immediately. - -The workflow produces a test summary saved to your project's implementation artifacts folder. - -### Test Patterns - -Generated tests follow a "simple and maintainable" philosophy: - -- **Standard framework APIs only** -- no external utilities or custom abstractions -- **Semantic locators** for UI tests (roles, labels, text rather than CSS selectors) -- **Independent tests** with no order dependencies -- **No hardcoded waits or sleeps** -- **Clear descriptions** that read as feature documentation - -:::note[Scope] -The QA workflow generates tests only. For code review and story validation, use the Code Review workflow (`CR`) instead. -::: - -### When to Use Built-in QA - -- Quick test coverage for a new or existing feature -- Beginner-friendly test automation without advanced setup -- Standard test patterns that any developer can read and maintain -- Small-medium projects where comprehensive test strategy is unnecessary - -## Test Architect (TEA) Module - -TEA is a standalone module that provides an expert agent (Murat) and nine structured workflows for enterprise-grade testing. It goes beyond test generation into test strategy, risk-based planning, quality gates, and requirements traceability. - -- **Documentation:** [TEA Module Docs](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) -- **Install:** `npx bmad-method install` and select the TEA module -- **npm:** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) - -### What TEA Provides - -| Workflow | Purpose | -| --- | --- | -| Test Design | Create a comprehensive test strategy tied to requirements | -| ATDD | Acceptance-test-driven development with stakeholder criteria | -| Automate | Generate tests with advanced patterns and utilities | -| Test Review | Validate test quality and coverage against strategy | -| Traceability | Map tests back to requirements for audit and compliance | -| NFR Assessment | Evaluate non-functional requirements (performance, security) | -| CI Setup | Configure test execution in continuous integration pipelines | -| Framework Scaffolding | Set up test infrastructure and project structure | -| Release Gate | Make data-driven go/no-go release decisions | - -TEA also supports P0-P3 risk-based prioritization and optional integrations with Playwright Utils and MCP tooling. - -### When to Use TEA - -- Projects that require requirements traceability or compliance documentation -- Teams that need risk-based test prioritization across many features -- Enterprise environments with formal quality gates before release -- Complex domains where test strategy must be planned before tests are written -- Projects that have outgrown the built-in QA's single-workflow approach - -## How Testing Fits into Workflows - -The QA Automate workflow appears in Phase 4 (Implementation) of the BMad Method workflow map. It is designed to run **after a full epic is complete** — once all stories in an epic have been implemented and code-reviewed. A typical sequence: - -1. For each story in the epic: implement with Build (`BD` / `bmad-build`), then optionally add Code Review (`CR`) -2. After the epic is complete: generate tests with `QA` (via the Developer agent) or TEA's Automate workflow -3. Run retrospective (`bmad-retrospective`) to capture lessons learned - -The built-in QA workflow works directly from source code without loading planning documents (PRD, architecture). TEA workflows can integrate with upstream planning artifacts for traceability. - -For more on where testing fits in the overall process, see the [Workflow Map](./workflow-map.md). diff --git a/website/astro.config.mjs b/website/astro.config.mjs index 077bac582..6af244b1e 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -24,6 +24,7 @@ export default defineConfig({ '/explanation/build': `${basePath}build/build-a-change/`, '/explanation/checkpoint-preview': `${basePath}build/checkpoint-a-change/`, '/build/review-a-completed-change': `${basePath}build/checkpoint-a-change/`, + '/reference/testing': `${basePath}build/test-completed-work/`, '/fr/how-to/non-interactive-installation': `${basePath}fr/how-to/install-bmad/`, '/cs/how-to/non-interactive-installation': `${basePath}cs/how-to/install-bmad/`, '/vi-vn/how-to/non-interactive-installation': `${basePath}vi-vn/how-to/install-bmad/`, @@ -157,6 +158,16 @@ export default defineConfig({ }, slug: 'build/checkpoint-a-change', }, + { + label: 'Test Completed Work', + translations: { + 'vi-VN': 'Kiểm thử công việc đã xong', + 'zh-CN': '测试已完成的工作', + 'fr-FR': 'Tester le travail terminé', + 'cs-CZ': 'Otestovat dokončenou práci', + }, + slug: 'build/test-completed-work', + }, ], }, {