x-execute-tests

Global Output Policy

• Language: English ONLY.
• Tone: Technical, Direct, and Concise.
• Efficiency: Remove all conversational fillers and greetings to save tokens.

Skill: Run Tests

Purpose

Testing is critical in {{PROJECT_NAME}}. The project enforces strict coverage thresholds (line >= 95%, branch >= 90%). This skill guides test execution, coverage analysis, and gap identification.

Test Execution Commands

# All tests
{{TEST_COMMAND}}

# With coverage report
{{COVERAGE_COMMAND}}

# Specific test class (adapt to your build tool)
# Example: mvn test -Dtest=ClassName
# Example: ./gradlew test --tests ClassName

Coverage Thresholds

Metric	Minimum
Line Coverage	>= 95%
Branch Coverage	>= 90%

Test Structure

For full testing philosophy (8 test categories, data uniqueness, fixture patterns), read knowledge/testing/testing-philosophy.md.

Naming Convention

[methodUnderTest]_[scenario]_[expectedBehavior]

Examples:

• processTransaction_approvedAmount_returnsSuccess
• findById_nonExistent_returnsEmpty
• validate_nullInput_throwsException

Test Pattern (Arrange-Act-Assert)

Every test method follows AAA with clear separation:

// Arrange -- setup objects and data
// Act -- execute the method under test
// Assert -- verify the outcome

Test Categories

Category	When to Use	Tools
Unit	Domain logic, engines, mappers	Test framework + assertions
Integration	DB interactions, framework features	Framework test support
API	REST endpoints	HTTP test client
E2E	Full flow (request -> process -> persist -> response)	Integration framework
Contract	Protocol/format compliance	Parametrized tests
Performance	Latency SLAs, throughput	Load testing framework

Coverage Analysis

After running {{COVERAGE_COMMAND}}, analyze the coverage report.

Common Coverage Gaps and Solutions

Gap	Solution
Uncovered else branch	Add test for the negative case
Uncovered exception path	Test error paths with exception assertions
Uncovered default in switch	Add test with unexpected input
Uncovered record accessor	Usually covered indirectly; add direct test if not
Uncovered validation	Test with invalid inputs

Per-Class Coverage Report Format

+--------------------------+-------+--------+
|          Class           | Line  | Branch |
+--------------------------+-------+--------+
| ClassA                   | 100%  | 95.0%  |
+--------------------------+-------+--------+
| ClassB                   | 97.3% | 88.5%  |
+--------------------------+-------+--------+

Tests: XX passing, XX failing, XX errors, XX skipped
Global Coverage: XX% line / XX% branch

Assertion Rules

Read knowledge/testing/testing-conventions.md for {{LANGUAGE}}-specific test frameworks and assertion libraries.

• Use the project's standard assertion library (e.g., AssertJ, Hamcrest)
• NEVER use basic assertEquals/assertTrue if a fluent assertion library is available
• Test exception paths with assertThatThrownBy or equivalent
• Test Optional results with isPresent()/isEmpty()

Test Data

Fixture Pattern

Centralize test data in utility classes:

• final class + private constructor + static methods
• Naming: a{Entity}() or a{Entity}With{Variation}()
• Constants for default values
• Domain fixtures separate from protocol/format fixtures

Data Uniqueness

Tests that create resources (POST/INSERT) MUST generate unique identifiers to avoid conflicts between test runs.

Traceability Matrix (--traceability flag)

When invoked with --traceability [STORY-ID|EPIC-ID], generates a bidirectional requirement-to-test mapping report.

Usage

# Single story traceability
/x-execute-tests --traceability STORY-0007-0003

# Epic-wide traceability (consolidates all stories)
/x-execute-tests --traceability EPIC-0007

Output

Generates results/traceability/traceability-{ID}-{YYYY-MM-DD}.md containing:

1. Requirement -> Test -> Execution table mapping each @GK-N scenario to its test class, method, status (PASS/FAIL/SKIP), and line coverage
2. Unmapped Requirements — scenarios with no corresponding test
3. Unmapped Tests — test methods not linked to any story scenario
4. Coverage Summary — stories covered, scenarios covered, pass/skip/fail counts

Traceability Matrix Format

# Traceability Matrix — STORY-XXXX-YYYY
Generated: YYYY-MM-DD | Build: <commit-hash>

## Requirement -> Test -> Execution

| Req ID | Scenario | Test Class | Method | Status | Line Cov |
|--------|----------|------------|--------|--------|----------|
| AT-1   | scenario | TestClass  | method | PASS   | 94%      |

## Unmapped Requirements
- AT-N: description

## Unmapped Tests
- TestClass.method -> not linked to any story scenario

## Coverage Summary
- Stories covered: N/M
- Scenarios covered: N/M (X%)
- Scenarios PASS: N | SKIP: N | FAIL: N

Epic Consolidation

For EPIC-ID, the matrix consolidates all stories in the epic with one section per story and a global summary at the end with aggregated totals.

Integration Notes

• Invoked by x-implement-story during Phase 2 (G7) and Phase 4
• Invoked by x-implement-task during Step 4
• Coverage report consumed by x-review-codebase skill (QA engineer)
• Thresholds enforced by x-lib-verify-group in G7 verification