Greenrun

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