Playwright CRX

This package contains the Chrome Extensions flavor of the Playwright library.

For that, it relies on chrome.debugger to implement playwright's ConnectionTransport interface.

NOTE: If you want to write end-to-end tests, you should use @playwright/test instead.

Recorder / Player

Note: This extension is available in Chrome Web Store.

A small demo of Playwright CRX recorder and player in action:

It provides playwright recorder (the same used in playwright codegen) bundled as a chrome extension, with no other dependencies. This way, with your normal chrome / chromium / edge browser, you can record playwright scripts in your prefered language.

In terms of chrome extension functionality, it provides:

• action button for attaching current tab into recorder (it opens the recorder if it's closed)
• context menu for the same purpose
• side panel to display the recorder by default (it can be disabled in the options, falling back to a popup window)
• command shortcuts:
  • Alt + Shift + R starts recording
  • Alt + Shift + C starts inspecting
• options page to configure:
  • Default language (defaults to Node Library)
  • TestID Attribute Name (defaults to data-testid)
  • Open in Side Panel (defaults to true, and falls back to a popup window if set to false)
• pages must be explicitly attached to be recordable, except if they are opened from already attached pages
• closing the recorder window will detach all pages and uninstall injected scripts (highlights and event listeners)
• a player that will run the recorded instructions, in any supported language*
  • it actually doesn't run Java, Python or C#, but it uses an internal JSONL format to know which instructions it needs to run and how to map them into the current selected code. This way, it can highlight the lines being executed.

API

It's possible to use playwright-crx as a library to create new chrome extensions.

Here's a simple example of a background service worker for a chrome extension using playwright-crx:

import { crx, expect } from 'playwright-crx/test';

// if you don't need assertions, you can reduce the bundle size by importing crx from playwright-crx
// import { crx } from 'playwright-crx';

chrome.action.onClicked.addListener(async ({ id: tabId }) => {
  const crxApp = await crx.start({ slowMo: 500 });

  try {
    // tries to connect to the active tab, or creates a new one
    const page = await crxApp.attach(tabId!).catch(() => crxApp.newPage());

    await page.goto('https://demo.playwright.dev/todomvc/#/');
    await page.getByPlaceholder('What needs to be done?').click();
    await page.getByPlaceholder('What needs to be done?').fill('Hello World!');
    await page.getByPlaceholder('What needs to be done?').press('Enter');

    // assertions work too
    await expect(page.getByTestId('todo-title')).toHaveText('Hello World!');
  } finally {
    // page stays open, but no longer controlled by playwright
    await crxApp.detach(page);
    // releases chrome.debugger
    await crxApp.close();
  }
});

A more complete example can be found in examples/todomvc-crx.

Tracing

Playwright CRX also supports tracing, compatible with Playwright Trace Viewer.

For it to work properly, some additional steps are required:

• ensure vite generates source maps with rollup-plugin-sourcemaps and doesn't minify the code:

import { defineConfig } from 'vite';
import sourcemaps from 'rollup-plugin-sourcemaps';

export default defineConfig({
  build: {
    minify: false,
    sourcemap: true,
    rollupOptions: {
      plugins: [sourcemaps()],
      // other configurations
    },
  },
});

• add the following CSP to your extension manifest.json:

  "content_security_policy": {
    "extension_pages": "script-src 'self' 'wasm-unsafe-eval'"
  }

• on the extension service worker script, register the application source map as soon as possible:

import { crx, registerSourceMap } from 'playwright-crx';

registerSourceMap().catch(() => {});

A complete example can be found in examples/todomvc-crx.

Build

To build playwright-crx:

npm ci
npm run build

Updating Playwright

Playwright is nested as a git subtree.

To update it, just run the following command (replace v1.48.0 with the desired release tag):

git subtree pull --prefix=playwright [email protected]:microsoft/playwright.git v1.48.0 --squash