---
name: scorpio-test-strategy
description: Analyze test coverage gaps, recommend test strategies by module, and generate test task files. Use when you want to proactively improve test health, assess coverage, or plan a testing initiative.
---

# Test Strategist

A systematic methodology for analyzing a project's test health, identifying coverage gaps, recommending test strategies, and generating actionable test tasks. This skill is the proactive counterpart to scorpio-qa-final — scorpio-qa-final validates specific changes, Test Strategist evaluates overall test health.

## Prerequisites

- A **Project Context document** from **scorpio-project-map** (recommended)
- Access to the codebase and existing test files
- Ability to run the test suite and coverage tools (if available)

## Analysis Phases

```
Phase 1: Survey     → Map existing tests and coverage
Phase 2: Assess     → Identify gaps and risk areas
Phase 3: Strategize → Recommend test types by module
Phase 4: Generate   → Create test task files
Phase 5: Present    → Deliver prioritized test plan
```

## Phase 1: Survey

Map what tests currently exist and how they're organized.

### Discover Test Files

```
Glob: "**/*.test.*"        → co-located test files
Glob: "**/*.spec.*"        → spec-style test files
Glob: "**/__tests__/**"    → Jest-style test directories
Glob: "tests/**"           → top-level test directory
Glob: "test/**"            → alternative test directory
Glob: "**/*.cy.*"          → Cypress E2E tests
Glob: "**/playwright/**"   → Playwright E2E tests
```

### Identify Test Infrastructure

| Check | How |
|-------|-----|
| Test framework | Read package.json/config for jest, vitest, pytest, etc. |
| Test runner config | Read jest.config, vitest.config, pytest.ini, etc. |
| Coverage tool | Check for nyc, c8, istanbul, coverage config |
| E2E framework | Check for Cypress, Playwright, Selenium |
| CI test step | Check .github/workflows for test commands |
| Test scripts | Read package.json scripts for test-related commands |

### Run Coverage (if available)

```bash
# Attempt to generate coverage report
npm run test -- --coverage  # or equivalent
```

### Document Test Landscape

```markdown
## Test Landscape

### Infrastructure
- **Test framework**: [Jest / Vitest / pytest / etc.]
- **Coverage tool**: [c8 / istanbul / none]
- **E2E framework**: [Playwright / Cypress / none]
- **CI integration**: [Yes — runs on PR / No]

### Current Tests
| Location | Count | Type | Framework |
|----------|-------|------|-----------|
| `src/**/*.test.ts` | [N] | Unit | Jest |
| `tests/integration/` | [N] | Integration | Jest |
| `e2e/` | [N] | E2E | Playwright |

### Coverage Summary (if available)
| Module | Statements | Branches | Functions | Lines |
|--------|-----------|----------|-----------|-------|
| src/auth/ | [N]% | [N]% | [N]% | [N]% |
| src/api/ | [N]% | [N]% | [N]% | [N]% |
| src/components/ | [N]% | [N]% | [N]% | [N]% |
| **Overall** | [N]% | [N]% | [N]% | [N]% |

### Test Patterns Observed
- **Naming**: [describe/it blocks, test('should...'), etc.]
- **Mocking**: [jest.mock, vi.mock, manual mocks, etc.]
- **Fixtures**: [factory functions, JSON fixtures, builders]
- **Assertions**: [expect, assert, custom matchers]
```

## Phase 2: Assess

Identify where test coverage is weak or missing entirely.

### Gap Detection Strategy

#### By Module

For each module identified in the project structure:

```markdown
### Module Coverage Assessment

| Module | Source Files | Test Files | Coverage | Risk Level |
|--------|-------------|------------|----------|------------|
| auth/ | [N] | [N] | [N]% or Unknown | [Critical/High/Med/Low] |
| api/ | [N] | [N] | [N]% or Unknown | [Critical/High/Med/Low] |
| components/ | [N] | [N] | [N]% or Unknown | [Critical/High/Med/Low] |
| utils/ | [N] | [N] | [N]% or Unknown | [Critical/High/Med/Low] |
```

#### By Test Type

```markdown
### Test Type Coverage

| Test Type | Exists? | Count | Covers |
|-----------|---------|-------|--------|
| Unit tests | Yes/No | [N] | Individual functions and methods |
| Integration tests | Yes/No | [N] | Module interactions, API endpoints |
| Component tests | Yes/No | [N] | UI component rendering and behavior |
| E2E tests | Yes/No | [N] | Full user flows |
| Snapshot tests | Yes/No | [N] | UI regression detection |
| Performance tests | Yes/No | [N] | Response times, load handling |
```

