greenrun-cli

Browser test management for Claude Code. Write tests in plain English, and Claude generates and runs Playwright scripts automatically.

Greenrun is an MCP server that connects Claude Code to the Greenrun API. You describe what to test, Greenrun handles the rest — script generation, parallel execution, result tracking, and re-running only what's needed.

Quick Start

npx greenrun-cli init

The setup wizard will:

1. Validate your Greenrun API token
2. Configure the Greenrun and Playwright MCP servers for Claude Code
3. Install /greenrun and /greenrun-sweep slash commands
4. Add project instructions to your CLAUDE.md
5. Set up tool permissions so tests run without prompts

Get an API token at app.greenrun.dev/tokens.

Prerequisites

• Node.js 18+
• Claude Code — install guide
• Playwright MCP — configured automatically by init

How It Works

1. Define tests in the dashboard or via Claude Code using MCP tools
2. Run /greenrun — Claude fetches tests, generates Playwright scripts on first run, then executes them natively
3. Scripts are cached — subsequent runs skip generation and execute instantly via npx playwright test
4. Results are tracked — pass/fail status, duration, and summaries stored per run

Script Generation

On first run, Claude walks through each test's instructions in the browser (scouting pass), observes UI states, and generates a .spec.ts script using real selectors. Scripts are saved to the API and reused on future runs.

If a cached script fails, an AI agent re-executes the test manually to determine whether the script is stale or there's a real bug. Stale scripts are automatically cleared for regeneration.

Authentication

Projects support named credential sets (name, email, password). Each test can reference a credential by name via credential_name. During execution, the matching credentials are used to authenticate before running the test.

Impact Analysis

After code changes, run /greenrun-sweep to find which tests are affected by the pages you changed. Only the relevant tests are re-run.

Slash Commands

/greenrun [filter]

Run tests for the current project. Supports filters:

• /greenrun — run all active tests
• /greenrun tag:smoke — run tests tagged "smoke"
• /greenrun /checkout — run tests linked to pages matching "/checkout"
• /greenrun login — run tests with "login" in the name

/greenrun-sweep

Detect which tests are impacted by recent git changes and offer to run them.

MCP Tools

| Tool | Description | |------|-------------| | list_projects | List all projects | | create_project | Create a project (with credentials, auth config) | | get_project | Get project details | | update_project | Update project settings | | list_pages | List pages in a project | | create_page | Register a page URL | | list_tests | List tests with latest run status | | get_test | Get full test details and instructions | | create_test | Create a test (with credential_name, tags, pages) | | update_test | Update test (auto-invalidates script on content change) | | prepare_test_batch | Fetch, filter, and start runs for a batch of tests | | export_test_script | Write a test's cached Playwright script to a local file (keeps scripts out of context) | | export_test_instructions | Write a test's instructions to a local file (keeps instructions out of context) | | sweep | Find tests affected by specific pages | | start_run | Start a test run | | complete_run | Record a single test result | | batch_complete_runs | Record results for multiple test runs in one call | | get_run | Get run details | | list_runs | List run history |

Manual Setup

If you prefer to configure manually instead of using init:

claude mcp add greenrun --transport stdio -e GREENRUN_API_TOKEN=your_token -- npx -y greenrun-cli@latest
claude mcp add playwright -- npx @playwright/mcp@latest --browser chrome --user-data-dir ~/.greenrun/browser-profile

Or add to your project's .mcp.json:

{
  "mcpServers": {
    "greenrun": {
      "command": "npx",
      "args": ["-y", "greenrun-cli@latest"],
      "env": { "GREENRUN_API_TOKEN": "${GREENRUN_API_TOKEN}" }
    }
  }
}

CLI Commands

greenrun init             Interactive setup wizard
greenrun update           Update templates and commands to latest version
greenrun serve            Start MCP server directly
greenrun --version        Print version
greenrun --help           Print help

Non-interactive init:

npx greenrun-cli init --token gr_xxx --scope local --no-claude-md --no-commands

License

MIT