Jest Playwright

Running your tests using Jest & Playwright

npm install -D jest jest-playwright-preset playwright

Also you can use jest-playwright-preset with specific playwright packages: playwright-webkit, playwright-chromium and playwright-firefox

npm install -D jest jest-playwright-preset playwright-firefox

Requirements

• Node.js >= 10.15.0
• Playwright >=0.12.1

Usage

Update your Jest configuration, either:

• with package.json:

"jest": {
  "preset": "jest-playwright-preset"
}

• with jest.config.js:

module.exports = {
    preset: "jest-playwright-preset",
    ...
}

NOTE: Be sure to remove any existing testEnvironment option from your Jest configuration. The jest-playwright-preset preset needs to manage that option itself.

Use Playwright in your tests:

• with package.json

{
  "scripts": {
    "test": "jest"
  }
}

describe('What is my browser', () => {
  beforeAll(async () => {
    await page.goto('https://whatismybrowser.com/')
  })

  it('should display "google" text on page', async () => {
    const browser = await page.$eval('.string-major', (el) => el.innerHTML)
    expect(browser).toContain('Chrome')
  })
})

Configuration

You can specify a jest-playwright.config.js at the root of the project or define a custom path using JEST_PLAYWRIGHT_CONFIG environment variable. It should export a config object.

• launchBrowserApp <[object]> All Playwright launch options can be specified in config. Since it is JavaScript, you can use all stuff you need, including environment.

• connectBrowserApp <[object]> All Playwright connect options can be specified in config.

• context <[object]> All Playwright context options can be specified in config.

• browsers <[string[]]>. Define a browsers to run tests into.

  • chromium Each test runs Chromium (default).
  • firefox Each test runs Firefox.
  • webkit Each test runs Webkit.

• devices <[string[]]>. Define a devices to run tests into. Actual list of devices can be found here

• exitOnPageError <[boolean]> Exits process on any page error. Defaults to true.

• server <[object]> All jest-dev-server options

• selectors <[array]>. Define selector. Each selector must be an object with name and script properties.

  Usage with query-selector-shadow-dom:

  jest-playwright.config.js:

const {
  selectorEngine,
} = require('query-selector-shadow-dom/plugins/playwright');

module.exports = {
  selectors: [
    {name: 'shadow', script: selectorEngine}
  ],
  ...
}

Note:

• You can also specify browser with BROWSER environment variable. You should do it only if you are using the whole playwright package.
• You can specify device with DEVICE environment variable.

Put in debug mode

Debugging tests can be hard sometimes and it is very useful to be able to pause tests in order to inspect the browser. Jest Playwright exposes a method jestPlaywright.debug() that suspends test execution and gives you opportunity to see what's going on in the browser.

await jestPlaywright.debug()

Start a server

Jest Playwright integrates a functionality to start a server when running your test suite, like jest-puppeteer. It automatically closes the server when tests are done.

To use it, specify a server section in your jest-playwright.config.js.

// jest-playwright.config.js
module.exports = {
  server: {
    command: 'node server.js',
    port: 4444,
  },
}

Other options are documented in jest-dev-server.

expect-playwright

There is a utility package expect-playwright which simplifies the expect statements in combination with Playwright to make e.g. shorter text comparisons.

ESLint globals / 'page' is not defined

There is eslint-plugin-jest-playwright available which includes the globals for using jest-playwright.

Unstable and experimental API

You can run tests for multiple browsers and devices:

• You must have installed playwright package
• You must define browsers to test with your jest-playwright.config.js:

module.exports = {
    browsers: ["chromium", "webkit"],
    devices: ["iPhone 6", "Pixel 2"],
    ...
}

It will run your tests for:

• Chromium browser and iPhone 6 device;
• Chromium browser and Pixel 2 device;
• Webkit browser and iPhone 6 device;
• Webkit browser and Pixel 2 device;

If there is no defined browsers in config it will run tests for chromium browser.

Usage with jest-circus

You can use jest-playwright with jest-circus runner for taking screenshots during test failures for example:

jest.config.json

"testRunner": "jest-circus/runner",
"testEnvironment": "./CustomEnvironment.js"

CustomEnvironment.js

const PlaywrightEnvironment = require('jest-playwright-preset/lib/PlaywrightEnvironment')
  .default

class CustomEnvironment extends PlaywrightEnvironment {
  async setup() {
    await super.setup()
    // Your setup
  }

  async teardown() {
    // Your teardown
    await super.teardown()
  }

  async handleTestEvent(event) {
    if (event.name === 'test_done' && event.test.errors.length > 0) {
      const parentName = event.test.parent.name.replace(/\W/g, '-')
      const specName = event.test.name.replace(/\W/g, '-')

      await this.global.page.screenshot({
        path: `screenshots/${parentName}_${specName}.png`,
      })
    }
  }
}

module.exports = CustomEnvironment

Usage with Typescript

Example Jest configuration in combination with ts-jest:

module.exports = {
  preset: 'jest-playwright-preset',
  transform: {
    '^.+\\.ts$': 'ts-jest',
  },
}

Types are also available, which you can either use via directly in your test:

/// <reference types="jest-playwright-preset" />
/// <reference types="expect-playwright" />

or at your central tsconfig.json either via files:

{
  "files": [
    "./global.d.ts",
    "node_modules/jest-playwright-preset/types/global.d.ts",
    "node_modules/expect-playwright/global.d.ts"
  ]
}

or via types:

{
  "compilerOptions": {
    "types": ["jest-playwright-preset", "expect-playwright"]
  }
}

It's important to not change the testEnvironment to node. Otherwise it won't work.

Known issues

Error reporting with Jest

If you face into error messages like UnhandledPromiseRejectionWarning: Error: Protocol error (Runtime.callFunctionOn): Target closed. or

Timeout - Async callback was not invoked within the 20000ms timeout specified by jest.setTimeout.Timeout - Async callback was not invoked within the 20000ms timeout specified by jest.setTimeout.Error:

and your Jest error reporting will only show that an entire test (it() function) has failed, then you need to increase the Jest timeout because the Playwright timeout is greater than the Jest timeout. So Jest in the end will simply stop the execution and no verbose (which exact line) error reporting can be generated.

To fix this behavior simply call

jest.setTimeout(35 * 1000)

in your tests at the top. (30 seconds is the default Playwright timeout for waiting for an specific element.)

New Browser instance for each test

If for your individual tests a new entire browser instance spins up each time and it won't be reused, then you probably run them in parallel. If you run them in a synchronous way with the --runInBand CLI option for Jest, then the same browser instance will be re-used and this should fix the issue.

Inspiration

Thanks to Smooth Code for great jest-puppeteer.

License

MIT