#### By Risk

Assess untested areas by their risk level:

| Risk Level | Criteria | Priority |
|-----------|----------|----------|
| **Critical** | Auth, payments, data mutations, security boundaries — no tests | Test immediately |
| **High** | Core business logic, API endpoints, shared utilities — no tests | Test next |
| **Medium** | UI components, secondary flows — no tests | Plan testing |
| **Low** | Config, static content, low-complexity helpers — no tests | Test if time permits |

### Code Pattern Analysis

Search for patterns that indicate undertested or untestable code:

```
Grep: "istanbul ignore" or "c8 ignore" → intentionally skipped coverage
Grep: "\.skip\(" or "xit\(" or "xdescribe\(" → skipped tests
Grep: "@ts-ignore" or "// eslint-disable" → suppressed checks (often in hard-to-test code)
Grep: "TODO.*test" or "FIXME.*test" → known test gaps
```

### Gap Summary

```markdown
## Coverage Gaps

### Critical Gaps (untested high-risk areas)
1. **[Module/Area]**: [N] source files, 0 test files — [why it's critical]
2. **[Module/Area]**: [N] source files, 0 test files — [why it's critical]

### High Gaps (untested core functionality)
1. **[Module/Area]**: [N] source files, [N] test files — [what's missing]

### Type Gaps (missing test categories)
1. **No integration tests**: API endpoints are only unit tested
2. **No E2E tests**: Critical user flows have no end-to-end coverage

### Quality Gaps (tests exist but are insufficient)
1. **[Module]**: Tests only cover happy path, no error cases
2. **[Module]**: Tests use mocks so heavily that real integration is untested
```

## Phase 3: Strategize

Recommend the right test types for each area.

### Test Type Selection Guide

| Code Area | Recommended Test Types | Why |
|-----------|----------------------|-----|
| **Pure functions / utils** | Unit tests | Deterministic, fast, high value per effort |
| **Service / business logic** | Unit + integration | Need to verify logic AND interactions |
| **API endpoints** | Integration tests | Test the full request/response cycle |
| **Database queries** | Integration tests (with test DB) | Verify actual SQL/query behavior |
| **UI components** | Component tests | Verify rendering, props, user interaction |
| **UI forms** | Component tests + E2E | Validation logic + full submit flow |
| **Authentication flows** | Integration + E2E | Security-critical, must test real flow |
| **Payment flows** | Integration + E2E | Financial-critical, must test real flow |
| **Complex state management** | Unit + component tests | Verify state transitions |
| **External API integrations** | Integration with mocks | Verify error handling, retries |

### Strategy Document

```markdown
## Test Strategy

### Guiding Principles
1. **Test the riskiest code first** — auth, payments, data mutations
2. **Prefer integration over unit for API code** — catch real issues
3. **Prefer component tests over E2E for UI** — faster, more stable
4. **Use E2E sparingly for critical paths** — login, checkout, core flows
5. **Follow existing patterns** — match the test style already in the codebase

### Module Strategies

#### [Module Name] — [Risk Level]
- **Current state**: [N] tests covering [what]
- **Gap**: [What's missing]
- **Recommendation**: Add [test type] for [what]
- **Pattern to follow**: [existing test file to use as reference]

#### [Module Name] — [Risk Level]
...

### Test Infrastructure Recommendations
- [ ] [Any tooling changes needed — add coverage tool, add E2E framework, etc.]
- [ ] [CI changes — add coverage threshold, add E2E step, etc.]
```

## Phase 4: Generate

Create test task files compatible with **scorpio-execute**.

### Test Task Format

```markdown
## TEST-[NNN] [Test Title]

**Type**: Chore
**Priority**: [P0-P3 based on risk level]
**Estimate**: [XS-M — tests are usually S or M]
**Dependencies**: None

### Description
Add [test type] tests for [module/area] to cover [specific gap].
Currently [N] source files with [0/insufficient] test coverage.

### What to Test
- [ ] [Specific function/endpoint/component to test]
- [ ] [Specific function/endpoint/component to test]
- [ ] Happy path for [main flow]
- [ ] Error case: [specific error scenario]
- [ ] Edge case: [specific edge case]

### Test Pattern Reference
Follow the pattern in `[path/to/existing/test.test.ts]`:
- [Naming convention to follow]
- [Mocking approach to use]
- [Assertion style to match]

### Acceptance Criteria
- [ ] Tests exist for all items in "What to Test" above
- [ ] All new tests pass
- [ ] Existing tests still pass
- [ ] Coverage for [module] increases to [target]% (if coverage tool available)
- [ ] Tests follow existing project patterns

### Technical Notes
- Test file location: `[where to place the test file]`
- Fixtures needed: [any test data or mocks required]
- Setup required: [test database, mock server, etc.]
```

