scenario-testing CLAUDE.md

Scenario Testing Plugin

Overview

This plugin enforces end-to-end testing with real dependencies instead of mocks. It validates that features actually work by exercising real systems with real data.

Skill Included

scenario-testing

Trigger keywords: test, mock, validate, feature complete, integration test, end-to-end, e2e, testing

When to use:

• Writing tests for new features
• Validating that code actually works
• When tempted to use mocks
• Before declaring work complete
• After fixing bugs

What it does:

1. Enforces "NO FEATURE IS VALIDATED UNTIL A SCENARIO PASSES WITH REAL DEPENDENCIES"
2. Requires scenarios in .scratch/ directory (gitignored)
3. Prohibits mocks - must use real dependencies (sandbox/test mode acceptable)
4. Ensures scenarios run independently (no ordering dependencies)
5. Extracts recurring patterns to scenarios.jsonl (committed)

Definition of done:

• Scenario in .scratch/ passes with zero mocks
• Real dependencies exercised
• .scratch/ remains gitignored
• Patterns extracted to scenarios.jsonl

Core Principle

The Iron Law: "NO FEATURE IS VALIDATED UNTIL A SCENARIO PASSES WITH REAL DEPENDENCIES"

Mocks create false confidence. Only scenarios exercising real systems validate that code works.

The Truth Hierarchy

1. Scenario tests (real system, real data) = TRUTH
2. Unit tests (isolated) = human comfort only
3. Mocks = lies hiding bugs

"A test that uses mocks is not testing your system. It's testing your assumptions about how dependencies behave."

Required Practices

1. Write Scenarios in .scratch/

# .scratch/test-feature.py - GITIGNORED
def test_user_can_register():
    # Hit real database
    user = register_user(email="[email protected]")

    # Hit real auth service (test mode)
    token = authenticate(user)

    # Verify against real storage
    assert load_user(user.id) is not None

2. Promote Patterns to scenarios.jsonl

{"name":"user-registration","description":"User can register and authenticate","given":"New user credentials","when":"User registers","then":"User exists in DB and can authenticate","validates":"Registration flow"}