# How `smoke.ps1` Executes and Validates Smoke Tests in the reverse-skill Repository

> Learn how smoke.ps1 executes and validates smoke tests in the reverse-skill repository. This script orchestrates tests and reports success through exit codes validated by test-p0-friction.ps1.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-18

---

**The `smoke.ps1` script orchestrates core functionality tests by invoking verification, routing, and case-management sub-scripts, then reports success via exit codes and log markers that `test-p0-friction.ps1` validates.**

The `smoke.ps1` script serves as the primary **smoke test entry point** for the `zhaoxuya520/reverse-skill` project. It coordinates multiple PowerShell modules to verify that routing coherence, case initialization, evidence handling, and master-route matrices function correctly on a clean environment. Understanding this execution flow helps developers debug failures and extend the test suite.

## How `smoke.ps1` Is Executed

The smoke test is **not run directly in CI pipelines**. Instead, the higher-level harness `test-p0-friction.ps1` invokes it with controlled parameters and captures all output for validation.

### Invocation from `test-p0-friction.ps1`

Located at `skills/scripts/test-p0-friction.ps1`, lines 29–33 construct the call:

```powershell
$smoke = Join-Path $scriptDir 'smoke.ps1'
& powershell -NoProfile -ExecutionPolicy Bypass -File $smoke `
    -LogDir (Join-Path $ScratchDir 'smoke-logs') -PackageRoot $PackageRoot 2>&1 |
    Tee-Object -FilePath $smokeLog | Out-Null
$smokeExit = $LASTEXITCODE

```

This pattern:
- Uses a **fresh PowerShell process** (`-NoProfile -ExecutionPolicy Bypass`) to avoid environmental contamination.
- Redirects all output (including errors via `2>&1`) through `Tee-Object` so logs appear both on console and in `$smokeLog`.
- Captures the exit code immediately in `$smokeExit` for validation.

### Manual Execution

Developers can run the smoke test locally:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/smoke.ps1 `
    -LogDir C:\temp\smoke-logs -PackageRoot .

```

## Internal Execution Flow of `smoke.ps1`

The script at `skills/scripts/smoke.ps1` sequences through discrete verification steps. Based on the source structure, the core entry points include:

| Step | Script | Purpose |
|------|--------|---------|
| 1 | `verify-routing-coherence.ps1` | Validates routing configuration consistency; must exit `0` |
| 2 | `master-route.ps1` | Executes sample master-route matrix to confirm rule parsing |
| 3 | `case-init.ps1` | Generates fresh case scaffold (`work/<case>/scope.md`) |
| 4 | `append-evidence.ps1` | Tests evidence appending and duplicate-ID rejection |
| 5 | `case-guard.ps1`, `test-routing.ps1`, `extract-summaries.ps1` | Guard enforcement, routing suite, and summary extraction |

The script loads these via `Join-Path $scriptDir '<script-name>'` and executes them with the `&` call operator. Each sub-script receives the `-LogDir` and `-PackageRoot` parameters to maintain consistent output locations.

### Routing Coherence Verification

Lines 50–58 of `smoke.ps1` demonstrate the pattern used throughout:

```powershell
$verify = Join-Path $scriptDir 'verify-routing-coherence.ps1'
& $verify -LogDir $LogDir -PackageRoot $PackageRoot
$verifyExit = $LASTEXITCODE
if ($verifyExit -eq 0) { Ok "verify-routing-coherence exit $verifyExit" }
else { Bad "verify-routing-coherence exit $verifyExit" }

```

The `Ok` and `Bad` helper functions provide color-coded console output while the exit code propagates for final assessment.

### Evidence Handling Validation

At line 141, `smoke.ps1` invokes `append-evidence.ps1` and specifically validates duplicate-ID rejection (line 177):

```powershell
Ok 'duplicate Evidence ID rejected without mutation'

```

This ensures the evidence system correctly guards against data corruption.

### Log Aggregation

After all entry points complete, lines 378–383 copy the primary `smoke.log` and [`SUMMARY.txt`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SUMMARY.txt) into the test harness scratch directory:

```powershell
Copy-Item (Join-Path $LogDir 'smoke.log') $ScratchDir -Force
Copy-Item (Join-Path $LogDir 'SUMMARY.txt') $ScratchDir -Force

```

## How Validation Occurs

Validation operates at **two levels**: exit code verification and log content inspection.

### Exit Code Validation

`test-p0-friction.ps1` maps `$smokeExit` to a simple status:

```powershell
if ($smokeExit -eq 0) { 'Ok' } else { 'Bad' }

```

A non-zero exit from any sub-script causes immediate failure classification.

### Log Content Validation

Lines 36–38 of `test-p0-friction.ps1` perform **pattern matching** against the aggregated log to confirm specific operations executed successfully:

| Pattern Group | Regex Pattern | Meaning |
|-------------|-------------|---------|
| Coherence check | `verify-routing-coherence\|VERIFY_EXIT=0\|ALL PASS` | Routing coherence verification passed |
| Core execution | `route apk\|parse master-route\|parse case-init` | Core parsing and routing steps completed |

Both patterns must be present for the test to report `Ok`; otherwise it reports `Bad`.

## Example Output Structure

A successful smoke run produces log entries like:

```

=== reverse-skill smoke | LogDir=C:\temp\smoke-logs | Host=pwsh ===
[OK] verify-routing-coherence exit 0
[OK] master-route completed
[OK] case-init generated scope
[OK] duplicate Evidence ID rejected without mutation
...

```

The `test-p0-friction.ps1` harness parses this output to extract the structured status markers.

## Summary

- **`smoke.ps1` is invoked by `test-p0-friction.ps1`** using an isolated PowerShell process with `-NoProfile -ExecutionPolicy Bypass`.
- **Six core scripts** are sequenced: `verify-routing-coherence.ps1`, `master-route.ps1`, `case-init.ps1`, `append-evidence.ps1`, plus supporting guard and routing tests.
- **Exit code validation** ensures each sub-script returns `0` on success.
- **Log pattern validation** in `test-p0-friction.ps1` confirms specific success markers appear in the aggregated output.
- **Log artifacts** (`smoke.log`, [`SUMMARY.txt`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SUMMARY.txt)) are preserved in the scratch directory for CI debugging.

## Frequently Asked Questions

### What triggers a smoke test failure?

A failure occurs when `smoke.ps1` returns a non-zero exit code, or when the log output lacks the required pass-signal patterns (`verify-routing-coherence|VERIFY_EXIT=0|ALL PASS` and routing/parsing markers). Either condition causes `test-p0-friction.ps1` to report `Bad`.

### Can I run `smoke.ps1` without the full test harness?

Yes. Run it manually with the `-LogDir` and `-PackageRoot` parameters. Ensure you have write access to the log directory and that all dependent scripts exist in the same directory as `smoke.ps1`.

### Why does `test-p0-friction.ps1` use pattern matching instead of just checking exit codes?

Exit codes confirm that scripts finished, but pattern matching verifies that they performed the *expected work*. This catches cases where a script exits cleanly but skips critical verification steps due to misconfiguration or silent errors.

### Where are the smoke test logs stored?

By default, `test-p0-friction.ps1` places logs in a `smoke-logs` subdirectory under its scratch directory. The final `smoke.log` and [`SUMMARY.txt`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SUMMARY.txt) are copied to the scratch root for CI artifact collection.