TestSpec

中文文档

Requirement-driven test design CLI for AI-assisted QA workflows.

TestSpec is a CLI tool that helps QA teams create, manage, and track test artifacts through a structured workflow. It integrates with AI-powered agents like Claude Code, Qoder, Codex, and Trae to streamline the testing process.

Features

• Structured Workflow: Follow a proven test design process from requirements to test cases
• AI Integration: Works with Claude Code, Qoder, Codex, Trae, and other AI agents
• Excel Export: Generate executable test cases with functional and performance worksheets
• Mind Map Export: Create visual test case maps for review and collaboration
• Traceability: Maintain links between requirements, test points, and test cases
• Archive System: Organize and preserve completed test cycles

Installation

npm install -g @wangjh2001/testspec@latest

Or use npx without installation:

npx @wangjh2001/testspec init
npx @wangjh2001/testspec new <test-name> --requirement <path>

Quick Start

1. Initialize Your Project

testspec init

This sets up the TestSpec workspace and configures AI agent integrations. By default, the interactive selection starts with Claude Code and Qoder selected. Use Space to select/deselect integrations and Enter to confirm. Before regenerating selected agent command files, init removes stale TestSpec-generated command files in the selected .claude/commands/test/, .qoder/commands/test/, or .trae/commands/test/ directories that still contain the generated marker; custom command files without the marker are preserved. Codex skills under .codex/skills/testspec-*/SKILL.md are refreshed only when they contain the generated marker or --force is used. Generated command and skill files are treated as TestSpec-managed and may be recreated by testspec init.

Available integrations:

| Agent | Output | | ----------- | ------------------------------------------------------------ | | Claude Code | .claude/commands/test/*.md for /test:* slash commands | | Codex | .codex/skills/testspec-*/SKILL.md skills plus AGENTS.md guidance | | Qoder | .qoder/commands/test/*.md for the same workflow labels | | Trae | .trae/commands/test/*.md for the same workflow labels | | Generic | Tool-agnostic AGENTS.md workflow guidance |

For non-interactive setup:

testspec init --agents claude,qoder
# or all integrations
testspec init --agents all

2. Create a Test Change

testspec new login-v2 --requirement docs/login-prd.md --object "Login service"

This creates a new test change directory with a proposal template. --requirement accepts a local path or URL, --object records the tested object name, and --force overwrites an existing workspace.

3. Run the Workflow

For requirement-grounded generation, run the configured workflow entry points inside Claude Code, Codex, Qoder, Trae, or another coding agent. Claude Code, Qoder, and Trae expose /test:* command labels; Codex exposes testspec-* skills that map back to the same test:* workflow labels. The agent reads the requirement document and writes semantic artifacts; the CLI remains provider-free and handles validation, export, reporting, and archive.

/test:analysis login-v2
/test:points login-v2
/test:excel login-v2

CLI commands such as testspec analysis and testspec points remain deterministic fallback/template helpers when no agent is available.

# Fallback/template requirement analysis
testspec analysis login-v2

# Fallback/template test points
testspec points login-v2

# Validate generated artifacts before export
testspec validate login-v2

# Export test cases to Excel
testspec excel login-v2

# Export mind map for review
testspec mind login-v2

# Generate report (after filling execution results in Excel)
testspec report login-v2

# Archive completed test cycle
testspec archive login-v2

Commands

| CLI command | Workflow label | Slash command | Description | | -------------------------------------------------------- | --------------- | ---------------- | ---------------------------------------------------------------- | | testspec init [--agents <ids|all>] [--force] | — | — | Initialize project with AI agent integrations | | testspec new <name> [--requirement <path>] [--object <name>] [--force] | test:new | /test:new | Create a test proposal workspace from a requirement document | | testspec analysis [name] | test:analysis | /test:analysis | Decompose requirements into testable items, risks, and questions | | testspec points [name] | test:points | /test:points | Generate fallback/template test points for a test change | | testspec validate [name] | test:validate | /test:validate | Validate generated artifacts for schema, traceability, and quality | | testspec excel [name] | test:excel | /test:excel | Export executable Excel test cases | | testspec mind [name] | test:mind | /test:mind | Export mind-map style test cases for review | | testspec report [name] | test:report | /test:report | Generate execution statistics from Excel results | | testspec archive [name] | test:archive | /test:archive | Archive the full test artifact chain for traceability | | testspec --help | — | — | Display help information | | testspec --version | — | — | Display version |

--agents accepts claude, codex, qoder, trae, generic, or all; multiple agent IDs are comma-separated, for example --agents claude,qoder,trae. Use --force with testspec init to refresh existing TestSpec-generated agent command files, or with testspec new to overwrite an existing test change workspace.

When a command accepts [name], TestSpec uses the explicit name if provided. If omitted, it infers the only active change; when multiple exist, it asks you to specify the change name.

Excel Export

testspec excel [name] exports artifacts/<name>_cases.xlsx with two worksheets:

| Worksheet | Purpose | | ---------- | --------------------------------------------------------------------------------------- | | 功能测试 | Minimal functional test cases with steps, expected results, priority, and execution status | | 性能测试 | Compact performance scenarios with baseline targets, metrics, and execution status |

The Excel workbook is execution-oriented. Compact artifacts/testcases.json uses exactly the executable schema title, module, type, priority, preconditions, steps, and expectedResult; the CLI normalizes generated cases to that schema before validation and export.

The performance worksheet is generated from deterministic rules:

• Core flows → load-test scenarios
• Query/search/list/report flows → query performance scenarios
• Submit/create/update/delete/order/payment flows → transaction or pressure-test scenarios
• Batch/import/export/upload/download flows → capacity or stability scenarios
• Dependency/callback/message/queue flows → stability scenarios

Unknown business targets (concurrency, target TPS/QPS) remain 待确认 until specified.

Directory Structure

After initialization and creating test changes, your project will have:

your-project/
├── .claude/commands/test/    # Claude Code slash commands (if selected)
├── .codex/skills/testspec-*/ # Codex skills (if selected)
├── .qoder/commands/test/     # Qoder commands (if selected)
├── .trae/commands/test/      # Trae commands (if selected)
├── AGENTS.md                 # Codex or generic agent guidance (if selected)
└── testspec/
    ├── changes/
    │   ├── login-v2/         # Active test change
    │   │   ├── proposal.md              # Test proposal
    │   │   ├── requirements-analysis.md # Requirement decomposition
    │   │   ├── specs/
    │   │   │   └── testpoints.md        # Test points
    │   │   ├── artifacts/
    │   │   │   ├── testcases.json       # Generated test cases
    │   │   │   ├── performance-cases.json
    │   │   │   ├── login-v2_cases.xlsx  # Excel export
    │   │   │   └── login-v2_cases.xmind # Mind map export
    │   │   └── report.md                # Execution report
    │   └── archive/
    │       └── 2026-06-04-login-v2/     # Archived change
    │           ├── manifest.json
    │           └── ...archived artifacts...
    └── ...

