agentleFS
RidhuanDEVRidhuanDEV/claude-skills/shadow-test/SKILL.md

shadow-test

Skill1 starsChanged yesterdayMITView on GitHub

Polyglot Automated Unit, Integration & Contract Testing. Use when writing or fixing Vitest/Jest, Pytest, Go test, Pest/PHPUnit, JUnit 5, xUnit, Rust, or Flutter tests. Do NOT use for RAG/LLM evals (/shadow-eval) or Pre-UAT k6 load tests (/shadow-perf).

  • Deletes or force-pushes

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 3 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill whenever the Monarch asks to write, expand, fix, or audit unit tests, integration tests, or API contract tests in any …

    line 8
  2. Very specific:

    Read references/POLYGLOT-TESTING-MATRIX.md for idiomatic test structures across TypeScript/Node/React, Python, Go, PHP/Laravel, …

    line 14
  3. Distinctive:

    Integration / Component Tests (Highest ROI for Backend APIs): Test the full route -> validation -> service -> database/transaction boundary …

    line 23
  4. Very specific:

    Run affected module tests first (vitest related, pytest --lf, go test ./pkg/...) for fast feedback before running the full test suite.

    line 29
  5. Very specific:

    Mutation & Fault/Race Injection: Verify critical business tests catch seeded bugs (mutation mindset).

    line 33
  6. Very specific:

    Flaky-Test Triage: Never ignore intermittent CI failures or blindly wrap with retries.

    line 34
  7. Very specific:

    Never leave exited test or migration-verification containers (*-test-<timestamp>, *-migration-verification*), anonymous volumes, or …

    line 37
  8. Very specific:

    Start at most one ephemeral DB container per test suite run and isolate individual tests via transactions (BEGIN ...

    line 39
  9. Very specific:

    Always run with an explicit project name (-p <project>-test) and tear down containers, anonymous volumes, AND locally built test images in …

    line 59
  10. Very specific:

    If a test builds a temporary image (docker build -t <app>-test:temp), always remove it in finally (docker image rm -f <app>-test:temp).

    line 64
  11. Very specific:

    Before reporting tests as VERIFIED-LOCAL, run python "shadow-quality/scripts/shadow_gate.py" --repo .

    line 66
  12. Distinctive:

    State & Container Isolation: Verify zero leftover test records in development databases AND zero leftover Docker test containers, anonymous …

    line 80

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Shadow Test (/shadow-test) — Polyglot Automated Testing, Risk-Based Pyramid & Contract Compatibility

Use this skill whenever the Monarch asks to write, expand, fix, or audit unit tests, integration tests, or API contract tests in any programming language or framework.


1. Local Knowledge Base Routing

  1. Read references/POLYGLOT-TESTING-MATRIX.md for idiomatic test structures across TypeScript/Node/React, Python, Go, PHP/Laravel, Java/Kotlin, C#/.NET, Rust, and Dart/Flutter.
  2. For JavaScript/TypeScript/Node.js backend & frontend testing, consult references/vendor/GoldbergYoni_JS_Testing_Best_Practices.md.

2. Enhanced Testing Doctrine

A. Risk-Based Test Pyramid

Prioritize testing effort where business and financial risk is highest:

  1. Integration / Component Tests (Highest ROI for Backend APIs): Test the full route -> validation -> service -> database/transaction boundary using real test DB transactions or Testcontainers rather than brittle mocks of internal repositories.
  2. Pure Domain Unit Tests: Fast, exhaustive table-driven/parameterized tests for pricing formulas, tax/discount calculations, state machine transitions, and permission evaluators.
  3. Consumer/Provider Contract Tests (Paired with /shadow-api & /shadow-compat): Verify HTTP status codes, response envelopes, required fields, and nullability match openapi.yaml so frontend/mobile consumers never break.

B. Regression Selection for Bug Fixes

  • Whenever fixing a bug or production incident (/shadow-maintain), write a targeted regression test that reproduces the exact failure first, then verify the fix turns it green.
  • Run affected module tests first (vitest related, pytest --lf, go test ./pkg/...) for fast feedback before running the full test suite.

C. Deterministic Fixtures, Advanced Techniques & Zero Flakiness

  • Property-Based & State-Machine Testing: For monetary math, parsers, serializers, and order/approval workflows, pair example tests with property-based checks (fast-check, Hypothesis, proptest) and randomized state-transition sequences verifying core invariants hold across arbitrary inputs.
  • Mutation & Fault/Race Injection: Verify critical business tests catch seeded bugs (mutation mindset); inject concurrent duplicate requests, DB deadlocks, or simulated ack timeouts when testing async/transactional code (/shadow-concurrency).
  • Flaky-Test Triage: Never ignore intermittent CI failures or blindly wrap with retries; isolate shared mutable globals, wall-clock timers (vi.useFakeTimers(), freezegun), seeded RNGs, and per-test DB transaction rollback (BEGIN ... ROLLBACK) before reporting PASS.

D. Mandatory Docker & Test Database Teardown (Zero Orphan Containers/Volumes/Images)

Never leave exited test or migration-verification containers (*-test-<timestamp>, *-migration-verification*), anonymous volumes, or temporary test-built images behind in Docker:

  1. Reuse One Container Per Suite (Never One Container Per Test):
    • Start at most one ephemeral DB container per test suite run and isolate individual tests via transactions (BEGIN ... ROLLBACK / SAVEPOINT) or disposable schemas (CREATE DATABASE test_<id>; ... DROP DATABASE test_<id>;). Never spawn a new postgres/mariadb/mysql container per test file.
  2. Always Pass --rm & --label shadow.ephemeral=true + Guaranteed try / finally Teardown:
    • Single Container (docker run):
      • PowerShell:
        $ContainerName = "app-test-db-$PID"
        try {
            docker run -d --rm --label shadow.ephemeral=true --name $ContainerName -e MYSQL_ROOT_PASSWORD=test mariadb:10
            # run migrations & tests...
        } finally {
            docker rm -f -v $ContainerName 2>$null | Out-Null
        }
      • Bash / POSIX:
        CONTAINER_NAME="app-test-db-$$"
        trap 'docker rm -f -v "$CONTAINER_NAME" >/dev/null 2>&1 || true' EXIT
        docker run -d --rm --label shadow.ephemeral=true --name "$CONTAINER_NAME" -e MYSQL_ROOT_PASSWORD=test mariadb:10
    • Docker Compose Test Stack:
      • Always run with an explicit project name (-p <project>-test) and tear down containers, anonymous volumes, AND locally built test images in finally / trap EXIT:
        docker compose -p "$Project-test" -f docker-compose.test.yml down -v --rmi local --remove-orphans
    • Temporary Test Images (docker build):
      • If a test builds a temporary image (docker build -t <app>-test:temp), always remove it in finally (docker image rm -f <app>-test:temp).
  3. Post-Test Leak Verification:
    • Before reporting tests as VERIFIED-LOCAL, run python "shadow-quality/scripts/shadow_gate.py" --repo . --check-docker-leaks to verify zero leftover test containers or images remain.

3. Mandatory 8-Point Test Coverage Matrix

For every module, service, or endpoint under test, cover:

  1. Happy Path (200/201): Assert observable output and persisted database/queue state.
  2. Validation & Schema Failure (400/422): Missing required fields, invalid types, negative numbers.
  3. Unauthenticated (401): Missing, malformed, or expired token.
  4. Forbidden / Cross-Tenant IDOR (403/404): User from Tenant A attempting to access or mutate Tenant B's resource (/shadow-auth).
  5. Not Found (404): Valid UUID/ID not present in DB.
  6. Idempotency / Conflict (409): Duplicate unique key or repeated Idempotency-Key request (/shadow-cache).
  7. Boundary Values: 0, -1, empty list [], max + 1, timezone/midnight edge cases, decimal/currency rounding.
  8. State & Container Isolation: Verify zero leftover test records in development databases AND zero leftover Docker test containers, anonymous volumes, or temporary test-built images after suite teardown.

4. Execution Approval & Intent Boundary (L0–L4)

  • Bounded unit/integration tests on verified local/sandbox environments are L1_SAFE_VERIFICATION. A unit-test request NEVER automatically authorizes L2 broad E2E suites (/shadow-browser) or L3 load/stress testing (/shadow-perf); require explicit approval (execution_approval_gate.py).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.