Testing Workflow

Testing Workflow

Orchestrate comprehensive testing across a project by coordinating the testing-patterns skill, e2e-testing skill, and testing agents. This meta-skill does not define test patterns itself — it routes to the right skill or agent at each stage and ensures nothing is missed.

When to Use

• Setting up testing for a new project from scratch
• Improving coverage for an existing project with gaps
• Establishing or revising a testing strategy
• Before a major release to verify quality gates are met
• After a large refactor to confirm nothing broke
• During code review when test adequacy is in question
• Onboarding a team to a testing workflow

Orchestration Flow

Follow these steps in order. Each step routes to a specific skill or agent — read and apply that resource before moving to the next step.

Phase 1: Discovery and Baseline

Scan the project to understand existing test infrastructure, measure current coverage, and identify gaps before making changes. Without a baseline, you cannot demonstrate improvement.

1. Identify test infrastructure — Determine the test runner, assertion library, coverage tool, and CI configuration already in use. If none exist, flag that setup is needed.
2. Measure current coverage — Run the existing test suite and record statement, branch, and function coverage. This is the baseline.
3. Map untested code — Identify modules, functions, and code paths with no test coverage. Prioritize by risk: business-critical logic first, utilities last.
4. Catalog existing tests — Categorize existing tests as unit, integration, or E2E. Check for skipped tests, flaky tests, and tests that don't assert anything meaningful.

Phase 2: Strategy Selection

Based on the discovery results, select the appropriate testing approach for this project.

1. Determine project type — Use the Coverage Targets table below to set appropriate thresholds for the project type.
2. Select test patterns — Read ai/skills/testing/testing-patterns/SKILL.md and choose the unit/integration test patterns that match the project's architecture, language, and framework.
3. Identify critical user journeys — List the 3-10 most important user workflows that require E2E coverage. These are flows where a failure would directly impact revenue, user trust, or safety.
4. Document the strategy — Fill in the Testing Strategy Template (below) and commit it to the repository.

Phase 3: Implementation

Generate tests following the patterns selected in Phase 2.

1. Unit tests first — Write unit tests for uncovered business logic, starting with the highest-risk modules. Follow the testing pyramid: ~70% of your tests should be unit tests.
2. Integration tests next — Write integration tests for module boundaries, API endpoints, and database queries. Focus on the seams where components interact.
3. E2E tests for critical journeys — Read ai/skills/testing/e2e-testing/SKILL.md and write E2E tests for each critical user journey identified in Phase 2.
4. Edge case coverage — After the happy paths are covered, add tests for error conditions, boundary values, null/empty inputs, and concurrency scenarios.

Phase 4: Validation

Verify that the new tests meet quality standards and coverage targets.

1. Run the full test suite — Every test must pass. Fix failures before proceeding.
2. Measure coverage against targets — Compare new coverage against the thresholds for the project type. If targets are not met, return to Phase 3.
3. Check test quality — Review tests for the anti-patterns listed in testing-patterns (assert-free tests, overmocking, flaky tests, test pollution). Fix any found.
4. Verify CI integration — Confirm that tests run automatically on every push/PR and that coverage thresholds are enforced in CI.

Phase 5: Maintenance

Establish ongoing practices to keep the test suite healthy.

1. Set up coverage ratcheting — Configure CI to fail if coverage drops below the current level. Coverage should only go up.
2. Establish flaky test policy — Any test that fails intermittently must be fixed within one sprint or removed with a justification.
3. Define test review standards — Every PR that adds or changes logic must include corresponding test changes. Reviewers check for this.
4. Schedule test health audits — Quarterly, review test execution time, flaky test rate, skipped test count, and coverage trends.

Skill Routing Table

Use this table to route specific needs to the correct resource:

When a request falls clearly into one row, go directly to that resource. Use the full orchestration flow only when comprehensive coverage is the goal.

Coverage Targets

Targets vary by project type. Use the appropriate row to set expectations:

These are minimums. Aim higher when time permits, but do not block releases on vanity metrics — prioritize meaningful coverage over percentage points.

Testing Strategy Template

Use this template to document the testing strategy for a project. Fill it in during the orchestration flow and keep it in the repo.

# Testing Strategy

## Project Overview
- **Project**: [name]
- **Type**: [startup MVP | production app | library | critical infrastructure]
- **Primary Language**: [language]
- **Framework**: [framework]
- **Test Runner**: [runner]
- **Coverage Tool**: [tool]

## Coverage Baseline
- **Statement**: [X%]
- **Branch**: [X%]
- **Function**: [X%]
- **E2E Journeys Covered**: [N of M]
- **Date Measured**: [YYYY-MM-DD]

## Coverage Targets
- **Statement**: [target%]
- **Branch**: [target%]
- **Function**: [target%]
- **E2E Journeys**: [target count]

## Test Patterns Selected
- [ ] [Pattern 1 — reason for selection]
- [ ] [Pattern 2 — reason for selection]
- [ ] [Pattern 3 — reason for selection]

## Critical User Journeys (E2E)
1. [Journey 1 — e.g., signup -> onboarding -> first action]
2. [Journey 2 — e.g., login -> dashboard -> export]
3. [Journey 3 — e.g., checkout -> payment -> confirmation]

## Gaps and Risks
- [Untested area 1 — risk level, mitigation plan]
- [Untested area 2 — risk level, mitigation plan]

## Quality Gate Status
- [ ] All tests pass
- [ ] Coverage targets met
- [ ] Critical journeys covered with E2E
- [ ] No skipped tests without justification
- [ ] Test execution time within budget
- [ ] CI enforces coverage thresholds

Quality Gates for Testing Completion

All of the following must be satisfied before marking testing complete:

NEVER Do

1. NEVER write tests that test implementation details instead of behavior — tests must verify what the code does, not how it does it
2. NEVER skip the discovery phase — always measure the baseline before writing new tests, or you cannot demonstrate improvement
3. NEVER merge tests that depend on execution order — each test must be independent and idempotent
4. NEVER mock what you do not own — wrap third-party dependencies in your own adapters and mock the adapters instead
5. NEVER treat coverage percentage as the sole quality metric — 100% coverage with weak assertions is worse than 70% coverage with strong assertions
6. NEVER leave the test suite in a failing state — if a test fails, fix it or remove it with a justification before moving on
7. NEVER skip E2E tests for critical user journeys — unit tests alone cannot catch integration failures in flows that matter most
8. NEVER deploy without running the full test suite — partial test runs create false confidence