Installation
Test Pulse commands
Copy-paste reference for zephex check test — subcommands, flags, output modes, billing, cancellation, and what you see while tests run.
Guide: Test Pulse overview · npx zephex install · API key
Install
Same zephex npm package as MCP — ~5 MB download, ~25 MB on disk. Test Pulse adds 0 MB extra. See install & size and local vs cloud.
shell
npx -y zephex check test # ~5 MB once (npm cache)npm install -g zephex # ~25 MB on disk# npm tarball includes TEST-PULSE.mdAliases
All of these route to the same tool:
shell
zephex check testzephex check-testzephex checktestzephex testszephex testzephex test-pulseRun commands
Full test run
shell
# Default — brief summary + failures + sample test fileszephex check test # One test file (fast iteration)zephex check test --command "bun test src/__tests__/auth.test.ts" # See detected command without running (0 credits)zephex check test --dry-run # Machine-readable JSON + CI exit codezephex check test --json --strictBefore run: Framework, runner command, and Ctrl+C hint print to stderr. During run: animated spinner + per-file scroll lines. After: brief report with coverage hint and expand footer.
Stop a run
- Ctrl+C once — cancels the test child process (process group on macOS/Linux). Should stop within ~1 second.
- Ctrl+C twice — force quit the CLI immediately (exit 130).
- Partial results are not saved to session on cancel.
shell
# Pre-run banner always shows:Cancel Ctrl+C # During run — press Ctrl+C once:error: Test run cancelled.# exit 130Live progress
What prints while tests run
All progress goes to stderr (stdout stays clean for --json). Hidden with -q / --quiet.
| Line type | Example | When |
|---|---|---|
| Pre-run banner | Framework bun / Runner bun test / Cancel Ctrl+C | Once, before spawn |
| Spinner (in-place) | handlers.test.ts · 12 files · ✓69 ✗5 · 180s | Updates every ~200ms |
| Scroll line | ▸ tests/mcp-tools.test.ts · ✓45 ✗2 · 180s | Each new test file + every 12s |
Spinner fields
- File part — current
.test.tsfile basename, or last test name if file header not yet parsed. - N files — count of distinct test files seen so far.
- ✓ / ✗ — running pass/fail tally from runner output.
- Ns — wall-clock elapsed since spawn.
Parsed runner patterns (bun, vitest, jest, pytest)
text
tests/foo.test.ts # file header line(pass) tests/foo.test.ts # bun non-TTY CI formatRUN tests/foo.test.ts # vitest/jesttests/test_auth.py::test_login # pytestScreenshot of the old behavior (project label only): Live progress guide.
Read session (0 credits)
These read the last run from ~/.zephex/test-sessions/ (30 min TTL). No re-run, no billing.
| Command | What you get |
|---|---|
| check test status | Health dashboard: coverage bar, 0% file warnings, top failure, drill-down links |
| check test summary | One-screen blurb — fastest read |
| check test list | All test files with ✓/✗/skip counts per file |
| check test failures | Failure blocks only: file:line, Expected/Received, rerun command |
| check test flaky | Flaky hints (needs prior runs with --flaky) |
| check test coverage | Per-file coverage table from last lcov artifact |
| check test fix-prompt | AI fix prompt from last run — failures, files, reproduce commands. Add --copy to copy to clipboard. |
| check test learn | What each command does + links to full docs (terminal guide) |
| check test last | Repeat last brief report |
| check test --full | Full report: coverage table, all test files, slow/skipped sections |
shell
zephex check test statuszephex check test failureszephex check test listzephex check test --fullOutput modes
Default vs expanded
- Default (brief): Project blurb, coverage bar, failures with Expected/Received, failed test files, sample of passed files, expand footer.
- --full:Everything — coverage by file table, all test files, slow tests (>2s), skipped groups.
- --quiet: Minimal stderr; still prints report unless JSON.
- --verbose: Includes suppressed log tail + full output mode.
- --json: Full
TestRunResultJSON on stdout.
Default report sections
text
Runner / Duration / Inventory / Result / CoverageFailures (fix first) ← file:line, Expected/Received, rerun lineFailed files ← which .test.ts files had failuresPassed files (sample) ← first N passing filesSlow (>2s) ← only in --fullSkipped ← only in --fullShow more footer ← list / failures / --full hintsFlags
shell
--cwd <path> Project root (monorepo / not in project folder)--command <cmd> Override detected test command--dry-run Show command only (0 credits)--strict Exit 1 on FAIL or ERROR--failed-only Re-run prior failures (needs session)--no-coverage Skip lcov collection (faster)--no-coverage-table Hide per-file table in --full--coverage-top <n> Max files in coverage table (default 15)--diff [branch] Patch coverage on changed lines--flaky Record outcomes + enable flaky hints--why "<question>" Follow-up from session (30m, no network)--refresh Ignore cache for --why--timeout <ms> Max runtime (default 30m)-q, --quiet Minimal stderr (hides live progress)-v, --verbose Raw logs + full output--json JSON output--api-key <key> Override API key for cloud uploadProject detection
Where to run
shell
# ✅ Correct — inside project with package.json + testscd ~/projects/my-appzephex check test # ✅ Monorepo — point at packagezephex check test --cwd mcp-proxy # ✅ Smoke one filezephex check test --command "bun test tests/handlers.test.ts" # ❌ Wrong — home directory (will error with nearby projects list)cd ~zephex check testBilling
Credits
- 1 credit per completed full run (flat — not 1–2).
- ~10 test runs ≈ 10 credits from your monthly MCP pool.
- 0 credits: status, summary, list, failures, flaky, coverage, last, dry-run.
- Dev bypass:
ZEPHEX_TEST_PULSE_FREE=1 - Optional cloud upload requires API key +
test_scanstable.
Frameworks
Auto-detected runners
bun, vitest, jest (+ jest-junit), pytest (+ pytest-cov), go (gotestsum), cargo (nextest). Detection reads package.json scripts and project markers.
shell
zephex check test --dry-run # see what Zephex pickedzephex check test --command "npm test" # overridezephex check test --command "pytest -x" # pythonWorkflows
Copy-paste workflows
Pre-push (full suite)
shell
cd my-appzephex check test --strict# if FAIL:zephex check test failureszephex check test --failed-onlyWhile fixing one failure
shell
zephex check test failures# copy the ↳ rerun line from output, e.g.:bun test tests/auth.test.ts -t "rejects expired token"Coverage drill-down
shell
zephex check testzephex check test statuszephex check test coveragezephex check test --fullMonorepo (mcpHub example)
shell
cd mcp-proxyzephex check test# or from repo root:zephex check test --cwd mcp-proxyNatural language (CLI router)
shell
zephex "are tests passing"zephex "what tests are failing"zephex "run tests"CI / GitHub Actions
yaml
- run: npx zephex check test --json --strict env: ZEPHEX_API_KEY: ${{ secrets.ZEPHEX_API_KEY }} working-directory: mcp-proxyCloud
History (API key)
shell
zephex check test history # last 10 cloud uploadsTests always execute locally. The server stores structured results only — it never runs your test command on Zephex infrastructure.