---

name: run-tests description: Execute tests with coverage analysis using bmad-commands, identify coverage gaps, and suggest missing tests. This skill should be used for test execution and quality validation. acceptance:

• tests_executed: "All matching tests successfully executed"
• coverage_generated: "Coverage report generated successfully"
• gaps_identified: "Coverage gaps analyzed and categorized"
• suggestions_provided: "Missing test suggestions provided (if gaps exist)" inputs: scope: type: string required: true description: "Test scope: task_id, file_path, or '--all'" validation: "Must be valid task ID, file path, or '--all'" coverage: type: boolean required: false description: "Generate coverage report" default: true framework: type: string required: false description: "Test framework (auto-detect or explicit: jest, pytest, junit, gtest, cargo, go)" default: "auto" outputs: tests_passed: type: boolean description: "Whether all tests passed" total_tests: type: number description: "Total number of tests executed" passed_tests: type: number description: "Number of tests that passed" failed_tests: type: number description: "Number of tests that failed" coverage_percent: type: number description: "Overall test coverage percentage" coverage_gaps: type: array description: "List of identified coverage gaps with criticality" telemetry: emit: "skill.run-tests.completed" track:
  • scope
  • framework
  • total_tests
  • passed_tests
  • failed_tests
  • coverage_percent
  • duration_ms
  • gaps_count

---

Run Tests Skill

Purpose

Execute tests, generate coverage reports, analyze coverage gaps, and suggest missing tests to improve code quality and test completeness.

Core Capabilities:

• Test execution via bmad-commands
• Coverage report generation and analysis
• Gap identification with criticality assessment
• Missing test suggestions with concrete examples

Prerequisites

• Test framework configured (Jest, Pytest, JUnit, Google Test, Cargo, Go Test, or any custom framework)
• Tests written for the code being tested
• bmad-commands skill available at .claude/skills/bmad-commands/
• Project dependencies installed

Framework Support:

• Auto-detection: Automatically detects Jest, Pytest, JUnit, GTest, Cargo, Go Test
• Explicit: Specify framework with --framework <name>
• Custom: Add custom frameworks via .claude/config.yaml (see bmad-commands/FRAMEWORK-EXTENSION-GUIDE.md)

---

Workflow

Step 0: Determine Test Scope

Action: Parse input and identify which tests to run.

Scope Types: Task-based (extract keywords → pattern → find tests), File-based (find corresponding test file), All tests (run all **/.test.)

See: references/templates.md#step-0-scope-determination-templates for complete examples

---

Step 1: Execute Tests

Action: Use bmad-commands to run tests.

Execute: python .claude/skills/bmad-commands/scripts/run_tests.py --path . --framework auto --output json

Parse Response: Extract success, outputs (passed, total_tests, coverage_percent, failures), telemetry, errors

If tests fail: Report failed tests with details, suggest fixes, do not proceed with coverage analysis

See: references/templates.md#step-1-test-execution-templates for complete response formats and error handling

---

Step 2: Generate Coverage Report

Action: Parse coverage data and generate reports.

Coverage Metrics: Statements, Branches, Functions, Lines (each with covered/total/percent)

Generate Report: Parse coverage JSON, create text table, check thresholds (≥80% for each metric)

See: references/templates.md#step-2-coverage-report-templates for complete formats and threshold checking

---

Step 3: Analyze Coverage Gaps

Action: Identify uncovered code and categorize by criticality.

Gap Categories: Error Handling (High), Edge Cases (Medium), Rare Branches (Low)

Criticality Levels:

• Critical: Security, payments, data deletion, auth (Must Test)
• High: Error handling, business logic, state transitions (Should Test)
• Medium: Logging, non-critical errors, minor edge cases (Nice to Test)
• Low: Debug code, dev-only code, trivial getters (Optional)

See: references/templates.md#step-3-gap-analysis-templates for complete examples and assessment criteria

---

Step 4: Suggest Missing Tests

Action: Generate concrete test suggestions for coverage gaps.

For each gap: File/line, criticality, reason, concrete test example

Prioritization: Focus on HIGH (3-5 suggestions), then MEDIUM (2-3), LOW optional

See: references/templates.md#step-4-test-suggestion-templates for complete suggestion formats with test code

---

Step 5: Present Summary

Action: Provide comprehensive test execution summary.

Summary Includes:

• Scope, framework, duration, test results (passed/failed/total)
• Coverage report with thresholds (statements, branches, functions, lines)
• Coverage gaps categorized by priority (CRITICAL/HIGH/MEDIUM/LOW)
• Test suggestions with estimated time and coverage gain
• Next steps and recommendations

See: references/templates.md#step-5-complete-summary-templates for formatted output examples

---

Output

Return structured JSON with test results, coverage data, gaps array (file, lines, criticality, category), test suggestions, and telemetry

See: references/templates.md#complete-json-output-format for full structure

---

Error Handling

No tests found: Verify test files exist, check scope pattern | Tests failing: Report failures with details, suggest fixes | Coverage below threshold: Identify gaps, suggest missing tests | Framework not configured: Verify installation and configuration

See: references/templates.md#error-templates for complete error messages and solutions

---

Common Scenarios

Tests passing + good coverage (≥80%): Report success, highlight optional improvements | Tests passing + low coverage (<80%): Identify critical gaps, suggest HIGH priority tests | Tests failing: Report failures, suggest fixes, do not proceed with coverage analysis

---

Best Practices

Run tests frequently | Prioritize quality over coverage % | Test what matters (business logic, errors, edge cases) | Keep tests fast (mock dependencies) | Use meaningful test names

See: references/best-practices.md for detailed testing best practices

---

Routing Guidance

Use this skill when:

• Need to execute tests for implemented code
• Need coverage analysis
• Want to identify test gaps
• Need to validate implementation quality

Always use after:

• Feature implementation (implement-feature)
• Bug fixes (fix-bug)
• Code refactoring (refactor-code)

Before:

• Creating pull requests
• Deploying to production
• Code reviews

---

Reference Files

Detailed documentation in references/:

• templates.md: All output formats, complete examples, JSON structures, CI/CD integration
• test-execution-guide.md: Test configuration and execution details
• coverage-analysis-guide.md: Coverage parsing and threshold checking
• gap-analysis-guide.md: Analyzing uncovered code and categorization
• test-suggestions.md: Missing test suggestion templates
• best-practices.md: Testing and coverage best practices

---

Part of BMAD Enhanced Development Suite