• Check if you already have Node installed by opening a terminal or command prompt instance and executing node -v. You should see a version number in the return.

  • If you do not have Node already installed, go to Node.js and select the version associated with your operating system.


Check if you already have Anvil installed through Foundry by opening a terminal or command prompt instance and executing anvil -V. You should see a version number in the return. If you do not, follow one of the guides below.


You can install GuardianTest using either npm or yarn:

NOTE: You should remove any installations of base Playwright from your repo. Otherwise you may encounter an error around "requiring @playwright/test a second time".


npm install --save-dev @guardianui/test


yarn add --dev @guardianui/test

Playwright Browsers

You will need to have the latest Playwright browser drivers installed.

npx playwright install

Configuring the Framework

Playwright Config

At your repo's top-level directory create a file called playwright.config.ts.

If you already are using Playwright and already have a playwright.config.ts:

  • Add /.*gui\.(js|ts|mjs)/ to the testMatch entry to make sure Playwright recognizes our tests

    • If you do not have a testMatch entry in the config, add one like shown in the example below

    • If you have existing Playwright tests that are either named with the testName.spec.ts or testName.test.ts naming conventions make the following your testMatch entry: [/.*gui\.(js|ts|mjs)/, /.*(spec|test)\.(js|ts|mjs)/]

  • Set fullyParallel to false

  • Set workers to 1

import { devices, PlaywrightTestConfig } from '@playwright/test';

 * See
const config: PlaywrightTestConfig = {
  // globalSetup: require.resolve('./globalSetup'),
  testDir: './tests',
  testMatch: [/.*gui\.(js|ts|mjs)/],
  /* Maximum time one test can run for. */
  timeout: 90 * 1000,
  expect: {
     * Maximum time expect() should wait for the condition to be met.
     * For example in `await expect(locator).toHaveText();`
    timeout: 5000
  /* Run tests in files in parallel */
  fullyParallel: false,
  /* Fail the build on CI if you accidentally left test.only in the source code. */
  forbidOnly: !!process.env.CI,
  /* Retry on CI only */
  retries: process.env.CI ? 2 : 0,
  /* Opt out of parallel tests on CI. */
  workers: 1,
  /* Reporter to use. See */
  reporter: [["html", { open: "never" }]],
  /* Shared settings for all the projects below. See */
  use: {
    // launchOptions: {
    //   slowMo: 1500,
    // },
    userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/ Safari/537.36",
    headless: true,
    /* Maximum time each action such as `click()` can take. Defaults to 0 (no limit). */
    actionTimeout: 0,
    /* Base URL to use in actions like `await page.goto('/')`. */
    // baseURL: 'http://localhost:3000',

    /* Collect trace when retrying the failed test. See */
    trace: 'on-first-retry',

  /* Configure projects for major browsers */
  projects: [
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
        launchOptions: {
          args: ['--disable-web-security'],

      name: 'firefox',
      use: {
        ...devices['Desktop Firefox'],

      name: 'webkit',
      use: {
        ...devices['Desktop Safari'],

    /* Test against mobile viewports. */
    // {
    //   name: 'Mobile Chrome',
    //   use: {
    //     ...devices['Pixel 5'],
    //   },
    // },
    // {
    //   name: 'Mobile Safari',
    //   use: {
    //     ...devices['iPhone 12'],
    //   },
    // },

    /* Test against branded browsers. */
    // {
    //   name: 'Microsoft Edge',
    //   use: {
    //     channel: 'msedge',
    //   },
    // },
    // {
    //   name: 'Google Chrome',
    //   use: {
    //     channel: 'chrome',
    //   },
    // },

  /* Folder for test artifacts such as screenshots, videos, traces, etc. */
  // outputDir: 'test-results/',

  /* Run your local dev server before starting the tests */
  // webServer: {},

export default config;


At your repo's top-level directory create another file called .env or if you already have one add the following to your existing .env. Comment out whichever line you do not use with a # at the start.

# Must fill in one of these API keys, do not need both


To be able to run tests, add the following to your app's package.json scripts section:

"test:gui": "npx playwright test --project=chromium --headed"

To run tests headless, use the following for your app's package.json scripts section instead:

"test:gui": "npx playwright test --project=chromium"

Tests Folder

Create a folder called tests to house your GuardianTest tests within.

Last updated