# Testorax

> Autonomous AI browser testing: give it a URL, get back a bug report with screenshots — no test code to write.

Testorax is a cloud testing service. You give it the URL of a deployed web app; it crawls that app, generates test scenarios using AI, runs them in real Chromium browsers on a cloud server, and delivers a structured bug report with per-step screenshots and error messages. There is no SDK to install, no test files to write, and no CI configuration required.

The service is conversational. If it cannot reach a page because it needs login credentials, encounters an ambiguous product flow, or generates zero useful scenarios, it pauses the run and posts a message back to the user. Once the user replies (through the web UI, CLI, or MCP), the run resumes from where it stopped. This makes it safe to run on apps with auth-gated flows without baking credentials into config files.

Testorax is designed to be called from an AI coding agent. The MCP server exposes 27 tools covering the full run lifecycle: create a run, track progress, read the report, inspect individual failing scenarios with step-level diagnostics, retry failures, cancel, and more. The CLI provides the same surface for terminal workflows. The REST API is available for direct integration.

## MCP Server (Claude Code, Cursor, Windsurf, Cline, any MCP-compatible agent)

Install:
```bash
npm install -g testorax-mcp
```

Add to your MCP config (Claude Code: `~/.claude/claude_desktop_config.json`, Cursor: MCP settings panel):
```json
{
  "mcpServers": {
    "testorax": {
      "command": "testorax-mcp",
      "env": {
        "TESTORAX_EMAIL": "your@email.com",
        "TESTORAX_API_KEY": "ttx_..."
      }
    }
  }
}
```

Get your API key at https://testorax.com/account/api-key

**Key MCP tools:**
- `create_run` / `create_bypass_run` — start a new test run
- `run_status` — check if a run is in progress, paused, or complete
- `get_report` — full bug report for a completed run
- `failure_context` — step-by-step diagnostic for a failing scenario (screenshots, selectors, network failures)
- `list_runs` — recent runs for your account
- `run_suite` — re-run a saved test suite by name
- `list_messages` / `send_message` — read/reply when Testorax pauses and asks a question
- `retry_failed` — re-execute only the scenarios that failed in a previous run
- `regressions` — compare two runs and surface newly-failing scenarios
- `get_dashboard` — KPIs and trend data for your account
- `run_app_group` — trigger runs on a group of URLs in parallel

## CLI

Install:
```bash
npm install -g testorax
```

Configure:
```bash
testorax login
```

Common commands:
```bash
testorax run https://acme-corp.com --tier full_test
testorax tail <run-id>
testorax report <run-id>
testorax suites run <suite-name>
testorax messages list <run-id>
testorax messages send <run-id> "username is admin@acme-corp.com, password is demo"
```

## REST API

Base URL: `https://testorax.com`

Authentication: pass `X-Api-Key: ttx_...` header on all API requests. Get your key from `/account/api-key`.

**Start a run:**
```
POST /api/runs/bypass
X-Api-Key: ttx_...
Content-Type: application/json

{
  "url": "https://acme-corp.com",
  "tier": "full_test",
  "email": "you@example.com"
}
```

Tiers: `quick_scan` | `standard` | `full_test` | `deep_dive`

**Poll status:**
```
GET /api/runs/:id
```

**Get report:**
```
GET /api/runs/:id/report
```

**Get step-level failure detail:**
```
GET /api/runs/:id/scenarios/:scenarioId/steps
```

**Re-run a saved suite:**
```
POST /api/account/suites/:slug/run
X-Api-Key: ttx_...
Content-Type: application/json

{ "email": "you@example.com" }
```

Full reference: https://testorax.com/api-docs

## Common prompts

Use these verbatim with any MCP-connected agent:

- "Run a quick scan on https://acme-corp.com and show me the bug report"
- "Test my deployed app at https://acme-corp.com using full_test tier"
- "Re-run my saved suite called checkout-flow"
- "Why did scenario [ID] fail in run [ID]? Give me the full step-by-step diagnostic"
- "Create a Testorax run for https://acme-corp.com with these custom scenarios: [paste scenario JSON]"
- "Review this PR — run Testorax on https://staging.acme-corp.com and report any regressions"
- "List my recent runs and show me which ones had failures"
- "Retry only the failing scenarios from run [ID]"

**Note:** if Testorax needs login credentials or gets stuck on a flow, it will pause the run and send you a message. Check `list_messages` and reply with `send_message`. The run resumes automatically once you reply.

## Optional

- Scenario schema reference: https://testorax.com/docs/scenarios
- API reference: https://testorax.com/api-docs
- CLI reference: https://testorax.com/cli
- Integrations (Claude Code, Cursor, MCP): https://testorax.com/integrations
- Account and API key: https://testorax.com/account/api-key
- MCP package on npm: https://www.npmjs.com/package/testorax-mcp
- CLI package on npm: https://www.npmjs.com/package/testorax