Using with AI Agents

After testspec init, AI agents can use workflow labels directly:

Claude Code:

/test:new login-v2 --requirement docs/login-prd.md
/test:analysis login-v2
/test:points login-v2
/test:validate login-v2
/test:excel login-v2
/test:mind login-v2
/test:report login-v2
/test:archive login-v2

Qoder / Trae: Use the same /test:* workflow labels from .qoder/commands/test/*.md or .trae/commands/test/*.md. These command files include the brief instruction, user arguments, and provider-neutral prompt-pack rules in the command body.

Codex: Use the generated skills in .codex/skills/testspec-*/SKILL.md, for example testspec-analysis, testspec-points, and testspec-excel. Each skill maps to the corresponding test:* workflow label and includes the backing CLI command plus provider-neutral prompt-pack rules. AGENTS.md remains a global overview.

Generic Agents: Read AGENTS.md for the same provider-neutral prompt-pack rules. Semantic labels such as test:analysis, test:points, and test:excel should read requirement evidence and generate artifacts before running deterministic CLI validation/export commands.

The test:* labels are Agent workflow labels, not shell commands.

Requirement-grounded generation rules

• The agent must read proposal.md and the referenced requirement document before semantic generation.
• If a requirement file is missing, remote, unreadable, or ambiguous, the agent must ask for readable content or explicit authorization instead of guessing.
• Generated requirements and test points should cite source evidence with document, section, and short quote when available; compact cases should stay executable and use the documented compact schema.
• Unknown business rules, roles, state transitions, limits, and SLA values should be marked 待确认 or added as clarification questions.
• Run testspec validate [name] before export and fix blocking validation errors.

Good case steps are concrete and observable:

1. Log in as user-a.
2. Open the login page.
3. Enter username=user-a and password=ValidPass123.
4. Click Login.
5. Verify the home page shows user-a as logged in.

Avoid generic template steps:

1. Prepare test data.
2. Execute the operation.
3. Verify the system meets requirements.

Development

# Install dependencies
npm install

# Run in development mode
npm run dev -- --help

# Build the CLI
npm run build

# Run checks
npm run typecheck
npm run test
npm run check

License

MIT