greenrun-cli 0.1.5 → 0.2.0

package/dist/api-client.d.ts

@@ -12,14 +12,32 @@ export declare class ApiClient {
         name: string;
         base_url?: string;
         description?: string;
-        concurrency?: number;
+        auth_mode?: string;
+        login_url?: string;
+        register_url?: string;
+        login_instructions?: string;
+        register_instructions?: string;
+        credentials?: {
+            name: string;
+            email: string;
+            password: string;
+        }[];
     }): Promise<unknown>;
     getProject(id: string): Promise<unknown>;
     updateProject(id: string, data: {
         name?: string;
         base_url?: string;
         description?: string;
-        concurrency?: number;
+        auth_mode?: string;
+        login_url?: string;
+        register_url?: string;
+        login_instructions?: string;
+        register_instructions?: string;
+        credentials?: {
+            name: string;
+            email: string;
+            password: string;
+        }[];
     }): Promise<unknown>;
     deleteProject(id: string): Promise<unknown>;
     listPages(projectId: string): Promise<unknown>;
@@ -39,6 +57,7 @@ export declare class ApiClient {
         page_ids?: string[];
         status?: string;
         tags?: string[];
+        credential_name?: string;
     }): Promise<unknown>;
     getTest(id: string): Promise<unknown>;
     updateTest(id: string, data: {
@@ -47,6 +66,9 @@ export declare class ApiClient {
         page_ids?: string[];
         status?: string;
         tags?: string[];
+        credential_name?: string | null;
+        script?: string | null;
+        script_generated_at?: string | null;
     }): Promise<unknown>;
     deleteTest(id: string): Promise<unknown>;
     sweep(projectId: string, params: {
@@ -60,4 +82,28 @@ export declare class ApiClient {
     }): Promise<unknown>;
     getRun(runId: string): Promise<unknown>;
     listRuns(testId: string): Promise<unknown>;
+    prepareTestBatch(projectId: string, filter?: string, testIds?: string[]): Promise<{
+        project: {
+            id: any;
+            name: any;
+            base_url: any;
+            auth_mode: any;
+            login_url: any;
+            register_url: any;
+            login_instructions: any;
+            register_instructions: any;
+            credentials: any;
+        };
+        tests: {
+            test_id: any;
+            test_name: any;
+            run_id: any;
+            instructions: any;
+            credential_name: any;
+            pages: any;
+            tags: any;
+            script: any;
+            script_generated_at: any;
+        }[];
+    }>;
 }

package/dist/api-client.js

@@ -102,4 +102,70 @@ export class ApiClient {
     async listRuns(testId) {
         return this.request('GET', `/tests/${testId}/runs`);
     }
+    // Batch operations
+    async prepareTestBatch(projectId, filter, testIds) {
+        const [projectResult, testsResult] = await Promise.all([
+            this.getProject(projectId),
+            this.listTests(projectId),
+        ]);
+        const project = projectResult.project;
+        let tests = (testsResult.tests || []).filter((t) => t.status === 'active');
+        if (testIds && testIds.length > 0) {
+            const idSet = new Set(testIds);
+            tests = tests.filter((t) => idSet.has(t.id));
+        }
+        else if (filter) {
+            if (filter.startsWith('tag:')) {
+                const tag = filter.slice(4).toLowerCase();
+                tests = tests.filter((t) => (t.tags || []).some((tg) => (tg.name || tg).toLowerCase() === tag));
+            }
+            else if (filter.startsWith('/')) {
+                tests = tests.filter((t) => (t.pages || []).some((p) => (p.url || '').includes(filter)));
+            }
+            else {
+                const term = filter.toLowerCase();
+                tests = tests.filter((t) => (t.name || '').toLowerCase().includes(term));
+            }
+        }
+        if (tests.length === 0) {
+            return {
+                project: {
+                    id: project.id, name: project.name, base_url: project.base_url,
+                    auth_mode: project.auth_mode ?? 'none',
+                    login_url: project.login_url ?? null,
+                    register_url: project.register_url ?? null,
+                    login_instructions: project.login_instructions ?? null,
+                    register_instructions: project.register_instructions ?? null,
+                    credentials: project.credentials ?? null,
+                },
+                tests: [],
+            };
+        }
+        // Fetch full test details in parallel
+        const fullTests = await Promise.all(tests.map((t) => this.getTest(t.id)));
+        // Start runs in parallel
+        const runs = await Promise.all(tests.map((t) => this.startRun(t.id)));
+        return {
+            project: {
+                id: project.id, name: project.name, base_url: project.base_url,
+                auth_mode: project.auth_mode ?? 'none',
+                login_url: project.login_url ?? null,
+                register_url: project.register_url ?? null,
+                login_instructions: project.login_instructions ?? null,
+                register_instructions: project.register_instructions ?? null,
+                credentials: project.credentials ?? null,
+            },
+            tests: fullTests.map((ft, i) => ({
+                test_id: ft.test.id,
+                test_name: ft.test.name,
+                run_id: runs[i].run.id,
+                instructions: ft.test.instructions,
+                credential_name: ft.test.credential_name ?? null,
+                pages: ft.test.pages || [],
+                tags: ft.test.tags || [],
+                script: ft.test.script ?? null,
+                script_generated_at: ft.test.script_generated_at ?? null,
+            })),
+        };
+    }
 }

package/dist/commands/init.js

@@ -44,7 +44,7 @@ function checkPrerequisites() {
     catch {
         // not installed
     }
-    return { claude, chromeHint: true };
+    return { claude };
 }
 async function validateToken(token) {
     try {
@@ -74,6 +74,15 @@ function configureMcpLocal(token) {
         console.error(`  claude mcp add greenrun --transport stdio -e GREENRUN_API_TOKEN=${token} -- npx -y greenrun-cli@latest\n`);
     }
 }
+function configurePlaywrightMcp() {
+    try {
+        execSync('claude mcp add playwright -- npx @playwright/mcp@latest --browser chrome --user-data-dir ~/.greenrun/browser-profile', { stdio: 'inherit' });
+    }
+    catch {
+        console.error('\nFailed to add Playwright MCP. You can add it manually:\n');
+        console.error('  claude mcp add playwright -- npx @playwright/mcp@latest --browser chrome --user-data-dir ~/.greenrun/browser-profile\n');
+    }
+}
 function configureMcpProject(token) {
     const mcpConfig = {
         mcpServers: {
@@ -127,7 +136,9 @@ function installClaudeMd() {
     if (existsSync(claudeMdPath)) {
         const existing = readFileSync(claudeMdPath, 'utf-8');
         if (existing.includes('## Greenrun')) {
-            console.log('  CLAUDE.md already contains Greenrun section, skipping');
+            const updated = existing.replace(/## Greenrun[\s\S]*$/, snippet.trimEnd());
+            writeFileSync(claudeMdPath, updated.endsWith('\n') ? updated : updated + '\n');
+            console.log('  Replaced Greenrun section in CLAUDE.md');
             return;
         }
         appendFileSync(claudeMdPath, '\n' + snippet);
@@ -155,6 +166,7 @@ function installSettings() {
         'mcp__greenrun__list_projects',
         'mcp__greenrun__get_project',
         'mcp__greenrun__create_project',
+        'mcp__greenrun__update_project',
         'mcp__greenrun__list_pages',
         'mcp__greenrun__create_page',
         'mcp__greenrun__list_tests',
@@ -166,19 +178,34 @@ function installSettings() {
         'mcp__greenrun__get_run',
         'mcp__greenrun__list_runs',
         'mcp__greenrun__sweep',
+        'mcp__greenrun__prepare_test_batch',
     ];
     const browserTools = [
-        'mcp__claude-in-chrome__tabs_context_mcp',
-        'mcp__claude-in-chrome__tabs_create_mcp',
-        'mcp__claude-in-chrome__navigate',
-        'mcp__claude-in-chrome__computer',
-        'mcp__claude-in-chrome__read_page',
-        'mcp__claude-in-chrome__find',
-        'mcp__claude-in-chrome__form_input',
-        'mcp__claude-in-chrome__javascript_tool',
-        'mcp__claude-in-chrome__get_page_text',
-        'mcp__claude-in-chrome__read_console_messages',
-        'mcp__claude-in-chrome__read_network_requests',
+        'mcp__playwright__browser_navigate',
+        'mcp__playwright__browser_snapshot',
+        'mcp__playwright__browser_click',
+        'mcp__playwright__browser_type',
+        'mcp__playwright__browser_handle_dialog',
+        'mcp__playwright__browser_tab_list',
+        'mcp__playwright__browser_tab_new',
+        'mcp__playwright__browser_tab_select',
+        'mcp__playwright__browser_tab_close',
+        'mcp__playwright__browser_select_option',
+        'mcp__playwright__browser_hover',
+        'mcp__playwright__browser_drag',
+        'mcp__playwright__browser_press_key',
+        'mcp__playwright__browser_screenshot',
+        'mcp__playwright__browser_wait',
+        'mcp__playwright__browser_file_upload',
+        'mcp__playwright__browser_pdf_save',
+        'mcp__playwright__browser_close',
+        'mcp__playwright__browser_console_messages',
+        'mcp__playwright__browser_resize',
+        'mcp__playwright__browser_run_code',
+        'mcp__playwright__browser_evaluate',
+        'mcp__playwright__browser_fill_form',
+        'mcp__playwright__browser_tabs',
+        'mcp__playwright__browser_network_requests',
     ];
     const requiredTools = [...greenrunTools, ...browserTools];
     existing.permissions = existing.permissions || {};
@@ -191,7 +218,7 @@ function installSettings() {
 function installCommands() {
     const commandsDir = join(process.cwd(), '.claude', 'commands');
     mkdirSync(commandsDir, { recursive: true });
-    const commands = ['greenrun.md', 'greenrun-sweep.md'];
+    const commands = ['greenrun.md', 'greenrun-sweep.md', 'procedures.md'];
     for (const cmd of commands) {
         const src = join(TEMPLATES_DIR, 'commands', cmd);
         if (!existsSync(src)) {
@@ -228,8 +255,7 @@ export async function runInit(args) {
             process.exit(1);
         }
     }
-    console.log('  [i] Claude in Chrome extension required for browser test execution');
-    console.log('      Get it at: https://chromewebstore.google.com/detail/claude-in-chrome\n');
+    console.log('  [i] Playwright MCP will be configured for browser test execution\n');
     let token = opts.token;
     let scope = opts.scope;
     if (interactive) {
@@ -283,14 +309,15 @@ export async function runInit(args) {
         scope = scope || 'local';
     }
     // Configure MCP
-    console.log('Configuring MCP server...');
+    console.log('Configuring MCP servers...');
     if (scope === 'project') {
         configureMcpProject(token);
     }
     else {
         configureMcpLocal(token);
     }
-    console.log('  MCP server configured.\n');
+    configurePlaywrightMcp();
+    console.log('  MCP servers configured.\n');
     // Install extras
     if (opts.claudeMd) {
         installClaudeMd();
@@ -302,7 +329,7 @@ export async function runInit(args) {
     console.log(`
 Done! Restart Claude Code to connect.
 
-Make sure Chrome is open with the Claude in Chrome extension active
-before running /greenrun - Claude needs browser access to execute tests.
+Playwright will launch a Chrome browser automatically when running tests.
+Run /greenrun to execute your test suite.
 `);
 }

package/dist/server.js

@@ -26,7 +26,16 @@ export async function startServer() {
         name: z.string().describe('Project name'),
         base_url: z.string().optional().describe('Base URL of the site (e.g. https://myapp.com)'),
         description: z.string().optional().describe('Project description'),
-        concurrency: z.number().int().min(1).max(20).optional().describe('Number of tests to run in parallel (default: 5)'),
+        auth_mode: z.enum(['none', 'existing_user', 'new_user']).optional().describe('How to authenticate before tests (default: none)'),
+        login_url: z.string().optional().describe('URL of login page (for existing_user auth mode)'),
+        register_url: z.string().optional().describe('URL of registration page (for new_user auth mode)'),
+        login_instructions: z.string().optional().describe('Steps to log in with existing credentials'),
+        register_instructions: z.string().optional().describe('Steps to register a new user'),
+        credentials: z.array(z.object({
+            name: z.string().describe('Credential set name (e.g. "admin", "viewer")'),
+            email: z.string().describe('Login email'),
+            password: z.string().describe('Login password'),
+        })).optional().describe('Named credential sets for test authentication (max 20)'),
     }, async (args) => {
         const result = await api.createProject(args);
         return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
@@ -35,6 +44,26 @@ export async function startServer() {
         const result = await api.getProject(args.project_id);
         return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     });
+    server.tool('update_project', 'Update project settings', {
+        project_id: z.string().describe('Project UUID'),
+        name: z.string().optional().describe('Updated project name'),
+        base_url: z.string().optional().describe('Updated base URL'),
+        description: z.string().optional().describe('Updated description'),
+        auth_mode: z.enum(['none', 'existing_user', 'new_user']).optional().describe('How to authenticate before tests'),
+        login_url: z.string().optional().describe('URL of login page (for existing_user auth mode)'),
+        register_url: z.string().optional().describe('URL of registration page (for new_user auth mode)'),
+        login_instructions: z.string().optional().describe('Steps to log in with existing credentials'),
+        register_instructions: z.string().optional().describe('Steps to register a new user'),
+        credentials: z.array(z.object({
+            name: z.string().describe('Credential set name (e.g. "admin", "viewer")'),
+            email: z.string().describe('Login email'),
+            password: z.string().describe('Login password'),
+        })).optional().describe('Named credential sets for test authentication (max 20)'),
+    }, async (args) => {
+        const { project_id, ...data } = args;
+        const result = await api.updateProject(project_id, data);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
     // --- Pages ---
     server.tool('list_pages', 'List pages in a project', { project_id: z.string().describe('Project UUID') }, async (args) => {
         const result = await api.listPages(args.project_id);
@@ -64,6 +93,7 @@ export async function startServer() {
         page_ids: z.array(z.string()).optional().describe('UUIDs of pages this test covers'),
         status: z.enum(['draft', 'active', 'archived']).optional().describe('Test status (default: active)'),
         tags: z.array(z.string()).optional().describe('Tag names for organizing tests (e.g. ["smoke", "auth"])'),
+        credential_name: z.string().optional().describe('Name of a credential set from the project to use for authentication'),
     }, async (args) => {
         const result = await api.createTest(args.project_id, {
             name: args.name,
@@ -71,6 +101,7 @@ export async function startServer() {
             page_ids: args.page_ids,
             status: args.status,
             tags: args.tags,
+            credential_name: args.credential_name,
         });
         return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     });
@@ -81,6 +112,9 @@ export async function startServer() {
         page_ids: z.array(z.string()).optional().describe('Updated page UUIDs (replaces existing)'),
         status: z.enum(['draft', 'active', 'archived']).optional().describe('Updated status'),
         tags: z.array(z.string()).optional().describe('Updated tag names (replaces existing tags)'),
+        credential_name: z.string().optional().nullable().describe('Name of a credential set from the project to use for authentication'),
+        script: z.string().optional().nullable().describe('Generated Playwright test script'),
+        script_generated_at: z.string().optional().nullable().describe('ISO timestamp when the script was generated'),
     }, async (args) => {
         const { test_id, ...data } = args;
         const result = await api.updateTest(test_id, data);
@@ -98,6 +132,20 @@ export async function startServer() {
         });
         return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     });
+    // --- Batch ---
+    server.tool('prepare_test_batch', 'Prepare a batch of tests for execution: lists tests, filters, fetches full details, and starts runs — all in one call. Returns everything needed to execute tests.', {
+        project_id: z.string().describe('Project UUID'),
+        filter: z.string().optional().describe('Filter: "tag:xxx" for tag, "/path" for page URL, or text for name substring'),
+        test_ids: z.array(z.string()).optional().describe('Specific test UUIDs to run (overrides filter)'),
+    }, async (args) => {
+        try {
+            const result = await api.prepareTestBatch(args.project_id, args.filter, args.test_ids);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true };
+        }
+    });
     // --- Test Runs ---
     server.tool('start_run', 'Start a test run (sets status to running)', { test_id: z.string().describe('Test UUID') }, async (args) => {
         const result = await api.startRun(args.test_id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "greenrun-cli",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "CLI and MCP server for Greenrun - browser test management for Claude Code",
   "type": "module",
   "main": "dist/server.js",

package/templates/claude-md.md

@@ -2,34 +2,44 @@
 
 ### Prerequisites
 
-- **Claude in Chrome extension** must be installed and active in your browser for test execution
+- **Playwright MCP** must be configured for browser test execution (`claude mcp add playwright -- npx @playwright/mcp@latest --browser chrome --user-data-dir ~/.greenrun/browser-profile`)
 - MCP server must be connected (check with `/mcp` in Claude Code)
 
 ### Available MCP Tools
 
 The Greenrun MCP server provides these tools:
 
-- **list_projects** / **get_project** / **create_project** - Manage projects
+- **list_projects** / **get_project** / **create_project** - Manage projects (includes auth configuration)
 - **list_pages** / **create_page** - Manage page URLs within a project
 - **list_tests** / **get_test** / **create_test** / **update_test** - Manage test cases
 - **start_run** / **complete_run** / **get_run** / **list_runs** - Execute and track test runs
 - **sweep** - Impact analysis: find tests affected by changed pages
+- **prepare_test_batch** - Batch prepare tests for execution (lists, filters, fetches details, starts runs in one call)
 
 ### Running Tests
 
-To run tests for this project:
+Use the `/greenrun` slash command to run all tests automatically, or `/greenrun tag:smoke` to filter.
 
-1. Use `list_projects` to find the project, then `list_tests` to get all tests
-2. For each test, call `get_test` to retrieve the full instructions
-3. Call `start_run` to begin a run (returns a run ID)
-4. Execute the test instructions using browser automation (Claude in Chrome)
-5. Call `complete_run` with the run ID, status (passed/failed/error), and a result summary
+To run tests manually:
 
-Or use the `/greenrun` slash command to run all tests automatically.
+1. Use `list_projects` to find the project
+2. Call `prepare_test_batch` with the project ID (and optional filter) to get test details and run IDs
+3. Execute each test's instructions using Playwright browser automation tools (`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`)
+4. Call `complete_run` with the run ID, status (passed/failed/error), and a result summary
+
+### Auth Configuration
+
+Projects can be configured with authentication settings so tests auto-login before execution:
+
+- **`auth_mode: "none"`** - No authentication (default)
+- **`auth_mode: "existing_user"`** - Log in with existing credentials via `login_url` and `login_instructions`
+- **`auth_mode: "new_user"`** - Register a new account each run via `register_url` and `register_instructions`
+
+Projects can also store named **credentials** (name/email/password sets). Each test can reference a credential by `credential_name` to use specific login details during execution.
 
 ### Creating Tests
 
-1. Navigate to the page you want to test in Chrome
+1. Navigate to the page you want to test using Playwright
 2. Write clear, step-by-step test instructions describing what to do and what to verify
 3. Use `create_page` to register the page URL if not already registered
 4. Use `create_test` with the instructions and page IDs

package/templates/commands/greenrun-sweep.md

@@ -36,41 +36,7 @@ Present the affected tests:
 
 ### 6. Offer to run
 
-Ask the user if they want to run the affected tests. If yes, execute them **in parallel** using the same approach as the `/greenrun` command:
+Ask the user if they want to run the affected tests. If yes:
 
-Use the project's `concurrency` setting (default: 5) to determine batch size. Split affected tests into batches and launch each batch simultaneously using the **Task tool** with `run_in_background: true`.
-
-For each test in a batch, launch a background agent with `max_turns: 30` and `model: "sonnet"`. Use this prompt:
-
-```
-You are executing a single Greenrun browser test. You have access to browser automation tools and Greenrun MCP tools.
-
-**Test: {test_name}** (ID: {test_id})
-
-Step 1: Call `get_test` with test_id "{test_id}" to get full instructions.
-Step 2: Call `start_run` with test_id "{test_id}" to begin - save the returned `run_id`.
-Step 3: Execute the test instructions using browser automation:
-   - Call `tabs_context_mcp` then create a new browser tab for this test
-   - Follow each instruction step exactly as written
-   - The instructions will tell you where to navigate and what to do
-   - Only take a screenshot when you need to verify a visual assertion — not for every navigation or click
-   - When reading page content, prefer `find` or `read_page` with `filter: "interactive"` over full DOM reads
-   - NEVER trigger JavaScript alerts, confirms, or prompts — they block the browser extension entirely. Before clicking delete buttons or other destructive actions, use `javascript_tool` to override: `window.alert = () => {}; window.confirm = () => true; window.prompt = () => null;`
-   - If browser tools stop responding (no result or timeout), assume a dialog is blocking — report the error and stop. Do not keep retrying.
-   - If you get stuck or a step fails, record the failure and move on — do not retry more than once
-Step 4: Call `complete_run` with:
-   - run_id: the run ID from step 2
-   - status: "passed" if all checks succeeded, "failed" if any check failed, "error" if execution was blocked
-   - result: a brief summary of what happened (include the failure reason if failed/error)
-Step 5: Close the browser tab you created to clean up.
-
-Return a single line summary: {test_name} | {status} | {result_summary}
-```
-
-Wait for each batch to complete before launching the next. After all tests finish, present a summary table:
-
-| Test | Pages | Tags | Status | Result |
-|------|-------|------|--------|--------|
-| Test name | Affected page URLs | tag1, tag2 | passed/failed/error | Brief summary |
-
-Include the total count: "X passed, Y failed, Z errors out of N tests"
+1. Call `prepare_test_batch` with the project ID and `test_ids` set to the affected test IDs from the sweep results.
+2. Read `.claude/commands/procedures.md` and follow the Execute and Summarize procedures using the batch result.

package/templates/commands/greenrun.md

@@ -2,100 +2,25 @@ Run Greenrun browser tests for this project in parallel.
 
 ## Instructions
 
-You are executing browser tests managed by Greenrun. Tests run in parallel using background agents, each with its own browser tab. Follow these steps precisely:
+You are executing browser tests managed by Greenrun. Follow these steps precisely:
 
 ### 1. Find the project
 
 Call `list_projects` to get all projects. Match the current project by name or base URL. If no match is found, tell the user and stop.
 
-Note the project's `concurrency` value (default: 5). This controls how many tests run simultaneously.
+### 2. Prepare test batch
 
-### 2. Get tests
+Call `prepare_test_batch` with the project ID.
 
-Call `list_tests` with the project ID. Each test has associated pages and tags which are organizational metadata for filtering.
+If the user specified an argument ("$ARGUMENTS"), pass it as the `filter` parameter:
+- `tag:smoke` → filters by tag
+- `/checkout` → filters by page URL
+- `login` → filters by test name
 
-If the user specified an argument ("$ARGUMENTS"), use it to filter tests:
-- If it starts with `/` (e.g. `/checkout`), filter to tests linked to a page matching that URL
-- If it starts with `tag:` (e.g. `tag:smoke`), filter to tests with that tag
-- Otherwise, treat it as a test name filter
+If no argument is given, omit the filter to run all active tests.
 
-If no argument is given, run all active tests.
+If the result has zero tests, tell the user and stop.
 
-If there are no matching active tests, tell the user and stop.
+### 3. Execute tests
 
-### 3. Pre-fetch test details
-
-Call `get_test` for ALL matching tests **in parallel** (multiple tool calls in one message). This retrieves the full instructions for each test.
-
-Then call `start_run` for ALL tests **in parallel** to get run IDs.
-
-You now have everything needed to launch agents: test name, full instructions, and run_id for each test.
-
-### 4. Execute tests in parallel
-
-Split the test list into batches of size `concurrency` (from the project settings).
-
-For each batch, launch all tests simultaneously using the **Task tool** with `run_in_background: true`. Each background agent receives a prompt with the full instructions and run_id embedded — agents do NOT need to call `get_test` or `start_run`.
-
-```
-For each test in the current batch, call the Task tool with:
-- subagent_type: "general-purpose"
-- run_in_background: true
-- max_turns: 50
-- model: "sonnet"
-- prompt: (see below)
-```
-
-The prompt for each background agent should be:
-
-```
-You are executing a single Greenrun browser test using browser automation tools. Be efficient — minimize tool calls to complete the test as fast as possible.
-
-**Test: {test_name}**
-**Run ID: {run_id}**
-
-## Test Instructions
-
-{paste the full test instructions from get_test here}
-
-## Execution Steps
-
-1. Call `tabs_context_mcp` then create a new browser tab with `tabs_create_mcp`
-2. Follow each test instruction step exactly as written, using these rules to minimize tool calls:
-
-   **Speed rules (critical):**
-   - NEVER take screenshots. Use `read_page` or `find` for all assertions and to locate elements.
-   - Navigate directly to URLs (e.g. `navigate` to `/tokens`) instead of clicking through nav links
-   - Use `javascript_tool` for quick assertions: `document.querySelector('h1')?.textContent` is faster than `read_page` for checking a heading
-   - Use `read_page` with `filter: "interactive"` to verify multiple things in one call rather than separate `find` calls
-   - Use `form_input` with element refs for filling forms — avoid click-then-type sequences
-   - When clicking elements, use `ref` parameter instead of coordinates to avoid needing screenshots
-   - Combine verification: after a page loads, do ONE `read_page` call and check all assertions from that result
-
-   **Reliability rules:**
-   - NEVER trigger JavaScript alerts, confirms, or prompts — they block the browser extension entirely. Before clicking delete buttons or other destructive actions, use `javascript_tool` to override: `window.alert = () => {}; window.confirm = () => true; window.prompt = () => null;`
-   - If browser tools stop responding (no result or timeout), assume a dialog is blocking — report the error and stop. Do not keep retrying.
-   - If you get stuck or a step fails, record the failure and move on — do not retry more than once
-   - If you are redirected to a login page, try using an existing logged-in tab from `tabs_context_mcp` instead of creating a new one
-
-3. Call `complete_run` with:
-   - run_id: "{run_id}"
-   - status: "passed" if all checks succeeded, "failed" if any check failed, "error" if execution was blocked
-   - result: a brief summary of what happened (include the failure reason if failed/error)
-
-Return a single line summary: {test_name} | {status} | {result_summary}
-```
-
-After launching all agents in a batch, wait for them all to complete (use `TaskOutput` to collect results) before launching the next batch.
-
-### 5. Summarize results
-
-After all batches complete, collect results from all background agents and present a summary table:
-
-| Test | Pages | Tags | Status | Result |
-|------|-------|------|--------|--------|
-| Test name | /login, /dashboard | smoke, auth | passed/failed/error | Brief summary |
-
-Include the total count: "X passed, Y failed, Z errors out of N tests"
-
-If any tests failed, highlight what went wrong and suggest next steps.
+Read `.claude/commands/procedures.md` and follow the Execute and Summarize procedures using the batch result.

package/templates/commands/procedures.md

@@ -0,0 +1,335 @@
+Shared procedures for executing Greenrun browser tests. Referenced by `/greenrun` and `/greenrun-sweep`.
+
+## Authenticate
+
+Before executing tests, handle authentication based on the project's `auth_mode` from the batch result.
+
+- **`none`** (or missing): Skip authentication entirely.
+- **`existing_user`**: Navigate to the project's `login_url` and follow the `login_instructions` step by step. Use `browser_snapshot` after to verify the page shows an authenticated state (no login form visible).
+- **`new_user`**: Navigate to the project's `register_url` and follow the `register_instructions` step by step. Use `browser_snapshot` after to verify registration succeeded and the user is authenticated.
+
+### Credentials
+
+The project may include a `credentials` array — named credential sets with `name`, `email`, and `password`. Each test may have a `credential_name` field referencing one of these sets.
+
+When authenticating for a test with `credential_name`:
+- Find the matching credential in `project.credentials` by name
+- Use that credential's email and password to fill the login form at `login_url`
+- If no `credential_name` is set on a test, use the first credential in the array (or fall back to `login_instructions`)
+
+When authenticating once for a batch (Step 1 below), use the credential that appears most frequently across the batch's tests. If tests use different credentials, re-authenticate between tests as needed.
+
+If auth fails (login form still visible after following instructions), report all tests as error with "Authentication failed" and stop.
+
+## Execute
+
+You have a batch result from `prepare_test_batch` containing `project` (with `credentials` array) and `tests[]` (each with `test_id`, `test_name`, `run_id`, `instructions`, `credential_name`, `pages`, `tags`, `script`, `script_generated_at`).
+
+If `tests` is empty, tell the user no matching active tests were found and stop.
+
+### Step 1: Authenticate on the main page
+
+Run the Authenticate procedure above once, using the standard Playwright tools (`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`).
+
+### Step 2: Classify tests
+
+Split the batch into two groups:
+
+- **scripted**: tests where `script` is non-null (cached Playwright scripts ready to run)
+- **unscripted**: tests where `script` is null (need script generation)
+
+If all tests are scripted, skip to Step 4.
+
+### Step 3: Score and generate scripts (easy-first)
+
+For each **unscripted** test, assign a difficulty score based on the instructions:
+
+- **easy** (1): Single-page tests with simple actions — navigate, check text/headings, verify static content, click a link and check the URL. Typically 1-4 steps, no form submissions, no multi-step flows.
+- **medium** (2): Tests involving form input, button clicks that trigger state changes, checking error/success messages, or verifying a redirect after an action. Typically 3-8 steps.
+- **hard** (3): Multi-page flows, tests requiring specific sequences of actions (e.g. add to cart then checkout), tests with complex assertions (table data, dynamic content), or tests involving file uploads, modals, or dialogs.
+
+Sort unscripted tests by difficulty ascending (easy first). This ensures simple tests get scripts generated quickly so native execution can start sooner.
+
+#### Walk-through script generation
+
+For each unscripted test (in difficulty order), do a **scouting pass** — actually follow the test instructions in the browser to observe all UI states:
+
+1. Navigate to the test's starting page via `browser_navigate`
+2. Take a `browser_snapshot` to see initial elements
+3. Follow the test instructions step by step using Playwright MCP tools (`browser_click`, `browser_type`, `browser_snapshot` after each action)
+4. Snapshot after each state change to capture: validation errors, success banners, modal dialogs, redirected pages, dynamically loaded content
+5. Collect all observed elements and selectors as context
+
+Then generate a `.spec.ts` script using the observed elements:
+
+```ts
+import { test, expect } from '@playwright/test';
+test('{test_name}', async ({ page }) => {
+  // If the test has a credential_name, include login steps using the matching
+  // credential from project.credentials (email + password) at the login_url
+  await page.goto('{start_url}');
+  // Steps generated from scouting pass observations
+  // Use getByRole, getByText, getByLabel, getByPlaceholder for selectors
+});
+```
+
+Save via `update_test(test_id, { script: <generated_script>, script_generated_at: <ISO_now> })`.
+
+**Pipeline optimisation**: After finishing all **easy** tests, if there are medium/hard tests remaining, proceed to Step 4 immediately with whatever scripts are ready (scripted + newly generated easy tests). Continue generating medium/hard scripts in parallel by launching a background Task agent for the remaining generation work. When those scripts are ready, they'll be saved to the API for next run.
+
+To launch the background generation agent:
+
+```
+Task tool with:
+- subagent_type: "general-purpose"
+- run_in_background: true
+- max_turns: 50
+- model: "sonnet"
+- prompt: (include project details, remaining unscripted tests with instructions, and the scouting+generation procedure above)
+```
+
+The background agent should: for each remaining test, do the scouting pass, generate the script, and call `update_test` to save it. It does NOT need to call `complete_run` — that happens in the native execution step.
+
+### Step 4: Export auth state
+
+If `auth_mode` is not `none`, export the browser session so native Playwright inherits it:
+
+```js
+async (page) => {
+  const state = await page.context().storageState();
+  require('fs').writeFileSync('/tmp/greenrun-auth-state.json', JSON.stringify(state));
+  return 'Auth state exported';
+}
+```
+
+Call this via `browser_run_code`. If `auth_mode` is `none`, skip this step.
+
+### Step 5: Write files and run natively
+
+Gather all tests that have scripts (previously scripted + newly generated from Step 3).
+
+1. **Write test files**: For each scripted test, write the script to `/tmp/greenrun-tests/{test_id}.spec.ts`
+
+2. **Write config**: Write `/tmp/greenrun-tests/playwright.config.ts`:
+
+```ts
+import { defineConfig } from '@playwright/test';
+export default defineConfig({
+  testDir: '.',
+  timeout: 30000,
+  workers: 20,
+  reporter: [['json', { outputFile: 'results.json' }]],
+  use: {
+    baseURL: '{base_url}',
+    storageState: '/tmp/greenrun-auth-state.json',  // omit 'use.storageState' entirely if auth_mode is 'none'
+  },
+});
+```
+
+Replace `{base_url}` with the project's base_url.
+
+3. **Execute**: Run via Bash:
+```
+npx playwright test --config /tmp/greenrun-tests/playwright.config.ts
+```
+
+4. **Parse results**: Read `/tmp/greenrun-tests/results.json`. Map each result back to a run ID via the filename: `{test_id}.spec.ts` → test_id → find the matching run_id from the batch.
+
+5. **Report results**: Call `complete_run(run_id, status, result_summary)` for each test. Map Playwright statuses: `passed` → `passed`, `failed`/`timedOut` → `failed`, other → `error`.
+
+### Step 6: Handle unscripted tests without scripts
+
+Any tests that still don't have scripts (e.g. because the background agent hasn't finished, or script generation failed) need to be executed via AI agents using the legacy approach. Follow Step 7 for these tests.
+
+### Step 7: Circuit breaker
+
+After parsing all native results, walk through them in completion order. Track consecutive failures:
+
+- If **3 or more consecutive failures** occur:
+  - Mark all remaining un-reported tests as error: "Circuit breaker: N consecutive failures detected"
+  - Skip AI fallback for remaining tests
+  - The counter resets on any pass
+
+### Step 8: AI-agent fallback for native failures
+
+For tests that **failed** in native execution (and circuit breaker has not tripped):
+
+1. Start new runs via `start_run(test_id)` (the original runs were already completed in Step 5)
+2. Launch background Task agents using the tab-isolation pattern:
+
+Create tabs and launch agents in batches of 20:
+
+#### Create tab
+```js
+async (page) => {
+  const newPage = await page.context().newPage();
+  await newPage.goto(START_URL);
+  return { index: page.context().pages().length - 1, url: newPage.url() };
+}
+```
+
+#### Launch agent
+```
+Task tool with:
+- subagent_type: "general-purpose"
+- run_in_background: true
+- max_turns: 25
+- model: "sonnet"
+- prompt: (agent prompt below, including the native failure message for diagnosis)
+```
+
+#### Agent prompt
+
+```
+Greenrun browser test (AI fallback). Run ID: {run_id}
+Tab index: {INDEX}
+
+**{test_name}**
+
+{paste the full test instructions here}
+
+**Native execution failed with:** {failure_message}
+
+Determine if this is a stale script (UI changed) or an actual bug. If the script is stale, the test may still pass when executed manually.
+
+## CRITICAL: Tab isolation
+
+You are assigned to tab index {INDEX}. You MUST use ONLY `browser_run_code` for ALL browser interactions. Do NOT use `browser_snapshot`, `browser_click`, `browser_type`, `browser_navigate`, or any other Playwright MCP tools. The only non-browser tool you may call is `complete_run`.
+
+Every `browser_run_code` call must scope to your tab:
+```js
+async (page) => {
+  const p = page.context().pages()[INDEX];
+  // ... your action here ...
+}
+```
+
+## Auth
+No authentication needed — the main page already authenticated and cookies are shared to your tab.
+
+## Interaction patterns
+
+**Navigate:**
+```js
+async (page) => {
+  const p = page.context().pages()[INDEX];
+  await p.goto('https://example.com/path');
+  return p.url();
+}
+```
+
+**Read page state (replaces browser_snapshot):**
+```js
+async (page) => {
+  const p = page.context().pages()[INDEX];
+  const url = p.url();
+  const title = await p.title();
+  const text = await p.locator('body').innerText();
+  const headings = await p.getByRole('heading').allTextContents();
+  const buttons = await p.getByRole('button').allTextContents();
+  const links = await p.getByRole('link').allTextContents();
+  const textboxes = await p.getByRole('textbox').evaluateAll(els =>
+    els.map(e => ({ name: e.getAttribute('name') || e.getAttribute('aria-label') || e.placeholder, value: e.value }))
+  );
+  return { url, title, headings, buttons, links, textboxes, text: text.substring(0, 2000) };
+}
+```
+
+**Click an element:**
+```js
+async (page) => {
+  const p = page.context().pages()[INDEX];
+  await p.getByRole('button', { name: 'Submit' }).click();
+  return p.url();
+}
+```
+
+**Fill a form field:**
+```js
+async (page) => {
+  const p = page.context().pages()[INDEX];
+  await p.getByRole('textbox', { name: 'Email' }).fill('test@example.com');
+  return 'filled';
+}
+```
+
+**Handle a dialog:**
+```js
+async (page) => {
+  const p = page.context().pages()[INDEX];
+  p.once('dialog', d => d.accept());
+  await p.getByRole('button', { name: 'Delete' }).click();
+  return p.url();
+}
+```
+
+**Check for specific text (verification):**
+```js
+async (page) => {
+  const p = page.context().pages()[INDEX];
+  const visible = await p.getByText('Success').isVisible();
+  return { found: visible };
+}
+```
+
+## Rules
+- ONLY use `browser_run_code` — no other browser tools
+- Always scope to `page.context().pages()[INDEX]`
+- Use Playwright locators: `getByRole`, `getByText`, `getByLabel`, `getByPlaceholder`, `locator`
+- Read page state to find elements before interacting
+- Navigate with absolute URLs via `p.goto(url)` — never click nav links
+
+## FORBIDDEN — never use these:
+- `browser_snapshot`, `browser_click`, `browser_type`, `browser_navigate` — these operate on the MAIN page and will interfere with other tests
+- `browser_wait` — NEVER call this
+- `browser_screenshot` — NEVER use
+
+## Error recovery
+- On ANY failure: retry the failing step ONCE, then skip to Finish.
+
+## Finish (MANDATORY — always reach this step)
+1. If the test passes on manual execution, call `update_test(test_id, { script: null, script_generated_at: null })` to invalidate the stale cached script.
+2. `complete_run(run_id, status, brief_summary)` — ALWAYS call this, even on error.
+3. Return: {test_name} | {status} | {summary}
+```
+
+#### Wait and clean up
+
+Wait for all agents to complete via `TaskOutput`. Then close extra tabs (newest first):
+
+```js
+async (page) => {
+  const pages = page.context().pages();
+  for (let i = pages.length - 1; i >= 1; i--) {
+    await pages[i].close();
+  }
+  return { remainingPages: page.context().pages().length };
+}
+```
+
+Check for orphaned runs (agents that crashed without calling `complete_run`). For any orphaned run IDs, call `complete_run(run_id, "error", "Agent crashed or timed out")`.
+
+### Step 9: Wait for background generation
+
+If a background generation agent was launched in Step 3, check if it has completed via `TaskOutput` with `block: false`. If still running, note this in the summary. The generated scripts will be available on the next run.
+
+## Summarize
+
+Present a summary table with a Mode column showing how each test was executed:
+
+| Test | Pages | Tags | Mode | Status | Result |
+|------|-------|------|------|--------|--------|
+| Test name | /login, /dashboard | smoke, auth | native/agent/skipped | passed/failed/error | Brief summary |
+
+Mode values:
+- **native** — executed via `npx playwright test`
+- **agent** — executed via AI agent (fallback or no script available)
+- **skipped** — circuit breaker tripped, not executed
+
+Total: "X passed, Y failed, Z errors out of N tests"
+
+If the circuit breaker tripped, note: "Circuit breaker tripped after N consecutive failures. M tests skipped."
+
+If background script generation is still running, note: "Script generation in progress for N tests. Scripts will be cached for next run."
+
+If any tests failed, highlight what went wrong and suggest next steps.