Playwright - Trigger.dev

If you are using Playwright, you should use the Playwright build extension.

Automatically installs Playwright and required browser dependencies
Allows you to specify which browsers to install (chromium, firefox, webkit)
Supports headless or non-headless mode
Lets you specify the Playwright version, or auto-detects it
Installs only the dependencies needed for the selected browsers to optimize build time and image size

This extension only affects the build and deploy process, not the dev command.

You can use it for a simple Playwright setup like this:

import { defineConfig } from "@trigger.dev/sdk";
import { playwright } from "@trigger.dev/build/extensions/playwright";

export default defineConfig({
  project: "<project ref>",
  // Your other config settings...
  build: {
    extensions: [
      playwright(),
    ],
  },
});

Options

browsers: Array of browsers to install. Valid values: "chromium", "firefox", "webkit". Default: ["chromium"].
headless: Run browsers in headless mode. Default: true. If set to false, a virtual display (Xvfb) will be set up automatically.
version: Playwright version to install. If not provided, the version will be auto-detected from your dependencies (recommended).
Using a different version in your app than specified here will break things. We recommend not setting this option to automatically detect the version.

Custom browsers and version

import { defineConfig } from "@trigger.dev/sdk";
import { playwright } from "@trigger.dev/build/extensions/playwright";

export default defineConfig({
  project: "<project ref>",
  build: {
    extensions: [
      playwright({
        browsers: ["chromium", "webkit"], // optional, will use ["chromium"] if not provided
        version: "1.43.1",  // optional, will automatically detect the version if not provided
      }),
    ],
  },
});

Headless mode

By default, browsers are run in headless mode. If you need to run browsers with a UI (for example, for debugging), set headless: false. This will automatically set up a virtual display using Xvfb.

import { defineConfig } from "@trigger.dev/sdk";
import { playwright } from "@trigger.dev/build/extensions/playwright";

export default defineConfig({
  project: "<project ref>",
  build: {
    extensions: [
      playwright({
        headless: false,
      }),
    ],
  },
});

Environment variables

The extension sets the following environment variables during the build:

PLAYWRIGHT_BROWSERS_PATH: Set to /ms-playwright so Playwright finds the installed browsers
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: Set to 1 to skip browser download at runtime
PLAYWRIGHT_SKIP_BROWSER_VALIDATION: Set to 1 to skip browser validation at runtime
DISPLAY: Set to :99 if headless: false (for Xvfb)

Troubleshooting

Browser download failures

If you encounter errors during the build process related to browser downloads (e.g., “failed to solve: process did not complete successfully: exit code: 9”), this is a known issue with certain Playwright versions. Workaround: Revert Playwright to version 1.40.0 in your project dependencies. You can specify this version explicitly in your config:

import { defineConfig } from "@trigger.dev/sdk";
import { playwright } from "@trigger.dev/build/extensions/playwright";

export default defineConfig({
  project: "<project ref>",
  build: {
    extensions: [
      playwright({
        version: "1.40.0",
      }),
    ],
  },
});

For more details, see GitHub issue #2440.

Managing browser instances

To prevent issues with waits and resumes, you can use middleware and locals to manage the browser instance. This will ensure the browser is available for the whole run, and is properly cleaned up on waits, resumes, and after the run completes. Here’s an example using chromium, but you can adapt it for other browsers:

import { logger, tasks, locals } from "@trigger.dev/sdk";
import { chromium, type Browser } from "playwright";

// Create a locals key for the browser instance
const PlaywrightBrowserLocal = locals.create<{ browser: Browser }>("playwright-browser");

export function getBrowser() {
  return locals.getOrThrow(PlaywrightBrowserLocal).browser;
}

export function setBrowser(browser: Browser) {
  locals.set(PlaywrightBrowserLocal, { browser });
}

tasks.middleware("playwright-browser", async ({ next }) => {
  // Launch the browser before the task runs
  const browser = await chromium.launch();
  setBrowser(browser);
  logger.log("[chromium]: Browser launched (middleware)");

  try {
    await next();
  } finally {
    // Always close the browser after the task completes
    await browser.close();
    logger.log("[chromium]: Browser closed (middleware)");
  }
});

tasks.onWait("playwright-browser", async () => {
  // Close the browser when the run is waiting
  const browser = getBrowser();
  await browser.close();
  logger.log("[chromium]: Browser closed (onWait)");
});

tasks.onResume("playwright-browser", async () => {
  // Relaunch the browser when the run resumes
  // Note: You will have to have to manually get a new browser instance in the run function
  const browser = await chromium.launch();
  setBrowser(browser);
  logger.log("[chromium]: Browser launched (onResume)");
});

You can then use getBrowser() in your task’s run function to access the browser instance:

export const playwrightTestTask = task({
  id: "playwright-test",
  run: async () => {
    const browser = getBrowser();
    const page = await browser.newPage();
    await page.goto("https://google.com");
    await page.screenshot({ path: "screenshot.png" });
    await page.close();

    // Waits will gracefully close the browser
    await wait.for({ seconds: 10 });

    // On resume, we will re-launch the browser but you will have to manually get the new instance
    const newBrowser = getBrowser();
    const newPage = await newBrowser.newPage();
    await newPage.goto("https://playwright.dev");
    await newPage.screenshot({ path: "screenshot2.png" });
    await newPage.close();
  },
});

​Options

​Custom browsers and version

​Headless mode

​Environment variables

​Troubleshooting

​Browser download failures

​Managing browser instances

Options

Custom browsers and version

Headless mode

Environment variables

Troubleshooting

Browser download failures

Managing browser instances