npm package: @redredchen01/test-runner
Description: Test execution and management CLI — run, watch, coverage, snapshot, report, parallel, filter
Author: redredchen01
Latest version: 1.0.0

# @redredchen01/test-runner

> Test execution and management CLI — run, watch, coverage, snapshot, report, parallel, filter

[![npm version](https://img.shields.io/npm/v/@redredchen01/test-runner.svg)](https://www.npmjs.com/package/@redredchen01/test-runner)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Install

```bash
npm install -g @redredchen01/test-runner
```

## Quick Start

```bash
# Auto-detect framework and run tests
test-runner run

# Watch for changes
test-runner watch

# Check coverage with threshold
test-runner coverage --min-coverage 80

# Run tests matching a pattern
test-runner filter --pattern "login"
```

## Commands

### `run` — Execute tests

Auto-detect and run tests. Supports jest, mocha, pytest, bats, go test, and cargo test.

```bash
test-runner run
test-runner run --framework jest --path ./src
test-runner run --framework pytest --verbose --bail
```

Options: `--framework`, `--path DIR`, `--verbose`, `--bail`, `--json`

---

### `watch` — Watch and re-run

Watch for file changes and automatically re-run tests. Uses fswatch if available, falls back to polling.

```bash
test-runner watch
test-runner watch --path ./src --framework jest
test-runner watch --pattern "*.py" --debounce 3
```

Options: `--path DIR`, `--pattern GLOB`, `--framework`, `--debounce SECS`, `--json`

---

### `coverage` — Collect coverage

Run tests with coverage collection. Fails with exit code 1 if coverage is below `--min-coverage`.

```bash
test-runner coverage
test-runner coverage --framework jest --min-coverage 80
test-runner coverage --framework pytest --output html
```

Options: `--framework`, `--min-coverage N`, `--output text|html|json`, `--json`

---

### `snapshot` — Manage snapshots

Update, clear, or list test snapshot files (jest and pytest).

```bash
test-runner snapshot list
test-runner snapshot update --framework jest
test-runner snapshot clear
```

Subcommands: `update`, `clear`, `list`
Options: `--framework`, `--json`

---

### `report` — Generate report

Parse test output from a file or stdin and generate a summary report.

```bash
test-runner run 2>&1 | test-runner report
test-runner report --input output.txt --format html --output report.html
```

Options: `--input FILE`, `--format text|json|html`, `--output FILE`, `--json`

---

### `parallel` — Run in parallel

Split test files across multiple workers and run them concurrently.

```bash
test-runner parallel
test-runner parallel --workers 4
test-runner parallel --framework jest --workers 8
```

Options: `--workers N`, `--framework`, `--split-by file|test`, `--json`

---

### `filter` — Filter tests

Run only tests matching a name pattern or tag/marker.

```bash
test-runner filter --pattern "login"
test-runner filter --pattern "^should handle" --framework jest
test-runner filter --tag slow --framework pytest
test-runner filter --pattern "TestUser" --framework go
```

Options: `--pattern REGEX`, `--tag TAG`, `--framework`, `--json`

---

## Auto-Detection

`test-runner` auto-detects the framework by scanning project files:

| Framework | Detection Signal                          |
|-----------|-------------------------------------------|
| jest      | `package.json` contains `"jest"`          |
| mocha     | `package.json` contains `"mocha"`         |
| pytest    | `requirements.txt` or `pyproject.toml` with `pytest` |
| bats      | `*.bats` files present                    |
| go        | `go.mod` present                          |
| cargo     | `Cargo.toml` present                      |

## JSON Output (Pipe Protocol)

All commands support `--json` for structured output compatible with the Skill Foundry pipe protocol:

```bash
test-runner run --json | some-other-tool
test-runner coverage --json | jq '.data.coverage_pct'
```

## License

MIT