check_test
Run once after edits, then query failures, coverage, and fix-first triage from the session cache for free.
Zephex is a hosted Model Context Protocol (MCP) server that gives AI coding agents structured test health through check_test — plus nine other built-in tools and one API key — so agents know what broke, where, and what to fix first without parsing 600-line test logs.
When to use
- After code changes, before push — confirm nothing broke.
- When the user asks if tests pass.
- To identify which module or area has the most failures.
- To get a fix-first triage order from failure clusters.
- With diff_base to see only failures in changed code.
When not to use
- You haven't made code changes yet — run tests after editing, not before.
- You need package-level CVE scanning — use check_package instead.
- You need a full project architecture overview — use explain_architecture.
- You need to scope a task before coding — use scope_task… wait, that's this tool now.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| path | string | Yes* | Absolute path or github:owner/repo (required for run/detect). |
| task | enum | Yes | run | detect | status | summary | list | failures | coverage | fix_prompt | history | why | compare |
| session_id | string | No | Re-use a prior session for free queries. |
| area | string | No | Scope to a module: auth, billing, proxy, etc. |
| file_filter | string | No | Glob to filter test files. |
| diff_base | string | No | Git ref for diff-scoped failures. |
| with_coverage | boolean | No | Include coverage data (default: false). |
Limits: Session cache lives ~1 hour. The run task consumes 1 hosted credit; session queries are free. Coverage requires a compatible test framework (bun:test, jest, vitest, pytest with --coverage).
Try it — copy a prompt
Paste into Cursor, Claude Code, Windsurf, VS Code, or any editor with a hosted MCP connection.
Before you call it
- Zephex API key and hosted MCP in your editor.
- A project with runnable tests and a recognized test framework.
- **path** as absolute project root or github:owner/repo (required for run/detect).
- Optional **diff_base** to scope results to changed files.
Token and request cost
A single run call (1 credit hosted) returns the full health picture in ~300-800 tokens. Session queries (list, failures, why) cost 0 credits and ~100-300 tokens each.
Example
MCP tools/call
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "check_test", "arguments": { "path": "/path/to/project", "task": "run", "area": "auth", "with_coverage": true } }}Response shape
Response shape
{ "health": "degraded", "broken_areas": ["auth", "billing"], "fix_first": ["auth:verifyToken returns 401 for valid tokens"], "failure_clusters": [ { "area": "auth", "count": 3, "sample": "verifyToken › returns 200 with valid JWT" } ], "coverage_by_area": { "auth": 78, "billing": 92, "proxy": 88 }, "blind_spots": ["src/middleware/rate-limit.ts has no tests"], "session_id": "sess_abc123"}Which Zephex tool when
| Task | Use this tool | Not this tool |
|---|---|---|
| Check if tests pass after edits | check_test | read_code |
| Get fix-first triage order | check_test | keep_thinking |
| Find coverage by module | check_test | find_code |
| Debug a single failure | check_test task=why | audit_headers |
What it can do in your codebase
- Run full test suite or scope to a specific area (auth, billing, proxy, etc.)
- Return broken_areas — which modules have failures
- List fix_first — ordered triage from failure clusters
- Surface failure_clusters with sample failure messages per area
- Report coverage_by_area when with_coverage is set
- Detect blind_spots — untested files or modules
- Generate area_graph and graph_mermaid for test dependency visualization
- Compute health — healthy / degraded / broken verdict
- Scope to diff with diff_base — only failures in changed code
- Free session queries: list, failures, status, why, compare (0 credits)
Common response fields
Why teams use it
Run once, query freely
The run task costs 1 credit. Every subsequent query (list, failures, why, status, compare) hits the session cache at 0 credits.
Module-level triage
Scope to area: auth, billing, proxy, etc. Get fix_first ordered by severity within each area.
Diff-aware testing
Set diff_base to a git ref and get failures_in_diff — only failures in code you changed.
Visual dependency graph
area_graph and graph_mermaid show how test areas depend on each other.
Fields in the check_test response
| Field | Meaning |
|---|---|
| health | healthy | degraded | broken — overall verdict. |
| broken_areas | Modules with at least one failing test. |
| fix_first | Ordered list of what to fix, by impact. |
| failure_clusters | Grouped failures per area with sample messages. |
| coverage_by_area | Code coverage percentage per module. |
| blind_spots | Files or modules with no test coverage. |
How it fits your workflow
- Read health — if "healthy", you are good to push.
- Review broken_areas and fix_first for triage order.
- Run check_test task=why on a specific failure for root cause.
- Fix code, then run check_test again to confirm green.
- Use task=compare to see improvement between runs.
Troubleshooting
- No tests detected → verify the project has a recognized test framework (bun:test, jest, vitest, pytest, cargo test, go test).
- Empty broken_areas → all tests pass! Check health field for 'healthy'.
- Coverage data missing → re-run with with_coverage:true and a compatible test framework.
- Session not found → task=run first to establish a session, then query with task=list|failures|why.
- 429 rate limit → the 'run' task costs 1 credit (Free 100/day rolling 24h); session queries are free.
How to verify it works
- Connect Zephex MCP; confirm check_test in tools/list.
- Run: "check_test: run with coverage on auth module"
- Response must include health, broken_areas, and session_id; then follow with task=why on a failure.
Common questions
Billing and plan limits: FAQ, usage limits.
Which MCP tool should I use to verify my changes work?
Use check_test with task=run and optional area filter. It runs the test suite and returns structured health. After fixing failures, use task=compare to see the improvement.
How is check_test different from running tests manually?
check_test parses the output into agent-native fields: broken_areas, fix_first, failure_clusters, coverage_by_area. Instead of a 600-line log you get structured JSON your agent can act on. Session queries are free after one run.
How do I use check_test with Cursor?
Add Zephex to .cursor/mcp.json, restart, and paste a prompt like 'check_test: run with coverage on auth — show fix_first.' The agent will call the tool and return structured health data.
What does the area parameter do?
It scopes test execution to a specific module: auth, billing, proxy, db, etc. The exact areas depend on your project's test structure. Omitting it runs the full suite.
How do session queries work?
After one task=run call, all subsequent queries on the returned session_id (list, failures, status, why, compare) are free. You can ask 'why did auth:verifyToken fail?' without re-running tests.
Also audit: check_package for dependency CVEs before push.
Billing: Each tool call counts as one request on your Zephex plan (Free includes 555 requests/month). See usage limits for tier details. Usage limits.
Data: Executes test commands in the provided path and returns structured output as JSON. Test output is processed ephemerally. Data use.
check_package audits dependency safety; check_test audits test health — use both before push, then read_code.
For AI agents (JSON)
{"tool":"check_test","when":"after code changes or user asks about tests","then":["read health first, then task=why on failures"]}