How to Run Unit Tests for reverse-skill: Complete PowerShell Testing Guide

Run the test-p0-friction.ps1 script from the repository root using PowerShell with bypass execution policy to execute the full test suite covering smoke tests, case initialization, evidence handling, and routing validation.

The reverse-skill repository provides a lightweight, self-contained testing framework written entirely in PowerShell. This guide walks you through how to run unit tests for reverse-skill, interpret results, and validate your installation without needing external test runners or complex dependencies.

Prerequisites for Running reverse-skill Tests

Before executing any tests, ensure your environment meets these requirements:

• PowerShell 5.1+ on Windows, or PowerShell 7 on Linux/macOS
• External utilities referenced by skills (e.g., nmap, nuclei) available on $PATH — the harness tolerates missing tools and skips relevant checks
• No special environment variables required; scripts automatically create temporary directories under $env:TEMP

The test scripts are located in skills/scripts/ and operate independently without requiring a formal test framework installation.

Running the Main Test Suite

The primary entry point is skills/scripts/test-p0-friction.ps1, which orchestrates end-to-end validation of core workflows.

Execute the Full Test Harness

# From the repository root

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/test-p0-friction.ps1

This command:

1. Creates a temporary scratch folder
2. Runs all test steps sequentially
3. Prints [OK] or [FAIL] markers for each verification
4. Returns exit code 1 if any failures occurred

Test Coverage in test-p0-friction.ps1

Test Category	Verification Target	Source Location
Smoke test	Routing and verification stages complete cleanly	Lines 29-38
Case-init (granted)	AuthGranted creates ready-to-act case with valid scope.md	Lines 39-60
Bare case-init	Default case status remains pending without auth	Lines 63-71
Append-evidence	Evidence file created with correct title, repro command, excerpt	Lines 73-96
Recon-pipeline sanity	Origin/Referer hints and network references present	Lines 99-107
Routing coherence	verify-routing-coherence.ps1 exits zero	Lines 14-19
Chinese routing samples	master-route.ps1 correctly routes Chinese-language hints	Lines 20-30
Case-guard	Exit codes: 0 (ready), 2 (pending), 0 with -Force	Lines 33-41
Lab case with AuthGranted	Lab-only case preserves granted status and lab_only mode	Lines 43-65
Junk AuthStatus handling	Stray AuthStatus does not override prior AuthGranted	Lines 66-83
Special-char evidence	-RawExcerptFile transports arbitrary Unicode safely	Lines 85-100

Running the Workflow Safety Check

For CI/CD validation, execute the secondary test script:

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/test-workflow-title-safety.ps1

This script inspects .github/workflows/auto-merge-journal.yml to verify that PR metadata is handled as plain data and no shell injection vectors exist. Run this whenever you modify GitHub Actions workflows.

Quick Validation: Running Individual Components

For faster feedback during development, execute specific test components directly:

# Smoke test only — minimal routing and verification check

powershell -NoProfile -ExecutionPolicy Bypass -File .\skills\scripts\smoke.ps1 -LogDir .\tmp\smoke-logs

# Verify routing matrix coherence explicitly

powershell -NoProfile -ExecutionPolicy Bypass -File .\skills\scripts\verify-routing-coherence.ps1

Interpreting Test Results

The test harness uses explicit output markers:

• [OK] — Component behaved as expected
• [FAIL] — Assertion failed; details printed immediately

Failed tests appear in a final summary. The script returns exit code 1 if any failures occurred, making it suitable for CI pipeline integration.

Example output structure:

[OK] smoke test - routing and verification passed
[OK] case-init with AuthGranted - scope.md generated
[FAIL] recon-pipeline sanity - missing 'nuclei' in PATH
...
Summary: 10 passed, 1 failed

Key Test Files Reference

File	Purpose
skills/scripts/test-p0-friction.ps1	Main end-to-end test harness
skills/scripts/smoke.ps1	Minimal sanity check for routing
skills/scripts/case-init.ps1	Case folder and scope.md creation
skills/scripts/append-evidence.ps1	Evidence markdown generation
skills/scripts/verify-routing-coherence.ps1	Routing matrix validation
skills/scripts/master-route.ps1	Natural-language hint routing
skills/scripts/test-workflow-title-safety.ps1	CI workflow security check

Summary

• Primary command: powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/test-p0-friction.ps1
• Test location: All scripts reside in skills/scripts/
• No dependencies: Pure PowerShell implementation with automatic temp directory management
• CI-ready: Non-zero exit codes signal failure; explicit [OK]/[FAIL] markers parse easily
• Modular: Run smoke.ps1 or individual components for targeted validation

Frequently Asked Questions

Can I run reverse-skill tests on Linux or macOS?

Yes. Install PowerShell 7 and execute the same commands. The test harness detects the platform and adjusts paths accordingly. External tools like nmap or nuclei must still be available on $PATH for full coverage.

What happens if required external tools are missing?

The test suite skips checks dependent on missing utilities and marks them accordingly. Core PowerShell-based validations (routing, case handling, evidence generation) continue to execute normally.

How do I debug a failing test?

Each test prints its assertion details on failure. Navigate to the specific lines in test-p0-friction.ps1 referenced in the failure message, then run the underlying script manually with verbose flags to isolate the behavior.

Is there a way to run tests in a clean environment?

The scripts automatically create and clean up temporary directories under $env:TEMP. No manual isolation is required. For complete freshness, clear $env:TEMP\reverse-skill-* directories before execution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}