@playwright/mcp 0.0.25 → 0.0.26

package/README.md

@@ -146,6 +146,8 @@ Playwright MCP server supports following arguments. They can be provided in the
                                example ".com,chromium.org,.domain.com"
   --proxy-server <proxy>       specify proxy server, for example
                                "http://myproxy:3128" or "socks5://myproxy:8080"
+  --save-trace                 Whether to save the Playwright Trace of the
+                               session into the output directory.
   --storage-state <path>       path to the storage state file for isolated
                                sessions.
   --user-agent <ua string>     specify user agent string

package/config.d.ts

@@ -94,6 +94,11 @@ export type Config = {
    */
   vision?: boolean;
 
+  /**
+   * Whether to save the Playwright trace of the session into the output directory.
+   */
+  saveTrace?: boolean;
+
   /**
    * The directory to save output files.
    */

package/lib/config.js

@@ -35,11 +35,19 @@ const defaultConfig = {
         allowedOrigins: undefined,
         blockedOrigins: undefined,
     },
+    outputDir: path.join(os.tmpdir(), 'playwright-mcp-output', sanitizeForFilePath(new Date().toISOString())),
 };
-export async function resolveConfig(cliOptions) {
-    const config = await loadConfig(cliOptions.config);
+export async function resolveConfig(config) {
+    return mergeConfig(defaultConfig, config);
+}
+export async function resolveCLIConfig(cliOptions) {
+    const configInFile = await loadConfig(cliOptions.config);
     const cliOverrides = await configFromCLIOptions(cliOptions);
-    return mergeConfig(defaultConfig, mergeConfig(config, cliOverrides));
+    const result = mergeConfig(mergeConfig(defaultConfig, configInFile), cliOverrides);
+    // Derive artifact output directory from config.outputDir
+    if (result.saveTrace)
+        result.browser.launchOptions.tracesDir = path.join(result.outputDir, 'traces');
+    return result;
 }
 export async function configFromCLIOptions(cliOptions) {
     let browserName;
@@ -127,6 +135,7 @@ export async function configFromCLIOptions(cliOptions) {
             allowedOrigins: cliOptions.allowedOrigins,
             blockedOrigins: cliOptions.blockedOrigins,
         },
+        saveTrace: cliOptions.saveTrace,
         outputDir: cliOptions.outputDir,
     };
     if (!cliOptions.imageResponses) {
@@ -156,18 +165,17 @@ async function loadConfig(configFile) {
     }
 }
 export async function outputFile(config, name) {
-    const result = config.outputDir ?? os.tmpdir();
-    await fs.promises.mkdir(result, { recursive: true });
+    await fs.promises.mkdir(config.outputDir, { recursive: true });
     const fileName = sanitizeForFilePath(name);
-    return path.join(result, fileName);
+    return path.join(config.outputDir, fileName);
 }
 function pickDefined(obj) {
     return Object.fromEntries(Object.entries(obj ?? {}).filter(([_, v]) => v !== undefined));
 }
 function mergeConfig(base, overrides) {
     const browser = {
-        ...pickDefined(base.browser),
-        ...pickDefined(overrides.browser),
+        browserName: overrides.browser?.browserName ?? base.browser?.browserName ?? 'chromium',
+        isolated: overrides.browser?.isolated ?? base.browser?.isolated ?? false,
         launchOptions: {
             ...pickDefined(base.browser?.launchOptions),
             ...pickDefined(overrides.browser?.launchOptions),
@@ -177,6 +185,9 @@ function mergeConfig(base, overrides) {
             ...pickDefined(base.browser?.contextOptions),
             ...pickDefined(overrides.browser?.contextOptions),
         },
+        userDataDir: overrides.browser?.userDataDir ?? base.browser?.userDataDir,
+        cdpEndpoint: overrides.browser?.cdpEndpoint ?? base.browser?.cdpEndpoint,
+        remoteEndpoint: overrides.browser?.remoteEndpoint ?? base.browser?.remoteEndpoint,
     };
     if (browser.browserName !== 'chromium' && browser.launchOptions)
         delete browser.launchOptions.channel;
@@ -187,6 +198,6 @@ function mergeConfig(base, overrides) {
         network: {
             ...pickDefined(base.network),
             ...pickDefined(overrides.network),
-        },
+        }
     };
 }

package/lib/context.js

@@ -18,7 +18,7 @@ import url from 'node:url';
 import os from 'node:os';
 import path from 'node:path';
 import * as playwright from 'playwright';
-import { waitForCompletion } from './tools/utils.js';
+import { callOnPageNoTrace, waitForCompletion } from './tools/utils.js';
 import { ManualPromise } from './manualPromise.js';
 import { Tab } from './tab.js';
 import { outputFile } from './config.js';
@@ -84,7 +84,7 @@ export class Context {
         const lines = ['### Open tabs'];
         for (let i = 0; i < this._tabs.length; i++) {
             const tab = this._tabs[i];
-            const title = await tab.page.title();
+            const title = await tab.title();
             const url = tab.page.url();
             const current = tab === this._currentTab ? ' (current)' : '';
             lines.push(`- ${i + 1}:${current} [${title}] (${url})`);
@@ -116,7 +116,7 @@ export class Context {
         let actionResult;
         try {
             if (waitForNetwork)
-                actionResult = await waitForCompletion(this, tab.page, async () => racingAction?.()) ?? undefined;
+                actionResult = await waitForCompletion(this, tab, async () => racingAction?.()) ?? undefined;
             else
                 actionResult = await racingAction?.() ?? undefined;
         }
@@ -153,7 +153,7 @@ ${code.join('\n')}
             result.push(await this.listTabsMarkdown(), '');
         if (this.tabs().length > 1)
             result.push('### Current tab');
-        result.push(`- Page URL: ${tab.page.url()}`, `- Page Title: ${await tab.page.title()}`);
+        result.push(`- Page URL: ${tab.page.url()}`, `- Page Title: ${await tab.title()}`);
         if (captureSnapshot && tab.hasSnapshot())
             result.push(tab.snapshotOrDie().text());
         const content = actionResult?.content ?? [];
@@ -168,10 +168,13 @@ ${code.join('\n')}
         };
     }
     async waitForTimeout(time) {
-        if (this._currentTab && !this._javaScriptBlocked())
-            await this._currentTab.page.evaluate(() => new Promise(f => setTimeout(f, 1000)));
-        else
+        if (!this._currentTab || this._javaScriptBlocked()) {
             await new Promise(f => setTimeout(f, time));
+            return;
+        }
+        await callOnPageNoTrace(this._currentTab.page, page => {
+            return page.evaluate(() => new Promise(f => setTimeout(f, 1000)));
+        });
     }
     async _raceAgainstModalDialogs(action) {
         this._pendingAction = {
@@ -233,6 +236,8 @@ ${code.join('\n')}
         const promise = this._browserContextPromise;
         this._browserContextPromise = undefined;
         await promise.then(async ({ browserContext, browser }) => {
+            if (this.config.saveTrace)
+                await browserContext.tracing.stop();
             await browserContext.close().then(async () => {
                 await browser?.close();
             }).catch(() => { });
@@ -264,6 +269,14 @@ ${code.join('\n')}
         for (const page of browserContext.pages())
             this._onPageCreated(page);
         browserContext.on('page', page => this._onPageCreated(page));
+        if (this.config.saveTrace) {
+            await browserContext.tracing.start({
+                name: 'trace',
+                screenshots: false,
+                snapshots: true,
+                sources: false,
+            });
+        }
         return { browser, browserContext };
     }
     async _createBrowserContext() {
@@ -291,8 +304,8 @@ async function createIsolatedContext(browserConfig) {
     try {
         const browserName = browserConfig?.browserName ?? 'chromium';
         const browserType = playwright[browserName];
-        const browser = await browserType.launch(browserConfig?.launchOptions);
-        const browserContext = await browser.newContext(browserConfig?.contextOptions);
+        const browser = await browserType.launch(browserConfig.launchOptions);
+        const browserContext = await browser.newContext(browserConfig.contextOptions);
         return { browser, browserContext };
     }
     catch (error) {
@@ -303,10 +316,10 @@ async function createIsolatedContext(browserConfig) {
 }
 async function launchPersistentContext(browserConfig) {
     try {
-        const browserName = browserConfig?.browserName ?? 'chromium';
-        const userDataDir = browserConfig?.userDataDir ?? await createUserDataDir({ ...browserConfig, browserName });
+        const browserName = browserConfig.browserName ?? 'chromium';
+        const userDataDir = browserConfig.userDataDir ?? await createUserDataDir({ ...browserConfig, browserName });
         const browserType = playwright[browserName];
-        const browserContext = await browserType.launchPersistentContext(userDataDir, { ...browserConfig?.launchOptions, ...browserConfig?.contextOptions });
+        const browserContext = await browserType.launchPersistentContext(userDataDir, { ...browserConfig.launchOptions, ...browserConfig.contextOptions });
         return { browserContext };
     }
     catch (error) {
@@ -325,12 +338,9 @@ async function createUserDataDir(browserConfig) {
         cacheDirectory = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
     else
         throw new Error('Unsupported platform: ' + process.platform);
-    const result = path.join(cacheDirectory, 'ms-playwright', `mcp-${browserConfig?.launchOptions?.channel ?? browserConfig?.browserName}-profile`);
+    const result = path.join(cacheDirectory, 'ms-playwright', `mcp-${browserConfig.launchOptions?.channel ?? browserConfig?.browserName}-profile`);
     await fs.promises.mkdir(result, { recursive: true });
     return result;
 }
-export async function generateLocator(locator) {
-    return locator._generateLocatorString();
-}
 const __filename = url.fileURLToPath(import.meta.url);
 export const packageJSON = JSON.parse(fs.readFileSync(path.join(path.dirname(__filename), '..', 'package.json'), 'utf8'));

package/lib/index.js

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 import { createConnection as createConnectionImpl } from './connection.js';
-export async function createConnection(config = {}) {
+import { resolveConfig } from './config.js';
+export async function createConnection(userConfig = {}) {
+    const config = await resolveConfig(userConfig);
     return createConnectionImpl(config);
 }

package/lib/pageSnapshot.js

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { callOnPageNoTrace } from './tools/utils.js';
 export class PageSnapshot {
     _page;
     _text;
@@ -28,11 +29,14 @@ export class PageSnapshot {
         return this._text;
     }
     async _build() {
-        const yamlDocument = await this._page._snapshotForAI();
+        // FIXME: Rountrip evaluate to ensure _snapshotForAI works.
+        // This probably broke once we moved off locator snapshots
+        await this._page.evaluate(() => 1);
+        const snapshot = await callOnPageNoTrace(this._page, page => page._snapshotForAI());
         this._text = [
             `- Page Snapshot`,
             '```yaml',
-            yamlDocument.toString({ indentSeq: false }).trim(),
+            snapshot,
             '```',
         ].join('\n');
     }

package/lib/program.js

@@ -15,7 +15,9 @@
  */
 import { program } from 'commander';
 import { startHttpTransport, startStdioTransport } from './transport.js';
-import { resolveConfig } from './config.js';
+import { resolveCLIConfig } from './config.js';
+// @ts-ignore
+import { startTraceViewerServer } from 'playwright-core/lib/server';
 import { packageJSON } from './context.js';
 program
     .version('Version ' + packageJSON.version)
@@ -39,19 +41,27 @@ program
     .option('--port <port>', 'port to listen on for SSE transport.')
     .option('--proxy-bypass <bypass>', 'comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"')
     .option('--proxy-server <proxy>', 'specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080"')
+    .option('--save-trace', 'Whether to save the Playwright Trace of the session into the output directory.')
     .option('--storage-state <path>', 'path to the storage state file for isolated sessions.')
     .option('--user-agent <ua string>', 'specify user agent string')
     .option('--user-data-dir <path>', 'path to the user data directory. If not specified, a temporary directory will be created.')
     .option('--viewport-size <size>', 'specify browser viewport size in pixels, for example "1280, 720"')
     .option('--vision', 'Run server that uses screenshots (Aria snapshots are used by default)')
     .action(async (options) => {
-    const config = await resolveConfig(options);
+    const config = await resolveCLIConfig(options);
     const connectionList = [];
     setupExitWatchdog(connectionList);
     if (options.port)
         startHttpTransport(config, +options.port, options.host, connectionList);
     else
         await startStdioTransport(config, connectionList);
+    if (config.saveTrace) {
+        const server = await startTraceViewerServer();
+        const urlPrefix = server.urlPrefix('human-readable');
+        const url = urlPrefix + '/trace/index.html?trace=' + config.browser.launchOptions.tracesDir + '/trace.json';
+        // eslint-disable-next-line no-console
+        console.error('\nTrace viewer listening on ' + url);
+    }
 });
 function setupExitWatchdog(connectionList) {
     const handleExit = async () => {

package/lib/tab.js

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 import { PageSnapshot } from './pageSnapshot.js';
+import { callOnPageNoTrace } from './tools/utils.js';
 export class Tab {
     context;
     page;
@@ -51,9 +52,15 @@ export class Tab {
         this._clearCollectedArtifacts();
         this._onPageClose(this);
     }
+    async title() {
+        return await callOnPageNoTrace(this.page, page => page.title());
+    }
+    async waitForLoadState(state, options) {
+        await callOnPageNoTrace(this.page, page => page.waitForLoadState(state, options).catch(() => { }));
+    }
     async navigate(url) {
         this._clearCollectedArtifacts();
-        const downloadEvent = this.page.waitForEvent('download').catch(() => { });
+        const downloadEvent = callOnPageNoTrace(this.page, page => page.waitForEvent('download').catch(() => { }));
         try {
             await this.page.goto(url, { waitUntil: 'domcontentloaded' });
         }
@@ -72,7 +79,7 @@ export class Tab {
                 throw e;
         }
         // Cap load event to 5 seconds, the page is operational at this point.
-        await this.page.waitForLoadState('load', { timeout: 5000 }).catch(() => { });
+        await this.waitForLoadState('load', { timeout: 5000 });
     }
     hasSnapshot() {
         return !!this._snapshot;

package/lib/tools/utils.js

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export async function waitForCompletion(context, page, callback) {
+export async function waitForCompletion(context, tab, callback) {
     const requests = new Set();
     let frameNavigated = false;
     let waitCallback = () => { };
@@ -30,22 +30,20 @@ export async function waitForCompletion(context, page, callback) {
         frameNavigated = true;
         dispose();
         clearTimeout(timeout);
-        void frame.waitForLoadState('load').then(() => {
-            waitCallback();
-        });
+        void tab.waitForLoadState('load').then(waitCallback);
     };
     const onTimeout = () => {
         dispose();
         waitCallback();
     };
-    page.on('request', requestListener);
-    page.on('requestfinished', requestFinishedListener);
-    page.on('framenavigated', frameNavigateListener);
+    tab.page.on('request', requestListener);
+    tab.page.on('requestfinished', requestFinishedListener);
+    tab.page.on('framenavigated', frameNavigateListener);
     const timeout = setTimeout(onTimeout, 10000);
     const dispose = () => {
-        page.off('request', requestListener);
-        page.off('requestfinished', requestFinishedListener);
-        page.off('framenavigated', frameNavigateListener);
+        tab.page.off('request', requestListener);
+        tab.page.off('requestfinished', requestFinishedListener);
+        tab.page.off('framenavigated', frameNavigateListener);
         clearTimeout(timeout);
     };
     try {
@@ -68,5 +66,8 @@ export function sanitizeForFilePath(s) {
     return sanitize(s.substring(0, separator)) + '.' + sanitize(s.substring(separator + 1));
 }
 export async function generateLocator(locator) {
-    return locator._generateLocatorString();
+    return locator._frame._wrapApiCall(() => locator._generateLocatorString(), true);
+}
+export async function callOnPageNoTrace(page, callback) {
+    return await page._wrapApiCall(() => callback(page), true);
 }

package/lib/transport.js

@@ -127,6 +127,6 @@ export function startHttpTransport(config, port, hostname, connectionList) {
             'If your client supports streamable HTTP, you can use the /mcp endpoint instead.',
         ].join('\n');
         // eslint-disable-next-line no-console
-        console.log(message);
+        console.error(message);
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.25",
+  "version": "0.0.26",
   "description": "Playwright Tools for MCP",
   "type": "module",
   "repository": {