playwright-e2e-mcp 0.6.0 → 0.7.0

package/dist/tools/save-login.js

@@ -0,0 +1,264 @@
+/**
+ * Tool — save-login: log in once and save the session as a Playwright
+ * storageState file that tests and the page tools reuse. Before logging in
+ * again it checks whether the saved session still works, so expired logins
+ * refresh themselves and valid ones are left alone.
+ *
+ * Passwords and one-time codes never pass through the chat: fill values
+ * may say {{env:E2E_PASSWORD}} (read from the server's environment) and
+ * {{totp}} (an authenticator code generated from a secret in an
+ * environment variable at the moment it is typed).
+ */
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { PlaywrightMcpError } from '../types/index.js';
+import { relativeToRoot, sanitizeUserPath, toNativePath, writeFileInsideRoot } from '../utils/path-utils.js';
+import { parseLocator } from '../utils/locator-expr.js';
+import { parseTotpSecret } from '../utils/totp.js';
+import { assertUrlAllowed } from '../utils/url-policy.js';
+import { assertHttpUrl, guard, pageActionSchema, resolvePageState, resolveProjectRoot, runBrowserScript, toolError, toolText, } from './shared.js';
+const saveLoginInput = z.object({
+    url: z.string().describe('Login page URL (http/https)'),
+    actions: z
+        .array(pageActionSchema)
+        .max(20)
+        .optional()
+        .describe("Login steps. In fill values write {{env:E2E_PASSWORD}} for a secret from the environment and {{totp}} for an authenticator code, never the secret itself. End with a 'wait' on something only signed-in users see"),
+    verify: z
+        .object({
+        url: z.string().optional().describe('Page to open to check the session, e.g. /account (default: where login ends)'),
+        visible: z.string().optional().describe("Locator only a signed-in user sees, e.g. getByRole('button', { name: 'Sign out' })"),
+        notUrl: z.string().optional().describe("The session is bad if the page lands on a URL containing this, e.g. '/login'"),
+    })
+        .optional()
+        .describe('How to tell the session works; also used to decide whether a saved session is still valid'),
+    name: z
+        .string()
+        .regex(/^[\w.-]{1,40}$/)
+        .optional()
+        .describe("Session name, e.g. 'admin' (default 'user'); saved to playwright/.auth/<name>.json"),
+    path: z.string().optional().describe('Where to save the storageState JSON inside the project (overrides name)'),
+    totpSecretEnv: z
+        .string()
+        .optional()
+        .describe('Environment variable holding the authenticator secret (base32 or otpauth:// URI), for {{totp}}'),
+    reuse: z.boolean().optional().describe('Keep a saved session that still passes verify instead of logging in again (default true)'),
+    headers: z.record(z.string(), z.string()).optional().describe('Extra HTTP headers'),
+    viewport: z.object({ width: z.number().int().min(200).max(4_000), height: z.number().int().min(200).max(4_000) }).optional(),
+    actionTimeoutMs: z.number().int().min(1_000).max(120_000).optional().describe('How long each step waits for its element (default 10000)'),
+    projectRoot: z.string().optional().describe('Project directory (default: server root)'),
+    timeoutMs: z.number().int().min(5_000).max(300_000).optional().describe('Overall limit in ms (default 60000)'),
+});
+export const saveLoginSchema = saveLoginInput;
+const ENV_TOKEN_RE = /\{\{\s*env:([A-Za-z0-9_]+)\s*\}\}/g;
+const TOTP_TOKEN_RE = /\{\{\s*totp\s*\}\}/;
+/**
+ * Environment variables a login may read. A page the agent visits could
+ * ask it to type {{env:AWS_SECRET_ACCESS_KEY}} into a form, so only names
+ * that are plainly test logins are allowed, plus any the user lists.
+ */
+export function loginEnvAllowed(name) {
+    if (/^(E2E|TEST|PW|PLAYWRIGHT|LOGIN)_[A-Z0-9_]+$/.test(name) && name !== 'PW_MCP_HTTP_TOKEN')
+        return true;
+    const extra = (process.env.PW_MCP_LOGIN_ENV ?? '')
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    return extra.includes(name);
+}
+/** The environment values the fill steps ask for, checked and read. */
+export function resolveLoginValues(actions) {
+    const names = new Set();
+    for (const action of actions ?? []) {
+        if (action.type !== 'fill' || !action.value)
+            continue;
+        for (const match of action.value.matchAll(ENV_TOKEN_RE))
+            names.add(match[1]);
+    }
+    const values = {};
+    const missing = [];
+    for (const name of names) {
+        if (!loginEnvAllowed(name)) {
+            throw new PlaywrightMcpError(`{{env:${name}}} is not an allowed login variable`, 'INVALID_INPUT', {
+                hint: 'Name login secrets E2E_*, TEST_*, PW_*, PLAYWRIGHT_* or LOGIN_* (e.g. E2E_PASSWORD), or list the name in PW_MCP_LOGIN_ENV.',
+            });
+        }
+        const value = process.env[name];
+        if (value === undefined || value === '')
+            missing.push(name);
+        else
+            values[name] = value;
+    }
+    if (missing.length > 0) {
+        throw new PlaywrightMcpError(`Not set in the server's environment: ${missing.join(', ')}`, 'INVALID_INPUT', {
+            hint: 'Set them where the MCP server starts (the env block of your MCP client config, or the shell), then restart the server.',
+        });
+    }
+    return values;
+}
+/** A literal typed into a password field: worth moving into an env variable. */
+function literalPasswordStep(actions) {
+    return (actions ?? []).some((a) => a.type === 'fill' && /pass(word|code)?|pin\b/i.test(a.locator ?? '') && !!a.value && !a.value.includes('{{'));
+}
+function expiryText(scan) {
+    if (scan.firstExpiry === null)
+        return scan.cookies > 0 ? 'session cookies only (they end when the browser closes)' : 'no cookies';
+    const seconds = scan.firstExpiry - Date.now() / 1000;
+    const when = new Date(scan.firstExpiry * 1000).toISOString().replace('T', ' ').slice(0, 16) + ' UTC';
+    if (seconds <= 0)
+        return `a cookie already expired (${when})`;
+    const hours = seconds / 3600;
+    const span = hours < 48 ? `${Math.max(1, Math.round(hours))} h` : `${Math.round(hours / 24)} days`;
+    return `first cookie expires in ${span} (${when})`;
+}
+/** Is the session file covered by .gitignore? A rough check that catches the common miss. */
+async function ignoredByGit(root, relative) {
+    const text = await readFile(toNativePath(path.posix.join(root, '.gitignore')), 'utf8').catch(() => '');
+    const lines = text.split(/\r?\n/).map((line) => line.trim().replace(/^\//, '').replace(/\/$/, ''));
+    const parts = relative.split('/');
+    for (let i = 1; i <= parts.length; i += 1) {
+        const prefix = parts.slice(0, i).join('/');
+        if (lines.includes(prefix) || lines.includes(`${prefix}/*`) || lines.includes(`${prefix}/**`))
+            return true;
+    }
+    return lines.some((line) => line === '*.auth.json' || line === '.auth' || (line.endsWith('.json') && relative.endsWith(line)));
+}
+function scanLines(scan) {
+    return [
+        `**Session:** ${scan.cookies} cookie${scan.cookies === 1 ? '' : 's'}, ${scan.origins} origin${scan.origins === 1 ? '' : 's'} with local storage · ${expiryText(scan)}`,
+    ];
+}
+export const saveLoginTool = {
+    name: 'save-login',
+    description: "Log in once and save the session as a storageState file (default playwright/.auth/<name>.json) for tests and the page tools. If a saved session still passes verify it is reused; expired ones log in again. Secrets stay out of chat: fill values use {{env:E2E_PASSWORD}} and {{totp}} (authenticator code from totpSecretEnv).",
+    inputSchema: saveLoginSchema,
+    handler: async (args, ctx) => guard('save-login', async () => {
+        if (ctx.restricted) {
+            throw new PlaywrightMcpError('save-login is not available on this server', 'INVALID_PATH', {
+                hint: 'It writes a session file into the project. Run the server locally.',
+            });
+        }
+        const url = assertHttpUrl(args.url);
+        await assertUrlAllowed(url);
+        const root = await resolveProjectRoot(args.projectRoot, ctx);
+        const timeoutMs = args.timeoutMs ?? 60_000;
+        const relativeTarget = args.path?.trim() || `playwright/.auth/${args.name ?? 'user'}.json`;
+        const target = sanitizeUserPath(relativeTarget, root);
+        if (!target.endsWith('.json')) {
+            throw new PlaywrightMcpError(`path must end in .json: ${relativeTarget}`, 'INVALID_PATH');
+        }
+        const shown = relativeToRoot(root, target);
+        let verifyUrl;
+        if (args.verify?.url) {
+            verifyUrl = new URL(args.verify.url, url).toString();
+            assertHttpUrl(verifyUrl);
+            await assertUrlAllowed(verifyUrl);
+        }
+        const visible = args.verify?.visible ? parseLocator(args.verify.visible) : undefined;
+        const loginVerify = args.verify ? { url: verifyUrl, visible, notUrl: args.verify.notUrl } : undefined;
+        const hasCheck = !!(visible || args.verify?.notUrl);
+        // A fresh login never starts from a session (PW_MCP_STORAGE_STATE included).
+        const { storageState: _default, ...base } = await resolvePageState({ headers: args.headers, viewport: args.viewport, actionTimeoutMs: args.actionTimeoutMs, actions: args.actions }, root, url, ctx);
+        const common = (state) => ({
+            ...state,
+            projectRoot: root,
+            loginVerify,
+            gotoTimeout: Math.min(30_000, Math.max(5_000, timeoutMs - 5_000)),
+            waitTimeout: 10_000,
+            startedAt: Date.now(),
+        });
+        // 1. A saved session that still works is kept.
+        const existing = await stat(toNativePath(target)).catch(() => null);
+        if (existing?.isFile() && args.reuse !== false && hasCheck) {
+            const check = await runBrowserScript({
+                ...common({ headers: base.headers, viewport: base.viewport }),
+                loginVerify: { ...loginVerify, url: undefined },
+                mode: 'login',
+                url: verifyUrl ?? url,
+                storageState: toNativePath(target),
+                loginCheckOnly: true,
+            }, { timeoutMs, signal: ctx.signal });
+            const scan = check.ok ? check.data?.login : undefined;
+            if (scan?.verified === true) {
+                return toolText([
+                    `## ✅ STILL VALID — \`${shown}\``,
+                    '',
+                    `The saved session passed the check at ${verifyUrl ?? url}, so no new login was needed.`,
+                    '',
+                    ...scanLines(scan),
+                    '',
+                    `Use it with \`storageState: '${shown}'\` in the page tools, or \`use: { storageState: '${shown}' }\` in playwright.config.`,
+                ].join('\n'), { status: 'valid', valid: true, path: shown, url: verifyUrl ?? url, ...(scan.firstExpiry ? { expiresAt: new Date(scan.firstExpiry * 1000).toISOString() } : {}) });
+            }
+        }
+        if (!args.actions?.length) {
+            throw new PlaywrightMcpError('Pass the login steps in actions', 'INVALID_INPUT', {
+                hint: existing?.isFile()
+                    ? `The saved session \`${shown}\` ${hasCheck ? 'failed the check' : 'cannot be checked without verify.visible or verify.notUrl'}, so a new login is needed.`
+                    : "E.g. fill getByLabel('Email') with {{env:E2E_USER}}, fill getByLabel('Password') with {{env:E2E_PASSWORD}}, click getByRole('button', { name: 'Sign in' }).",
+            });
+        }
+        // 2. Log in, check, save.
+        const env = {};
+        const values = resolveLoginValues(args.actions);
+        if (Object.keys(values).length > 0)
+            env.PW_MCP_FILL_VALUES = JSON.stringify(values);
+        const wantsTotp = args.actions.some((a) => a.type === 'fill' && TOTP_TOKEN_RE.test(a.value ?? ''));
+        if (wantsTotp) {
+            const name = args.totpSecretEnv;
+            if (!name)
+                throw new PlaywrightMcpError('{{totp}} needs totpSecretEnv', 'INVALID_INPUT', { hint: 'Name the environment variable that holds the authenticator secret, e.g. E2E_TOTP_SECRET.' });
+            if (!loginEnvAllowed(name)) {
+                throw new PlaywrightMcpError(`${name} is not an allowed login variable`, 'INVALID_INPUT', {
+                    hint: 'Name it E2E_*, TEST_*, PW_*, PLAYWRIGHT_* or LOGIN_* (e.g. E2E_TOTP_SECRET), or list it in PW_MCP_LOGIN_ENV.',
+                });
+            }
+            const secret = process.env[name];
+            if (!secret)
+                throw new PlaywrightMcpError(`${name} is not set in the server's environment`, 'INVALID_INPUT');
+            const totp = parseTotpSecret(secret);
+            env.PW_MCP_TOTP = JSON.stringify({ key: totp.key.toString('hex'), digits: totp.digits, period: totp.period, algorithm: totp.algorithm });
+        }
+        const outcome = await runBrowserScript({ ...common(base), mode: 'login', url }, { timeoutMs, signal: ctx.signal, env });
+        if (!outcome.ok) {
+            const done = outcome.actionsDone?.length ? `\nSteps done: ${outcome.actionsDone.join(' → ')}` : '';
+            return toolError(outcome.kind ?? 'UNKNOWN', `Login on ${url} failed: ${outcome.error ?? 'unknown error'}${done}`, outcome.hint, outcome.stderrTail);
+        }
+        const scan = outcome.data?.login;
+        if (!scan)
+            return toolError('UNKNOWN', 'The browser returned no session.', undefined, outcome.stderrTail);
+        if (scan.verified === false) {
+            return toolText([
+                `## ❌ LOGIN FAILED — nothing saved`,
+                '',
+                `The steps ran, but the check failed: ${scan.verifyNote || 'the session did not work'}. Ended on ${outcome.data?.finalUrl ?? url}.`,
+                '',
+                '**How to fix:** check the credentials in the environment, add a `wait` step for the page after sign-in, or run **inspect-page** with the same actions to see where the login stops (an MFA prompt, a consent screen, an error message).',
+            ].join('\n'), { ok: false, status: 'failed', valid: false, path: shown, url });
+        }
+        await writeFileInsideRoot(target, `${JSON.stringify(scan.state, null, 2)}\n`, root);
+        const lines = [`## ✅ SAVED — \`${shown}\``, ''];
+        lines.push(scan.verified === true
+            ? `Logged in and checked: the session works${verifyUrl ? ` on ${verifyUrl}` : ''}.`
+            : 'Logged in. No check was given, so the session was saved without one; add `verify` so expired sessions are caught next time.', '', ...scanLines(scan));
+        if (scan.cookies === 0 && scan.origins === 0) {
+            lines.push('', '> ⚠️ The session is empty: no cookies or local storage were set. The login may not have finished; end the steps with a `wait` on the signed-in page.');
+        }
+        if (literalPasswordStep(args.actions)) {
+            lines.push('', '> 🔐 A password was typed as plain text, so it is now in this chat. Put it in an environment variable (E2E_PASSWORD) and write `{{env:E2E_PASSWORD}}` instead.');
+        }
+        if (!(await ignoredByGit(root, shown))) {
+            lines.push('', `> ⚠️ \`${shown}\` holds live session cookies and is not in .gitignore. Add \`${path.posix.dirname(shown)}/\` to .gitignore so it is never committed.`);
+        }
+        lines.push('', `**Use it:** \`storageState: '${shown}'\` in inspect-page, validate-selector and the audits, or \`use: { storageState: '${shown}' }\` in playwright.config. Call save-login again before a run: it keeps the session while it works and logs in again when it expires.`);
+        return toolText(lines.join('\n'), {
+            status: 'saved',
+            valid: true,
+            path: shown,
+            url,
+            ...(scan.firstExpiry ? { expiresAt: new Date(scan.firstExpiry * 1000).toISOString() } : {}),
+        });
+    }),
+};
+//# sourceMappingURL=save-login.js.map

package/dist/tools/save-login.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"save-login.js","sourceRoot":"","sources":["../../src/tools/save-login.ts"],"names":[],"mappings":"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"}

package/dist/tools/shared.d.ts

@@ -113,6 +113,7 @@ export declare const pageStateShape: {
         url: z.ZodOptional<z.ZodString>;
         ms: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>;
+    actionTimeoutMs: z.ZodOptional<z.ZodNumber>;
     routes: z.ZodOptional<z.ZodArray<z.ZodObject<{
         url: z.ZodString;
         method: z.ZodOptional<z.ZodString>;
@@ -154,6 +155,7 @@ export declare const pageStateShape: {
     }>>;
 };
 export interface PageStateInput {
+    actionTimeoutMs?: number;
     storageState?: string;
     headers?: Record<string, string>;
     actions?: Array<z.infer<typeof pageActionSchema>>;
@@ -186,6 +188,8 @@ export interface ResolvedRouteMock {
     delayMs?: number;
 }
 export interface ResolvedPageState {
+    /** Per-action wait in ms (the probe's default is 10000). */
+    actionTimeout?: number;
     storageState?: string;
     headers?: Record<string, string>;
     actions?: Array<{
@@ -227,7 +231,7 @@ export declare function describeRouteHits(state: ResolvedPageState, hits: number
 /** A hint when an unauthenticated page landed on a login screen. */
 export declare function loginHint(finalUrl: string | undefined, state: ResolvedPageState): string | undefined;
 export interface BrowserScriptConfig extends Omit<ResolvedPageState, never> {
-    mode: 'inspect' | 'validate' | 'screenshot' | 'heal' | 'a11y' | 'perf';
+    mode: 'inspect' | 'validate' | 'screenshot' | 'heal' | 'a11y' | 'perf' | 'login';
     projectRoot: string;
     /** Page to open; omitted when rendering a snapshot. */
     url?: string;
@@ -264,6 +268,13 @@ export interface BrowserScriptConfig extends Omit<ResolvedPageState, never> {
     mobile?: boolean;
     /** perf: ms to keep observing after load so late shifts and LCP land. */
     settleMs?: number;
+    /** login: how to tell the session works, and whether to only check it. */
+    loginVerify?: {
+        url?: string;
+        visible?: LocatorCall[];
+        notUrl?: string;
+    };
+    loginCheckOnly?: boolean;
     startedAt: number;
 }
 /** Network emulation in Chrome DevTools terms (throughput in bytes/s). */
@@ -299,6 +310,23 @@ export interface BrowserScriptData {
     ariaTruncated?: boolean;
     /** Requests each network mock in `routes` handled, by index. */
     routeHits?: number[];
+    /** HTTP status of the page's main document, when it was fetched over the network. */
+    httpStatus?: number;
+    /** mode 'login': the session check and what the session holds. */
+    login?: LoginScan;
+}
+export interface LoginScan {
+    /** null when no check was asked for. */
+    verified: boolean | null;
+    verifyNote?: string;
+    /** The storageState to save; absent when checking only or the check failed. */
+    state?: unknown;
+    cookies: number;
+    sessionCookies: number;
+    origins: number;
+    /** Earliest cookie expiry, in Unix seconds. */
+    firstExpiry: number | null;
+    expired: number;
 }
 export interface PerformanceResource {
     url: string;
@@ -380,6 +408,7 @@ export interface BrowserScriptOutcome {
 export declare function runBrowserScript(config: BrowserScriptConfig, options: {
     timeoutMs?: number;
     signal?: AbortSignal;
+    env?: Record<string, string>;
 }): Promise<BrowserScriptOutcome>;
 /** Accept only http(s) URLs for page-facing tools. */
 export declare function assertHttpUrl(url: string): string;

package/dist/tools/shared.js

@@ -294,7 +294,18 @@ export const routeMockSchema = z.object({
 /** Inputs shared by every tool that opens a page. */
 export const pageStateShape = {
     ...sessionShape,
-    actions: z.array(pageActionSchema).max(20).optional().describe('Steps run after load to reach a state (modal, step 3)'),
+    actions: z
+        .array(pageActionSchema)
+        .max(20)
+        .optional()
+        .describe("Steps run in order after load to reach a state (modal, step 3). One call = one fresh browser, so include the login steps; end with a 'wait' on what the state shows"),
+    actionTimeoutMs: z
+        .number()
+        .int()
+        .min(1_000)
+        .max(120_000)
+        .optional()
+        .describe('How long each action waits for its element (default 10000); keep timeoutMs above the total'),
     routes: z
         .array(routeMockSchema)
         .max(20)
@@ -365,7 +376,7 @@ async function resolveHar(har, root, ctx) {
 function assertHeaders(headers, what) {
     for (const [name, value] of Object.entries(headers)) {
         if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name) || /[\r\n]/.test(value)) {
-            throw new PlaywrightMcpError(`Invalid ${what} "${name}"`, 'INVALID_PATH', {
+            throw new PlaywrightMcpError(`Invalid ${what} "${name}"`, 'INVALID_INPUT', {
                 hint: 'Header names must be tokens and values must be single-line.',
             });
         }
@@ -377,13 +388,13 @@ export function resolveRouteMocks(routes) {
         const step = `routes[${i}] (${route.url})`;
         const method = route.method?.trim().toUpperCase();
         if (method !== undefined && !/^[A-Z]+$/.test(method)) {
-            throw new PlaywrightMcpError(`${step}: "${route.method}" is not an HTTP method`, 'INVALID_PATH');
+            throw new PlaywrightMcpError(`${step}: "${route.method}" is not an HTTP method`, 'INVALID_INPUT');
         }
         if (route.json !== undefined && route.body !== undefined) {
-            throw new PlaywrightMcpError(`${step}: pass json or body, not both`, 'INVALID_PATH');
+            throw new PlaywrightMcpError(`${step}: pass json or body, not both`, 'INVALID_INPUT');
         }
         if (route.abort && (route.json !== undefined || route.body !== undefined || route.status !== undefined)) {
-            throw new PlaywrightMcpError(`${step}: abort cannot be combined with a response`, 'INVALID_PATH');
+            throw new PlaywrightMcpError(`${step}: abort cannot be combined with a response`, 'INVALID_INPUT');
         }
         if (route.headers)
             assertHeaders(route.headers, `${step} header`);
@@ -392,7 +403,7 @@ export function resolveRouteMocks(routes) {
         if (route.json !== undefined) {
             body = JSON.stringify(route.json);
             if (body === undefined || body.length > MAX_MOCK_BODY) {
-                throw new PlaywrightMcpError(`${step}: json must be serialisable and under ${MAX_MOCK_BODY} characters`, 'INVALID_PATH');
+                throw new PlaywrightMcpError(`${step}: json must be serialisable and under ${MAX_MOCK_BODY} characters`, 'INVALID_INPUT');
             }
             contentType ??= 'application/json';
         }
@@ -461,12 +472,12 @@ export async function resolvePageState(input, root, entryUrl, ctx) {
         out.har = await resolveHar(input.har, root, ctx);
     if (input.browser && input.browser !== 'chromium') {
         if (serverlessChromiumEnabled()) {
-            throw new PlaywrightMcpError(`${input.browser} is not available on the hosted endpoint`, 'INVALID_PATH', {
+            throw new PlaywrightMcpError(`${input.browser} is not available on the hosted endpoint`, 'INVALID_INPUT', {
                 hint: "The hosted endpoint bundles Chromium only. Use 'chromium', or run the server locally for Firefox and WebKit.",
             });
         }
         if (input.browser === 'webkit' && blockPrivateUrls()) {
-            throw new PlaywrightMcpError('webkit is not available while private addresses are blocked', 'INVALID_PATH', {
+            throw new PlaywrightMcpError('webkit is not available while private addresses are blocked', 'INVALID_INPUT', {
                 hint: "WebKit cannot route every connection through the address guard. Use 'chromium' or 'firefox'.",
             });
         }
@@ -475,7 +486,7 @@ export async function resolvePageState(input, root, entryUrl, ctx) {
     if (input.device) {
         // Checked against the project's own Playwright device list in the browser child.
         if (!/^[\w .()+-]+$/.test(input.device)) {
-            throw new PlaywrightMcpError(`device "${input.device}" is not a Playwright device name`, 'INVALID_PATH', {
+            throw new PlaywrightMcpError(`device "${input.device}" is not a Playwright device name`, 'INVALID_INPUT', {
                 hint: "Use a name from Playwright's device list, e.g. 'iPhone 15' or 'Pixel 7'.",
             });
         }
@@ -483,12 +494,12 @@ export async function resolvePageState(input, root, entryUrl, ctx) {
     }
     if (input.channel) {
         if ((input.browser ?? 'chromium') !== 'chromium') {
-            throw new PlaywrightMcpError(`channel ${input.channel} needs the chromium engine`, 'INVALID_PATH', {
+            throw new PlaywrightMcpError(`channel ${input.channel} needs the chromium engine`, 'INVALID_INPUT', {
                 hint: 'Leave browser unset (or chromium) when you pick a channel.',
             });
         }
         if (serverlessChromiumEnabled()) {
-            throw new PlaywrightMcpError(`channel ${input.channel} is not available on the hosted endpoint`, 'INVALID_PATH', {
+            throw new PlaywrightMcpError(`channel ${input.channel} is not available on the hosted endpoint`, 'INVALID_INPUT', {
                 hint: 'The hosted endpoint bundles one Chromium build. Run the server locally to test in Chrome or Edge.',
             });
         }
@@ -496,6 +507,8 @@ export async function resolvePageState(input, root, entryUrl, ctx) {
     }
     if (input.routes && input.routes.length > 0)
         out.routes = resolveRouteMocks(input.routes);
+    if (input.actionTimeoutMs !== undefined)
+        out.actionTimeout = input.actionTimeoutMs;
     if (input.actions && input.actions.length > 0) {
         out.actions = [];
         let current = entryUrl;
@@ -503,13 +516,13 @@ export async function resolvePageState(input, root, entryUrl, ctx) {
             const step = `actions[${i}] (${action.type})`;
             if (action.type === 'goto') {
                 if (!action.url)
-                    throw new PlaywrightMcpError(`${step} needs a url`, 'INVALID_PATH');
+                    throw new PlaywrightMcpError(`${step} needs a url`, 'INVALID_INPUT');
                 let next;
                 try {
                     next = new URL(action.url, current).toString();
                 }
                 catch {
-                    throw new PlaywrightMcpError(`${step}: "${action.url}" is not a valid URL`, 'INVALID_PATH');
+                    throw new PlaywrightMcpError(`${step}: "${action.url}" is not a valid URL`, 'INVALID_INPUT');
                 }
                 assertHttpUrl(next);
                 await assertUrlAllowed(next);
@@ -518,10 +531,10 @@ export async function resolvePageState(input, root, entryUrl, ctx) {
                 continue;
             }
             if (NEEDS_LOCATOR.has(action.type) && !action.locator) {
-                throw new PlaywrightMcpError(`${step} needs a locator`, 'INVALID_PATH');
+                throw new PlaywrightMcpError(`${step} needs a locator`, 'INVALID_INPUT');
             }
             if ((action.type === 'press' || action.type === 'select') && action.value === undefined) {
-                throw new PlaywrightMcpError(`${step} needs a value`, 'INVALID_PATH');
+                throw new PlaywrightMcpError(`${step} needs a value`, 'INVALID_INPUT');
             }
             const locator = action.locator ? parseLocator(action.locator) : undefined;
             out.actions.push({
@@ -613,7 +626,7 @@ export async function runBrowserScript(config, options) {
     try {
         const outcome = await runProcess(process.execPath, [scriptPath, configPath], {
             cwd: config.projectRoot,
-            env: childEnv({ FORCE_COLOR: '0', ...serverless?.env }),
+            env: childEnv({ FORCE_COLOR: '0', ...serverless?.env, ...options.env }),
             timeoutMs: options.timeoutMs ?? 45_000,
             signal: options.signal,
         });
@@ -628,6 +641,26 @@ export async function runBrowserScript(config, options) {
         if (outcome.aborted) {
             return { ok: false, kind: 'CLIENT_DISCONNECT', error: 'Inspection aborted (client disconnected).' };
         }
+        // Checked before the child's output: killing it closes the browser, and the
+        // "browser has been closed" error it prints then is not a crash.
+        if (outcome.timedOut) {
+            const done = extractJsonFromText(outcome.stdout);
+            let steps;
+            try {
+                steps = done ? JSON.parse(done).actionsDone : undefined;
+            }
+            catch {
+                /* no usable output */
+            }
+            return {
+                ok: false,
+                kind: 'TIMEOUT',
+                error: `The whole call exceeded timeoutMs (${options.timeoutMs ?? 45_000}ms) and was stopped.`,
+                hint: 'Raise timeoutMs. It covers launch, navigation and every action, so keep it above the sum of the waits (each action waits up to actionTimeoutMs, default 10000).',
+                ...(steps?.length ? { actionsDone: steps } : {}),
+                stderrTail: tailText(outcome.stderr),
+            };
+        }
         const json = extractJsonFromText(outcome.stdout);
         if (json !== null) {
             try {
@@ -647,15 +680,6 @@ export async function runBrowserScript(config, options) {
                 /* fall through to generic handling */
             }
         }
-        if (outcome.timedOut) {
-            return {
-                ok: false,
-                kind: 'TIMEOUT',
-                error: `Page inspection exceeded ${options.timeoutMs ?? 45_000}ms and was killed.`,
-                hint: 'The page may be blocking on network requests. Raise timeoutMs or use waitUntil: "domcontentloaded".',
-                stderrTail: tailText(outcome.stderr),
-            };
-        }
         return {
             ok: false,
             kind: 'UNKNOWN',
@@ -681,12 +705,12 @@ export function assertHttpUrl(url) {
         parsed = new URL(trimmed);
     }
     catch {
-        throw new PlaywrightMcpError(`"${url}" is not a valid URL`, 'INVALID_PATH', {
+        throw new PlaywrightMcpError(`"${url}" is not a valid URL`, 'INVALID_INPUT', {
             hint: 'Use a full URL, e.g. http://localhost:3000/login',
         });
     }
     if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
-        throw new PlaywrightMcpError(`Unsupported URL scheme "${parsed.protocol}"`, 'INVALID_PATH', {
+        throw new PlaywrightMcpError(`Unsupported URL scheme "${parsed.protocol}"`, 'INVALID_INPUT', {
             hint: 'Only http:// and https:// URLs are supported.',
         });
     }