il-e2e-agent 0.1.0

package/README.md

@@ -0,0 +1,333 @@
+# il-e2e-agent
+
+End-to-end browser tests written in plain English, executed by [tester-army/e2e](https://github.com/tester-army/e2e)
+and driven by the **Claude Code installed on your machine**, signed in with your own Claude account.
+No Anthropic API key is required.
+
+```ts
+import { test, expect } from 'il-e2e-agent';
+
+test('a visitor reaches checkout', async ({ app, agent, browser }) => {
+  await app.open('/pricing');
+  await agent.act('Choose the monthly plan and continue to checkout.'); // Claude operates the page
+  await expect(browser).toHaveURL(/\/checkout/);                         // deterministic check, no model
+});
+```
+
+## Contents
+
+- [How it works](#how-it-works)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Framework setup](#framework-setup): [Next.js](#nextjs) · [Nuxt](#nuxt) · [React (Vite)](#react-vite) · [Create React App](#create-react-app)
+- [Configuration](#configuration)
+- [Writing tests](#writing-tests)
+- [Running tests](#running-tests)
+- [Replay cache](#replay-cache)
+- [Keeping it out of production builds](#keeping-it-out-of-production-builds)
+- [Troubleshooting](#troubleshooting)
+- [Limitations](#limitations)
+
+## How it works
+
+`e2e` runs your tests in a real browser (Playwright). Steps written as `agent.act('…')` are handed to
+an agent; this package supplies that agent.
+
+For each agent step, il-e2e-agent starts your installed Claude Code and gives it a small set of tools:
+read the screen, tap, type, select, check, scroll, and run several of those in one batch. Claude reads
+the page as an accessibility listing, performs the step, and reports whether it succeeded. Every action
+goes through e2e's own action layer, so it is recorded.
+
+Once a step has passed and a later check has confirmed the result, e2e saves the recorded actions.
+**Later runs replay them directly, without calling Claude**, until the page changes enough that the
+replay no longer matches. Claude then takes over from the current screen and the new path is recorded.
+
+Each Claude Code session is isolated from your personal setup: no `CLAUDE.md`, hooks, built-in tools,
+personal MCP servers or connected apps are loaded, and no session history is written.
+
+## Requirements
+
+| Requirement | Notes |
+| --- | --- |
+| Claude Code, installed and signed in | `curl -fsSL https://claude.ai/install.sh \| bash`, then `claude auth login`. Found on `PATH` or in `~/.local/bin`; set `IL_E2E_CLAUDE_PATH` to use a different binary. |
+| Node.js 20.19 or later | |
+| Playwright's Chromium | Once per machine: `npx playwright install chromium` |
+| `ANTHROPIC_API_KEY` **not** set | If it is set, Claude Code may bill that key instead of your plan. The CLI prints a warning. |
+
+Agent steps count against **your own** Claude plan's usage limits.
+
+## Installation
+
+Install as a dev dependency of your app:
+
+```bash
+npm install --save-dev github:vishalmishraa22/il-e2e-agent
+npx playwright install chromium
+```
+
+Then create this layout in your project:
+
+```
+your-app/
+├── package.json                 add a "test:e2e" script (below)
+└── e2e/
+    ├── il-e2e-agent.config.ts   app URL and network policy
+    ├── tests/
+    │   └── *.e2e.ts             your tests
+    ├── support/                 optional shared helpers
+    └── .gitignore
+```
+
+`e2e/.gitignore`. Run output stays local; the replay cache is committed so teammates replay recorded steps:
+
+```gitignore
+.e2e/*
+!.e2e/cache/
+```
+
+`package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "test:e2e": "il-e2e-agent run --config e2e/il-e2e-agent.config.ts",
+    "test:e2e:fresh": "il-e2e-agent run --config e2e/il-e2e-agent.config.ts --no-cache"
+  }
+}
+```
+
+## Framework setup
+
+Tests run against your app's **dev server**. Pick a port for tests (3100 below) so a test run never
+collides with the dev server you already use, and start it before running the tests. Alternatively,
+let the runner start it with `app.command` (see [Configuration](#configuration)).
+
+### Next.js
+
+```json
+{ "scripts": { "dev:e2e": "next dev -p 3100" } }
+```
+
+`next build` type-checks every `.ts` file that `tsconfig.json` includes. Exclude the test folder so
+production builds never depend on test code:
+
+```jsonc
+// tsconfig.json
+{ "exclude": ["node_modules", "e2e"] }
+```
+
+### Nuxt
+
+```json
+{ "scripts": { "dev:e2e": "nuxt dev --port 3100" } }
+```
+
+Add the test folder to `.nuxtignore` so the dev server's file watcher skips it (test runs write files
+under `e2e/.e2e/`):
+
+```gitignore
+e2e/**
+```
+
+If CI runs `nuxi typecheck`, also exclude `e2e/` there through `typescript.tsConfig.exclude` in
+`nuxt.config.ts`.
+
+### React (Vite)
+
+```json
+{ "scripts": { "dev:e2e": "vite --port 3100 --strictPort" } }
+```
+
+No further changes are needed with the default Vite templates: `tsconfig.app.json` only includes
+`src/`, and Vite's watcher only reacts to files your app imports.
+
+### Create React App
+
+```json
+{ "scripts": { "dev:e2e": "PORT=3100 BROWSER=none react-scripts start" } }
+```
+
+### Server-side tracking
+
+The network policy below controls what the **test browser** can reach. Calls your **server** makes
+(for example a Next.js route handler or Nuxt server route forwarding to an analytics or CRM API)
+are outside its reach. If your app does this in development, turn it off in the `dev:e2e` script
+with your app's own environment flags, and block the forwarding routes with `blockPaths`.
+
+## Configuration
+
+`e2e/il-e2e-agent.config.ts`:
+
+```ts
+import { defineConfig } from 'il-e2e-agent';
+
+export default defineConfig({
+  app: { url: 'http://localhost:3100' },
+  timeout: 600_000,
+  actionTimeout: 8_000,
+  maxSteps: 40,
+  network: {
+    allow: ['*.stripe.com', '*.stripe.network', 'fonts.googleapis.com', 'fonts.gstatic.com'],
+    readOnly: ['api-staging.example.com'],
+    blockPaths: ['/api/analytics'],
+    log: Boolean(process.env.E2E_NETWORK_LOG),
+  },
+});
+```
+
+`defineConfig` accepts every [e2e config option](https://e2e.tester.army/docs/reference/config)
+except `targets` and `agents`, which it builds for you, plus:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `app` | required | `url` of the app under test. Optionally `command` to let the runner start it, e.g. `{ executable: 'npm', args: ['run', 'dev:e2e'], cwd: '..', reuseExisting: true }`. |
+| `model` | `'sonnet'` | Claude model for agent steps: `'sonnet'`, `'haiku'` or `'opus'`. |
+| `effort` | `'low'` | Reasoning effort per agent step. Higher values think longer on every turn. |
+| `maxSteps` | `25` | Actions a single `agent.act` may take. Raise it for long multi-screen steps. |
+| `browser` | e2e defaults | Playwright web-engine options, e.g. `{ viewport: { width: 1280, height: 900 } }`. |
+| `network` | localhost only | Which hosts the test browser may reach. `false` disables the guard. |
+
+### Network policy
+
+Every request the test browser makes is checked, and anything not explicitly allowed is aborted.
+Development builds often send real analytics, advertising and CRM events. The policy keeps test runs
+out of that data, and keeps tests from writing to shared backends.
+
+| Field | Effect |
+| --- | --- |
+| `allow` | Hosts reachable with any method. `*.example.com` matches the domain and its subdomains. `localhost` and `127.0.0.1` are always allowed. |
+| `readOnly` | Hosts reachable with `GET`, `HEAD` and `OPTIONS` only, e.g. a staging API your pages read from. |
+| `blockPaths` | Path prefixes aborted on every host, including your own app's routes. |
+| `log` | Prints each newly blocked host and path once. |
+
+To build the list for a new project, start with only localhost allowed and run with
+`E2E_NETWORK_LOG=1`. Each `[il-e2e-agent] blocked …` line names a host the page tried to reach:
+- **Leave blocked:** trackers, pixels, tag managers and CRMs.
+- **Add to `allow`:** what the page needs to work, such as payment widgets, fonts and image CDNs.
+- **Add to `readOnly`:** APIs it only reads from.
+
+## Writing tests
+
+Tests live in `e2e/tests/*.e2e.ts`:
+
+```ts
+import { test, expect } from 'il-e2e-agent';
+
+test('a returning visitor keeps their campaign parameters', async ({ app, agent, browser, screen }) => {
+  await app.open('/landing?utm_source=newsletter');
+
+  await agent.act('Start the sign-up flow using the main call-to-action.');
+  await expect(browser).toHaveURL(/utm_source=newsletter/);
+
+  await agent.act('Enter the email {email} and continue.', { params: { email: 'qa@example.com' } });
+  await expect(screen.getByText('Check your inbox', { exact: false })).toBeVisible();
+});
+```
+
+Guidelines:
+
+- **Follow every `agent.act` with an `expect`.** The check confirms the step did the right thing, and
+  only steps confirmed by a later check are recorded for replay.
+- **One goal per `agent.act`.** Short, specific instructions are faster, cheaper and more reliable than
+  one instruction covering a whole flow.
+- **Check with `expect` wherever possible.** `expect`, `screen.*` and `browser.*` never call a model.
+  `agent.assert`, `agent.waitFor` and `agent.extract` call Claude on every run, even when the steps
+  before them are replayed.
+- **Pass data as `params`** and reference it as `{name}` in the instruction. Wrap values that change on
+  every run (timestamps, generated emails) in `unique()`, or the step is never replayed.
+- **Prefer `exact: false` for copy checks** when text may come from a CMS or change case.
+- **Never instruct the agent to submit real payments** or other irreversible actions against shared
+  environments.
+
+`test`, `expect`, `unique`, `credentials` and `secrets` are re-exported from e2e. The full test API is
+documented at [e2e.tester.army/docs](https://e2e.tester.army/docs).
+
+## Running tests
+
+```bash
+npm run dev:e2e                                  # terminal 1: the app on the test port
+
+npm run test:e2e                                 # terminal 2: all tests
+npm run test:e2e -- e2e/tests/checkout.e2e.ts    # one file
+npm run test:e2e -- --headed                     # watch the browser
+npm run test:e2e -- --reporter list,markdown     # writes e2e/.e2e/summary.md and failure pages
+npm run test:e2e:fresh                           # ignore recordings and run every step live
+```
+
+Failure details, screenshots and traces are written to `e2e/.e2e/`. Start with
+`e2e/.e2e/failures/` when a test fails.
+
+The CLI sets `E2E_TELEMETRY_DISABLED=1` unless you set it yourself.
+
+## Replay cache
+
+- **First run of a step:** Claude performs it live, and the actions are recorded in `e2e/.e2e/cache/`.
+- **Later runs:** the recording is replayed with no model call.
+- **The page changes:** the replay hands over to Claude where it stopped matching, and the step is
+  recorded again.
+- **Changing a test's name, an instruction or its params** starts that step from scratch.
+
+**Commit `e2e/.e2e/cache/`** so everyone on the team replays the same recordings instead of running
+every step live on their own plan. Review cache changes in pull requests like any other test data.
+
+## Keeping it out of production builds
+
+This package is a development tool. Deployment and CI builds that install dev dependencies (for example
+because the framework's build tooling lives there) should skip it. Remove it from `package.json` in the
+build environment before installing:
+
+```bash
+npm pkg delete devDependencies.il-e2e-agent && npm install --include=dev
+```
+
+This changes the build's working copy only. Verified with both `npm install` and `npm ci` (npm 11).
+
+AWS Amplify (`amplify.yml`):
+
+```yaml
+preBuild:
+  commands:
+    - npm pkg delete devDependencies.il-e2e-agent
+    - npm install --include=dev
+```
+
+Vercel (`vercel.json`):
+
+```json
+{ "installCommand": "npm pkg delete devDependencies.il-e2e-agent && npm install" }
+```
+
+GitHub Actions:
+
+```yaml
+- run: npm pkg delete devDependencies.il-e2e-agent
+- run: npm ci
+```
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+| --- | --- |
+| `Claude Code was not found` | Install Claude Code and run `claude auth login`, or set `IL_E2E_CLAUDE_PATH`. |
+| `il-e2e-agent.config.ts not found` | Pass `--config e2e/il-e2e-agent.config.ts`, as the scripts above do, or run from the folder that holds it. |
+| `APP_UNREACHABLE` | The app isn't running on the configured URL. Start `npm run dev:e2e` first, or configure `app.command`. |
+| A page renders broken or incomplete | A resource it needs is blocked. Run with `E2E_NETWORK_LOG=1` and add the host to `network.allow`. |
+| A step takes long or exhausts its steps | Split the instruction into smaller `agent.act` calls, or raise `maxSteps`. |
+| A recorded step keeps re-running live | Its instruction, params or test name changed, or a value differs on every run. Use `unique()` for those. |
+| The dev server misbehaves while tests run | Exclude `e2e/` from its file watcher (`.nuxtignore` for Nuxt). |
+
+## Limitations
+
+- **Local use.** Agent steps run on the signed-in developer's own Claude plan, for their own use. Don't
+  share sign-ins or run them on shared or automated infrastructure. Replays of committed recordings need
+  no model.
+- **Text, not pixels.** The agent reads the page's accessibility tree. Layout and visual correctness
+  need separate visual testing.
+- **`agent.assert`, `waitFor` and `extract` always run live**, so they use your plan on every run.
+- **Pre-1.0 foundations.** e2e is still before 1.0, and this package pins exact versions of it.
+
+## Disclaimer
+
+il-e2e-agent is an independent project. It is not affiliated with, endorsed by or sponsored by
+Anthropic. Claude and Claude Code are trademarks of Anthropic, PBC. Your use of Claude Code is governed
+by Anthropic's terms for your plan.

package/bin/il-e2e-agent.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CONFIG_FILE = 'il-e2e-agent.config.ts';
+const CONFIG_COMMANDS = new Set(['run', 'cache', 'mcp', 'explore']);
+
+const argv = process.argv.slice(2);
+const command = argv[0] && !argv[0].startsWith('-') && !argv[0].includes('.') ? argv.shift() : 'run';
+
+if (process.env.ANTHROPIC_API_KEY) {
+  console.warn(
+    '[il-e2e-agent] ANTHROPIC_API_KEY is set, so Claude Code may bill that key instead of your Claude subscription. ' +
+      'Unset it to run on your own login.',
+  );
+}
+
+const args = [command, ...argv];
+if (CONFIG_COMMANDS.has(command) && !argv.includes('--config')) {
+  const config = resolve(CONFIG_FILE);
+  if (!existsSync(config)) {
+    console.error(`[il-e2e-agent] ${CONFIG_FILE} not found in ${process.cwd()}. Run il-e2e-agent from the folder that holds it.`);
+    process.exit(2);
+  }
+  args.push('--config', config);
+}
+
+const e2eCli = join(dirname(fileURLToPath(import.meta.resolve('e2e'))), 'cli/bin.js');
+const child = spawn(process.execPath, [e2eCli, ...args], {
+  stdio: 'inherit',
+  env: { E2E_TELEMETRY_DISABLED: '1', ...process.env },
+});
+child.on('exit', (code, signal) => (signal ? process.kill(process.pid, signal) : process.exit(code ?? 1)));

package/bin/prune-bundled-claude.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// postinstall: the Claude Agent SDK installs its own ~215 MB Claude Code binary as an optional
+// per-platform package. il-e2e-agent always runs the developer's installed Claude Code (it refuses to
+// start without one), so the bundled copy is never used and is deleted. npm cannot skip just that
+// one optional package (--omit=optional would also drop esbuild's platform binary, which e2e needs).
+import { existsSync, statSync, unlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+let sdkDir;
+try {
+  sdkDir = dirname(fileURLToPath(import.meta.resolve('@anthropic-ai/claude-agent-sdk')));
+} catch {
+  process.exit(0);
+}
+
+const platformPackage = `claude-agent-sdk-${process.platform}-${process.arch}`;
+const candidates = [
+  join(sdkDir, '..', platformPackage, 'claude'),
+  join(sdkDir, '..', `${platformPackage}-musl`, 'claude'),
+  join(sdkDir, 'node_modules', '@anthropic-ai', platformPackage, 'claude'),
+];
+
+for (const bundled of candidates.filter(existsSync)) {
+  const megabytes = Math.round(statSync(bundled).size / 1024 / 1024);
+  unlinkSync(bundled);
+  console.log(`[il-e2e-agent] Removed the Agent SDK's bundled Claude Code (${megabytes} MB); your installed one is used.`);
+}

package/dist/agent.d.ts

@@ -0,0 +1,19 @@
+import { type EffortLevel } from 'ai-sdk-provider-claude-code';
+import type { StepExecutor } from 'e2e';
+export interface ClaudeCodeAgentOptions {
+    /** Claude Code model alias or id: 'sonnet', 'haiku', 'opus'. */
+    readonly model?: string;
+    /** Claude Code turns allowed per agent step before it is reported as blocked. */
+    readonly maxTurns?: number;
+    /**
+     * Reasoning effort for agent steps. Defaults to 'low': driving a UI step by step needs little
+     * deliberation, and Claude Code's own default ('high') thinks on every turn, which is slow.
+     */
+    readonly effort?: EffortLevel;
+    /** Claude Code binary to run. Defaults to the one installed on this machine (see claude-binary.ts). */
+    readonly claudeExecutable?: string;
+}
+export declare function claudeCodeAgent(options?: ClaudeCodeAgentOptions): {
+    executor: StepExecutor;
+    model: import("@ai-sdk/provider").LanguageModelV4;
+};

package/dist/agent.js

@@ -0,0 +1,332 @@
+import { generateText } from 'ai';
+import { z } from 'zod';
+import { claudeCode, createAiSdkMcpServer, } from 'ai-sdk-provider-claude-code';
+import { isAgentError } from 'e2e/agent';
+import { requireInstalledClaude } from "./claude-binary.js";
+// The provider warns on every step that maxTurns above 20 is high; long steps are expected here.
+globalThis.AI_SDK_LOG_WARNINGS ??= false;
+const SERVER = 'e2e';
+const RUNTIME_STOPS = new Set(['STEP_BUDGET_EXHAUSTED', 'STEP_TIMEOUT', 'CANCELLED']);
+const FAILED_CODES = ['ASSERTION_FAILED', 'ASSERTION_INCONCLUSIVE', 'ACTION_FAILED', 'LOCATOR_NOT_FOUND'];
+const BLOCKED_CODES = [
+    'AUTOMATION_UNSUPPORTED',
+    'ENVIRONMENT_UNAVAILABLE',
+    'SEED_DATA_MISSING',
+    'TEST_SETUP_FAILED',
+    'AUTH_CREDENTIAL_INVALID',
+    'AUTH_CREDENTIAL_UNAVAILABLE',
+];
+// Above this share of changed lines a diff saves little, so the full listing is sent instead.
+const FULL_LISTING_RATIO = 0.6;
+// Runs Claude Code with nothing from ~/.claude (no CLAUDE.md, hooks, MCP servers or
+// built-in tools) and without writing sessions to disk; it signs in with the local login.
+// strictMcpConfig matters most: without it the user's own MCP servers and claude.ai
+// connectors attach after the first tool call and add ~40k input tokens to every turn.
+const ISOLATED = {
+    tools: [],
+    settingSources: [],
+    strictMcpConfig: true,
+    persistSession: false,
+    verbatimPrompts: true,
+    permissionPrompts: 'none',
+};
+const SYSTEM_PROMPT = `You are a QA agent testing a web app through tools. You see the app only as a listing with one element per line: "#id role "name" ...". Ids stay the same for as long as an element exists.
+
+Screen updates:
+- The step starts with the full listing.
+- Every action returns only what changed: lines that appeared ("+") and ids that disappeared ("-"). Everything else is unchanged and its ids still work.
+- When the path changes or most of the page changed, you get the full listing again. Call "observe" if you need it otherwise.
+
+Working efficiently:
+- Use "batch" to do several actions on one screen in a single call (fill every field, then click Continue). It stops at the first action that fails and tells you which.
+
+Rules:
+- Do exactly what the instruction asks, using only data the instruction or its params give. Never invent personal data.
+- Prefer the visible, labelled control a real user would use.
+- For an "assert" step, never change the app: only observe, then judge.
+- When the step is done, or cannot be done, call "complete_step" exactly once:
+  - passed: the screen shows the goal was reached (act) or the statement is true (assert).
+  - failed: the app did not behave as required, or the statement is false. Use ASSERTION_INCONCLUSIVE when the screen does not prove it either way.
+  - blocked: something outside the product stopped you (an environment error, a control your tools cannot operate).
+- Your summary is one sentence naming the evidence on screen.`;
+export function claudeCodeAgent(options = {}) {
+    const modelId = options.model ?? 'sonnet';
+    const base = {
+        ...ISOLATED,
+        pathToClaudeCodeExecutable: options.claudeExecutable ?? requireInstalledClaude(),
+    };
+    return {
+        executor: claudeCodeExecutor({
+            modelId,
+            maxTurns: options.maxTurns ?? 30,
+            base: { ...base, effort: options.effort ?? 'low' },
+        }),
+        // Judges agent.waitFor / agent.extract, which e2e runs through its own structured-output call.
+        model: claudeCode(modelId, base),
+    };
+}
+function claudeCodeExecutor(settings) {
+    return {
+        name: 'claude-code',
+        version: '2',
+        cache: 'inherit',
+        runStep: (ctx) => runStep(ctx, settings),
+    };
+}
+async function runStep(ctx, { modelId, maxTurns, base }) {
+    const controller = new AbortController();
+    const abort = () => controller.abort(ctx.signal.reason);
+    if (ctx.signal.aborted)
+        abort();
+    ctx.signal.addEventListener('abort', abort, { once: true });
+    const state = { transcript: [], screen: new ScreenTracker(), abort: () => controller.abort() };
+    const tools = buildTools(ctx, state);
+    const model = claudeCode(modelId, {
+        ...base,
+        systemPrompt: SYSTEM_PROMPT,
+        maxTurns,
+        mcpServers: { [SERVER]: createAiSdkMcpServer(SERVER, tools) },
+        allowedTools: Object.keys(tools).map((name) => `mcp__${SERVER}__${name}`),
+    });
+    const startedAt = new Date();
+    try {
+        const result = await generateText({
+            model,
+            prompt: await buildPrompt(ctx, state.screen),
+            abortSignal: controller.signal,
+        });
+        ctx.budgets.recordModelCall({
+            ...readUsage(result.usage),
+            startedAt: startedAt.toISOString(),
+            durationMs: Date.now() - startedAt.getTime(),
+            provider: 'claude-code',
+            modelId,
+        });
+    }
+    catch (error) {
+        if (state.hardStop)
+            throw state.hardStop;
+        if (state.verdict === undefined)
+            throw error;
+    }
+    finally {
+        ctx.signal.removeEventListener('abort', abort);
+        ctx.attachTranscript(state.transcript.join('\n'));
+    }
+    if (state.hardStop)
+        throw state.hardStop;
+    return (state.verdict ?? {
+        status: 'blocked',
+        errorCode: 'AUTOMATION_UNSUPPORTED',
+        summary: `Claude Code stopped without calling complete_step within ${maxTurns} turns.`,
+    });
+}
+/** Remembers the listing Claude last saw, so updates can carry only what changed. */
+class ScreenTracker {
+    lines = new Set();
+    path;
+    full(screen) {
+        this.remember(screen);
+        return render(screen);
+    }
+    changes(screen) {
+        const current = listingLines(screen);
+        const added = current.filter((line) => !this.lines.has(line));
+        const currentIds = new Set(current.map(idOf));
+        const removed = [...this.lines].map(idOf).filter((id) => id !== undefined && !currentIds.has(id));
+        const pathChanged = screen.path !== this.path;
+        if (pathChanged || screen.treeUnavailable || added.length > current.length * FULL_LISTING_RATIO) {
+            return `${pathChanged ? 'Navigated. ' : ''}Full screen:\n${this.full(screen)}`;
+        }
+        this.remember(screen);
+        if (added.length === 0 && removed.length === 0)
+            return 'No visible change.';
+        return [
+            added.length > 0 ? `+ appeared or changed:\n${added.join('\n')}` : undefined,
+            removed.length > 0 ? `- gone: ${removed.map((id) => `#${id}`).join(' ')}` : undefined,
+        ]
+            .filter((part) => part !== undefined)
+            .join('\n');
+    }
+    remember(screen) {
+        this.lines = new Set(listingLines(screen));
+        this.path = screen.path;
+    }
+}
+function listingLines(screen) {
+    return screen.text.split('\n').filter((line) => line.trim() !== '');
+}
+function idOf(line) {
+    return /#(\w+)/.exec(line)?.[1];
+}
+function render(screen) {
+    return [
+        screen.path === undefined ? undefined : `Path: ${screen.path}`,
+        screen.treeUnavailable ? 'The element list is unavailable right now; observe again.' : undefined,
+        screen.text,
+        screen.truncated ? '(listing truncated; scroll to see more)' : undefined,
+    ]
+        .filter((line) => line !== undefined)
+        .join('\n');
+}
+const BATCH_ACTION = z.object({
+    action: z.enum(['tap', 'type', 'select', 'check', 'press']),
+    id: z.string(),
+    text: z.string().optional().describe('type: the text to enter'),
+    value: z.string().optional().describe('select: the option label or value'),
+    checked: z.boolean().optional().describe('check: true or false'),
+    key: z.string().optional().describe('press: a key such as "Enter"'),
+});
+function buildTools(ctx, state) {
+    const can = (verb) => ctx.target.verbs.has(verb);
+    const node = z.string().describe('Element id from the screen listing, e.g. "n12"');
+    const target = (id) => ({ id: id.replace(/^#/, '') });
+    const define = (name, description, inputSchema, body) => ({
+        description,
+        inputSchema,
+        execute: async (args) => {
+            state.transcript.push(`→ ${name} ${JSON.stringify(args)}`);
+            try {
+                const output = await body(args);
+                state.transcript.push(`← ${output.split('\n', 1)[0]}`);
+                return output;
+            }
+            catch (error) {
+                if (isAgentError(error) && RUNTIME_STOPS.has(error.code)) {
+                    state.hardStop = error;
+                    state.abort();
+                }
+                state.transcript.push(`✗ ${error instanceof Error ? error.message : String(error)}`);
+                throw error;
+            }
+        },
+    });
+    const changes = async () => state.screen.changes(await ctx.observe());
+    const act = (name, description, inputSchema, body) => define(name, description, inputSchema, async (args) => {
+        await body(args);
+        return `Done.\n${await changes()}`;
+    });
+    const tools = {
+        observe: define('observe', 'Read the full current screen listing.', z.object({}), async () => state.screen.full(await ctx.observe())),
+        complete_step: define('complete_step', 'Finish the step with a verdict. Call exactly once, last.', z.object({
+            status: z.enum(['passed', 'failed', 'blocked']),
+            summary: z.string().describe('One sentence naming the evidence on screen'),
+            errorCode: z
+                .enum([...FAILED_CODES, ...BLOCKED_CODES])
+                .optional()
+                .describe('Required for blocked; optional for failed; omit for passed'),
+        }), async ({ status, summary, errorCode }) => {
+            state.verdict = toVerdict(status, summary, errorCode);
+            return 'Verdict recorded. Stop now.';
+        }),
+    };
+    if (ctx.step.kind === 'assert')
+        return tools;
+    const runOne = async (step) => {
+        const t = target(step.id);
+        switch (step.action) {
+            case 'tap':
+                return ctx.actions.tap(t);
+            case 'type':
+                return ctx.actions.type(t, step.text ?? '');
+            case 'select':
+                return ctx.actions.select(t, step.value ?? '');
+            case 'check':
+                return ctx.actions.check(t, step.checked ?? true);
+            case 'press':
+                return ctx.actions.press(t, step.key ?? 'Enter');
+        }
+    };
+    tools.batch = define('batch', 'Run several actions in order on the current screen (e.g. fill fields, then tap Continue). Stops at the first failure.', z.object({ actions: z.array(BATCH_ACTION).min(1).max(15) }), async ({ actions }) => {
+        for (const [index, step] of actions.entries()) {
+            if (!can(step.action))
+                throw new Error(`Action ${index + 1} (${step.action}) is not supported on this target.`);
+            try {
+                await runOne(step);
+            }
+            catch (error) {
+                if (isAgentError(error) && RUNTIME_STOPS.has(error.code))
+                    throw error;
+                const reason = error instanceof Error ? error.message : String(error);
+                return `Action ${index + 1} of ${actions.length} (${step.action} #${step.id}) failed: ${reason}\n${await changes()}`;
+            }
+        }
+        return `Done (${actions.length} actions).\n${await changes()}`;
+    });
+    if (can('tap')) {
+        tools.tap = act('tap', 'Click or tap one element.', z.object({ id: node }), ({ id }) => ctx.actions.tap(target(id)));
+    }
+    if (can('type')) {
+        tools.type = act('type', 'Fill a text field with a value.', z.object({ id: node, text: z.string() }), ({ id, text }) => ctx.actions.type(target(id), text));
+    }
+    if (can('typeSecret') && ctx.step.secrets.length > 0) {
+        tools.type_secret = act('type_secret', `Fill a field with a declared secret. Available: ${ctx.step.secrets.map((s) => `${s.name} (${s.purpose})`).join(', ')}.`, z.object({ id: node, name: z.string() }), ({ id, name }) => ctx.actions.typeSecret(target(id), name));
+    }
+    if (can('select')) {
+        tools.select = act('select', 'Choose an option in a select/dropdown by its visible label or value.', z.object({ id: node, value: z.string() }), ({ id, value }) => ctx.actions.select(target(id), value));
+    }
+    if (can('check')) {
+        tools.check = act('check', 'Set a checkbox, radio or switch to checked or unchecked.', z.object({ id: node, checked: z.boolean() }), ({ id, checked }) => ctx.actions.check(target(id), checked));
+    }
+    if (can('scroll')) {
+        tools.scroll = act('scroll', 'Scroll the page, or one scrollable element, by one screen.', z.object({ direction: z.enum(['up', 'down', 'left', 'right']), id: node.optional() }), ({ direction, id }) => ctx.actions.scroll(direction, id === undefined ? undefined : target(id)));
+    }
+    if (can('scrollUntil')) {
+        tools.scroll_until = act('scroll_until', 'Scroll until an element with this exact name or text is visible.', z.object({ text: z.string(), direction: z.enum(['up', 'down', 'left', 'right']) }), ({ text, direction }) => ctx.actions.scrollUntil(text, direction));
+    }
+    if (can('navigate')) {
+        tools.navigate = act('navigate', 'Go to an app-relative path or URL. Only when the instruction asks for it.', z.object({ url: z.string() }), ({ url }) => ctx.actions.navigate(url));
+    }
+    if (can('back')) {
+        tools.back = act('back', 'Go back one page.', z.object({}), () => ctx.actions.back());
+    }
+    return tools;
+}
+function toVerdict(status, summary, errorCode) {
+    if (status === 'passed')
+        return { status, summary };
+    if (status === 'blocked') {
+        const code = BLOCKED_CODES.includes(errorCode ?? '') ? errorCode : 'AUTOMATION_UNSUPPORTED';
+        return { status, summary, errorCode: code };
+    }
+    const code = FAILED_CODES.includes(errorCode ?? '') ? errorCode : undefined;
+    return code === undefined ? { status, summary } : { status, summary, errorCode: code };
+}
+async function buildPrompt(ctx, screen) {
+    const { step } = ctx;
+    return [
+        `Step kind: ${step.kind}`,
+        `Instruction: ${step.instruction}`,
+        step.params === undefined ? undefined : `Params: ${JSON.stringify(step.params)}`,
+        ctx.agentContext ? `Context: ${ctx.agentContext}` : undefined,
+        ctx.ledger ? `Earlier steps in this test:\n${ctx.ledger}` : undefined,
+        ctx.replayedPrefix === undefined
+            ? undefined
+            : `A recorded replay already did part of this step and stopped (${ctx.replayedPrefix.stopReason}). Do not repeat these actions:\n- ${ctx.replayedPrefix.replayedActions.join('\n- ')}` +
+                (ctx.replayedPrefix.uncertainAction
+                    ? `\nThis action may or may not have taken effect; check the screen before retrying it: ${ctx.replayedPrefix.uncertainAction}`
+                    : ''),
+        `Current screen:\n${screen.full(await ctx.observe())}`,
+    ]
+        .filter((part) => part !== undefined)
+        .join('\n\n');
+}
+function readUsage(usage) {
+    const count = (value) => {
+        if (typeof value === 'number')
+            return value;
+        if (value !== null && typeof value === 'object' && typeof value.total === 'number') {
+            return value.total;
+        }
+        return undefined;
+    };
+    const details = usage
+        ?.inputTokenDetails;
+    const fields = {
+        inputTokens: count(usage?.inputTokens),
+        outputTokens: count(usage?.outputTokens),
+        cacheReadTokens: details?.cacheReadTokens,
+        cacheWriteTokens: details?.cacheWriteTokens,
+    };
+    return Object.fromEntries(Object.entries(fields).filter(([, value]) => typeof value === 'number'));
+}

package/dist/claude-binary.d.ts

@@ -0,0 +1,4 @@
+export declare const CLAUDE_PATH_ENV = "IL_E2E_CLAUDE_PATH";
+/** The developer's installed Claude Code: env override, then PATH, then the installer's default locations. */
+export declare function findInstalledClaude(): string | undefined;
+export declare function requireInstalledClaude(): string;

package/dist/claude-binary.js

@@ -0,0 +1,32 @@
+import { accessSync, constants } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+export const CLAUDE_PATH_ENV = 'IL_E2E_CLAUDE_PATH';
+function executable(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The developer's installed Claude Code: env override, then PATH, then the installer's default locations. */
+export function findInstalledClaude() {
+    const override = process.env[CLAUDE_PATH_ENV];
+    if (override)
+        return executable(override) ? override : undefined;
+    const fromPath = (process.env.PATH ?? '')
+        .split(delimiter)
+        .filter(Boolean)
+        .map((dir) => join(dir, 'claude'));
+    const defaults = [join(homedir(), '.local', 'bin', 'claude'), join(homedir(), '.claude', 'local', 'claude')];
+    return [...fromPath, ...defaults].find(executable);
+}
+export function requireInstalledClaude() {
+    const found = findInstalledClaude();
+    if (found)
+        return found;
+    throw new Error('il-e2e-agent: Claude Code was not found. Install it (curl -fsSL https://claude.ai/install.sh | bash), ' +
+        `sign in with \`claude auth login\`, or point ${CLAUDE_PATH_ENV} at the binary.`);
+}

package/dist/config.d.ts

@@ -0,0 +1,25 @@
+import type { E2EConfig } from 'e2e';
+import { type WebOptions } from '@e2e-dev/web';
+import { type ClaudeCodeAgentOptions } from './agent.ts';
+import { type NetworkPolicy } from './network.ts';
+type TargetApp = NonNullable<E2EConfig['targets'][number]['app']>;
+export interface ClaudeE2EConfig extends Omit<E2EConfig, 'targets' | 'agents'> {
+    /** The app under test: its URL and, optionally, the command that starts it. */
+    readonly app: TargetApp;
+    /** Report label for the target; defaults to `web`. */
+    readonly name?: string;
+    /** Options for the Playwright web engine (viewport, browser, …). */
+    readonly browser?: WebOptions;
+    /** Claude Code model alias for agent steps: 'sonnet' (default), 'haiku' or 'opus'. */
+    readonly model?: string;
+    /** Reasoning effort for agent steps: 'low' (default), 'medium', 'high', … */
+    readonly effort?: ClaudeCodeAgentOptions['effort'];
+    /** Actions one `agent.act` may take; e2e's default is 25. */
+    readonly maxSteps?: number;
+    /** Hosts the test browser may reach; `false` turns the guard off. Default: localhost only. */
+    readonly network?: NetworkPolicy | false;
+    /** Extra named agents, passed through to e2e unchanged. */
+    readonly agents?: E2EConfig['agents'];
+}
+export declare function defineConfig(config: ClaudeE2EConfig): E2EConfig;
+export {};

package/dist/config.js

@@ -0,0 +1,16 @@
+import { web } from '@e2e-dev/web';
+import { claudeCodeAgent } from "./agent.js";
+import { registerNetworkPolicy } from "./network.js";
+export function defineConfig(config) {
+    const { app, name, browser, model, effort, maxSteps, network, agents, ...rest } = config;
+    registerNetworkPolicy(network ?? {});
+    return {
+        ...rest,
+        tests: rest.tests ?? ['e2e/**/*.e2e.ts', 'tests/**/*.e2e.ts'],
+        targets: [{ name: name ?? 'web', engine: web(browser), app }],
+        agents: {
+            default: { ...claudeCodeAgent({ model, effort }), ...(maxSteps === undefined ? {} : { maxSteps }) },
+            ...agents,
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { defineConfig, type ClaudeE2EConfig } from './config.ts';
+export { claudeCodeAgent, type ClaudeCodeAgentOptions } from './agent.ts';
+export { test } from './test.ts';
+export { decide, type NetworkPolicy } from './network.ts';
+export { expect, unique, credentials, secrets } from 'e2e';
+export type { Agent, Screen } from 'e2e';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { defineConfig } from "./config.js";
+export { claudeCodeAgent } from "./agent.js";
+export { test } from "./test.js";
+export { decide } from "./network.js";
+export { expect, unique, credentials, secrets } from 'e2e';

package/dist/network.d.ts

@@ -0,0 +1,19 @@
+import type { WebRoute } from '@e2e-dev/web';
+/**
+ * What the test browser may reach. Hosts accept a leading `*.` wildcard
+ * (`*.stripe.com` matches `js.stripe.com` and `stripe.com`). Everything not listed is aborted.
+ */
+export interface NetworkPolicy {
+    /** Hosts reachable with any method. `localhost` and `127.0.0.1` are always allowed. */
+    readonly allow?: readonly string[];
+    /** Hosts reachable with GET, HEAD and OPTIONS only (e.g. a staging API that must not be written to). */
+    readonly readOnly?: readonly string[];
+    /** Path prefixes aborted even on allowed hosts (e.g. the app's own `/api/facebook` proxy). */
+    readonly blockPaths?: readonly string[];
+    /** Print each newly blocked host/path once, to tune the policy. */
+    readonly log?: boolean;
+}
+/** Called by `defineConfig`; workers read it back through the environment. */
+export declare function registerNetworkPolicy(policy: NetworkPolicy | false): void;
+export declare function decide(policy: NetworkPolicy, url: string, method: string): 'continue' | 'abort';
+export declare function createRouteGuard(): ((route: WebRoute) => Promise<void>) | undefined;

package/dist/network.js

@@ -0,0 +1,52 @@
+const POLICY_ENV = 'IL_E2E_NETWORK_POLICY';
+const ALWAYS_ALLOWED = ['localhost', '127.0.0.1'];
+const READ_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+/** Called by `defineConfig`; workers read it back through the environment. */
+export function registerNetworkPolicy(policy) {
+    process.env[POLICY_ENV] = JSON.stringify(policy);
+}
+function currentPolicy() {
+    const raw = process.env[POLICY_ENV];
+    return raw === undefined ? {} : JSON.parse(raw);
+}
+function hostMatches(hostname, pattern) {
+    if (pattern.startsWith('*.')) {
+        const base = pattern.slice(2);
+        return hostname === base || hostname.endsWith(`.${base}`);
+    }
+    return hostname === pattern;
+}
+export function decide(policy, url, method) {
+    if (url.startsWith('data:') || url.startsWith('blob:'))
+        return 'continue';
+    const { hostname, pathname } = new URL(url);
+    if ((policy.blockPaths ?? []).some((prefix) => pathname.startsWith(prefix)))
+        return 'abort';
+    if ([...ALWAYS_ALLOWED, ...(policy.allow ?? [])].some((pattern) => hostMatches(hostname, pattern))) {
+        return 'continue';
+    }
+    if ((policy.readOnly ?? []).some((pattern) => hostMatches(hostname, pattern))) {
+        return READ_METHODS.has(method) ? 'continue' : 'abort';
+    }
+    return 'abort';
+}
+const reported = new Set();
+export function createRouteGuard() {
+    const policy = currentPolicy();
+    if (policy === false)
+        return undefined;
+    return async (route) => {
+        const { url, method } = route.request;
+        if (decide(policy, url, method) === 'continue')
+            return route.continue();
+        if (policy.log) {
+            const { hostname, pathname } = new URL(url);
+            const key = `${method} ${hostname}${pathname.split('/').slice(0, 3).join('/')}`;
+            if (!reported.has(key)) {
+                reported.add(key);
+                console.warn(`[il-e2e-agent] blocked ${key}`);
+            }
+        }
+        return route.abort();
+    };
+}

package/dist/test.d.ts

@@ -0,0 +1,7 @@
+import type { Browser } from '@e2e-dev/web';
+/** e2e's `test`, with the config's network policy applied before every test body. */
+export declare const test: import("e2e").TestAPI<import("e2e").TestFixtures & {
+    browser: Browser;
+} & {
+    networkPolicy: void;
+}>;

package/dist/test.js

@@ -0,0 +1,11 @@
+import { test as base } from 'e2e';
+import { createRouteGuard } from "./network.js";
+/** e2e's `test`, with the config's network policy applied before every test body. */
+export const test = base.extend().extend({
+    networkPolicy: async ({ browser }, use) => {
+        const guard = createRouteGuard();
+        if (guard)
+            await browser.route('**/*', guard);
+        await use();
+    },
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "il-e2e-agent",
+  "version": "0.1.0",
+  "description": "Natural-language browser tests (tester-army/e2e) run by the Claude Code installed on each developer's machine, on their own login",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vishalmishraa22/il-e2e-agent.git"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "il-e2e-agent": "./bin/il-e2e-agent.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "tsc -p tsconfig.json",
+    "postinstall": "node bin/prune-bundled-claude.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "dependencies": {
+    "@e2e-dev/web": "0.11.2",
+    "ai": "7.0.127",
+    "ai-sdk-provider-claude-code": "4.3.3",
+    "e2e": "0.16.0",
+    "playwright": "1.63.0",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}