### Task Grouping Strategy

Group test tasks by module and risk:

```markdown
## Test Tasks — Priority Order

### P0 — Critical Coverage Gaps
- TEST-001: Add auth flow integration tests
- TEST-002: Add payment validation unit tests

### P1 — High Coverage Gaps
- TEST-003: Add API endpoint integration tests
- TEST-004: Add user service unit tests

### P2 — Medium Coverage Gaps
- TEST-005: Add UI component tests for forms
- TEST-006: Add utility function unit tests

### P3 — Nice to Have
- TEST-007: Add E2E tests for onboarding flow
- TEST-008: Add snapshot tests for shared components
```

## Phase 5: Present

Deliver the complete test health report.

### Test Strategist Report

```markdown
# Test Strategy Report: [Project Name]

**Date**: [date]
**Project Context**: docs/PROJECT-CONTEXT.md

## Executive Summary

[3-5 sentences: overall test health, biggest gaps, top recommendations]

## Current Test Health

### By the Numbers
- **Total test files**: [N]
- **Overall coverage**: [N]% (or "no coverage tool configured")
- **Test types present**: [Unit, Integration, E2E — list what exists]
- **Test types missing**: [list what's absent]

### Coverage Heatmap
| Module | Risk | Tests | Coverage | Health |
|--------|------|-------|----------|--------|
| auth/ | Critical | [N] | [N]% | BAD / OK / GOOD |
| api/ | High | [N] | [N]% | BAD / OK / GOOD |
| components/ | Medium | [N] | [N]% | BAD / OK / GOOD |

## Gap Analysis
[Phase 2 output]

## Recommended Strategy
[Phase 3 output]

## Test Tasks
[Phase 4 output — task summary table]

| Task | Module | Test Type | Priority | Estimate |
|------|--------|-----------|----------|----------|
| TEST-001 | auth | Integration | P0 | M |
| TEST-002 | payments | Unit | P0 | S |
| TEST-003 | api | Integration | P1 | M |

## Infrastructure Recommendations
- [ ] [Coverage tool setup if missing]
- [ ] [CI coverage threshold if missing]
- [ ] [E2E framework setup if missing]

## Recommended Next Steps
1. [Highest priority test task] → scorpio-execute
2. [Second priority] → scorpio-execute
3. [Infrastructure change] → scorpio-execute (chore task)
```

### User Approval Gate

Present the report and let the user decide:
- Which test tasks to pursue
- Priority order
- Whether infrastructure changes are needed first
- Target coverage thresholds

## Relationship to Other Skills

| Skill | Relationship |
|-------|-------------|
| **scorpio-roomba** | scorpio-roomba flags "missing tests" as quality findings. Test Strategist provides the comprehensive plan. |
| **scorpio-qa-final** | QA Reviewer checks that specific task changes have tests. Test Strategist assesses overall health. |
| **scorpio-execute** | Executes test tasks generated by Test Strategist. |
| **scorpio-retro** | scorpio-retro may identify "tests keep missing X" — feeds into Test Strategist priorities. |

## What NOT To Do

- Do not write test code during analysis (analysis only — code goes through scorpio-execute)
- Do not recommend 100% coverage as a goal (diminishing returns past ~80%)
- Do not ignore existing test patterns (new tests should match the project style)
- Do not prioritize low-risk tests over high-risk gaps
- Do not recommend test types the project can't support without infrastructure changes (note infra needs separately)
- Do not generate vague tasks ("add more tests")

## Skill Chain

Test Strategist feeds into the standard execution pipeline:

```
scorpio-project-map → scorpio-test-strategy → scorpio-execute + scorpio-commit → scorpio-qa-final → scorpio-qa-rework
```

Can also be triggered by other skills:
```
scorpio-roomba ("missing tests" findings) → scorpio-test-strategy (comprehensive plan)
scorpio-retro ("tests keep missing X") → scorpio-test-strategy (targeted plan)
```