Repository files navigation

It's more flexible, lightweight, optimized for Playwright, and has TypeScript support out of the box. This doesn't mean, that we stop with maintaining this package.

Running your tests usingJest &Playwright

npm install -D jest jest-playwright-preset playwright

Also you can usejest-playwright-preset with specific playwright packages:playwright-webkit,playwright-chromium andplaywright-firefox

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

• Node.js 14+
• Playwright 1.2.0+
• Jest 28+

Update your Jest configuration, either:

withpackage.json:

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

or withjest.config.js:

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

And add the Jest command as in the script section of yourpackage.json:

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

Now you can use Playwright in your tests:

// example.test.jsbeforeAll(async()=>{awaitpage.goto('https://whatismybrowser.com/')})test('should display correct browser',async()=>{constbrowser=awaitpage.$eval('.string-major',(el)=>el.innerHTML)expect(browser).toContain('Chrome')})

playwright actions can take some time for execution, because of itjest-playwright overrides jest default timeout interval from 5 to 15 seconds.You can change this interval withtestTimeout in yourjest configuration.

It's recommend to use a separate Jest configurationjest.e2e.config.js forjest-playwright to gain speed improvements and by that to only use Playwright in the end-to-end tests. For that you have to use the-c flag when calling Jest and use thetestMatch ortestRegex in your Jest config to split them.

Be sure to remove any existingtestEnvironment option from your Jest configuration. Thejest-playwright-preset preset needs to manage that option itself.

Configuration options can be specified using ajest-playwright.config.js file at the root of your project:

// jest-playwright.config.jsmodule.exports={// Options...}

Similar to JestglobalSetup configuration can except the export of an async function:

module.exports=async()=>{await ...};

A custom path can be specified to thejest-playwright.config.js file within yourjest.config.js file:

process.env.JEST_PLAYWRIGHT_CONFIG='/path/to/jest-playwright.config.js'

Alternatively, configuration options can specified using Jest's owntestEnvironmentOptions option within yourjest.config.js file:

// jest.config.jsmodule.exports={preset:'jest-playwright-preset',testEnvironmentOptions:{'jest-playwright':{// Options...},},}

• launchOptions <[object]>.All Playwright launch options can be specified in config. Since it is JavaScript, you can use all stuff you need, including environment.
• launchType <LAUNCH |PERSISTENT |SERVER>. Method to launch browser instance.jest-playwright attaches Playwright to an existing browser instance by default.
• connectOptions <[object]>.All Playwright connect options can be specified in config.
• contextOptions <[object]>.All Playwright context options can be specified in config.
• browsers <[(string | object)[]]>. Definebrowsers to run tests in.
  • chromium Each test runs Chromium (default).
  • firefox Each test runs Firefox.
  • webkit Each test runs Webkit.
• devices <[(string | object)[] | RegExp]>. Define adevices to run tests in. Actual list of devices can be foundhere.
• exitOnPageError <[boolean]>. Exits process on any page error. Defaults totrue.
• collectCoverage <[boolean]>. Enables the coverage collection of thesaveCoverage(page) calls to the.nyc_output/coverage.json file.
• serverOptions <[object]>.Alljest-process-manager options.
• selectors <[array]>. Defineselectors. Each selector must be an object with name and script properties.
• skipInitialization <[boolean]>. Add you ability to skip first setupplaywright process. Possible use cases can be foundhere
• resetContextPerTest <[boolean]>. Option for opening a new context per test
• useDefaultBrowserType <[boolean]>.Sometimesbrowser +device combinations don't have any sense. With this option tests will be run withdefaultBrowserType of device. Pay attention that you should definedevices to correct usage of this option.

You can control the browser with passing environment variable.

// jest-playwright.config.jsmodule.exports={browsers:[process.env.BROWSER],}

ForlaunchOptions,connectOptions andcontextOptions you can define special browser options.

// jest-playwright.config.jsmodule.exports={connectOptions:{chromium:{wsEndpoint:'ws://chrome.proxy.com:4444'},firefox:{wsEndpoint:'ws://firefox.proxy.com:4444'}},  ...}

There are different ways to define devices in your configuration file:

• You can use array of browser names:

module.exports={browsers:["chromium","webkit"],  ...}

• You can define custom browser. You can find out use caseshere:

{// Name of browser  name:'chromium'|'firefox'|'webkit'// Display name for test  displayName:string...// Browser options}

There are different ways to define devices in your configuration file:

• You can use array of device names:

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

• You can useRegExp:

module.exports={devices:/iPhone8/,  ...}

• Also you can define custom device:

{// Name of device  name:string// Page width and height  viewport:{    width:number    height:number}// user agent  userAgent:string// device scale factor  deviceScaleFactor:number// is device is mobile  isMobile:boolean// support of touch events  hasTouch:boolean// device default browser  defaultBrowserType:chromium,firefoxorwebkit}

• browserName <[string]> - name of the current browser (chromium, firefox or webkit)
• deviceName <[string]> - name of the current device
• browser <[Browser]> - Playwright browser instance
• context <[Context]> - a new Playwright context instance for each new test file
• page <[Page]> - Playwright page instance (since a new context for every test file also creates a new page for it)

All of them are available globally in each Jest test. If you are using ESLint and JavaScript, its recommend to use it in combination with theeslint-plugin-jest-playwright.

Playwright give youability to configure the browser for debugging with thePWDEBUG environment variable. It will launch the browser in headful mode, disables playwright timeout andJest won't timeout anymore.:

PWDEBUG=1jest

beforeEach(async()=>{awaitjestPlaywright.resetPage()})

To create a new page for each test, you can use this snippet to have a new page object for each individual test.

beforeEach(async()=>{awaitjestPlaywright.resetContext()})

To create a new context for each test, you can use this snippet to have a new context object for each individual test.

beforeEach(async()=>{awaitjestPlaywright.resetBrowser()})

You can use this snippet to reset current browser for each individual test. It will reset browser, context and page.

jest-playwright provides some functions to debug your tests.

IMPORTANT NOTE: For these kind of tests you should use properties passed through callback function instead ofglobals

This helper function provide you ability to run specific tests indebug mode. It will disableheadless mode.You can find more informationhere

test.jestPlaywrightDebug('failed',async({ page})=>{awaitpage.goto('https://github.com/')consttitle=awaitpage.title()awaitexpect(title).toBe('Google')})

Also you can define options fordebug mode withdebugOptions:

// jest-playwright.config.jsmodule.exports={debugOptions:{    ...contextOptions:{offline:true}}...}

This helper function provide you ability to run specific tests with passed options.You can definebrowser anddevice properties to run test for them, otherwise test run for current configuration.

test.jestPlaywrightConfig({// your jest-playwright options},'test name',async({ browser, context, page})=>{/* ... */},)

It's possible to track the coverage of the end-to-end tests with thebabel-plugin-istanbul Babel plugin configured. It needs to be included in the web application which you are gonna test otherwise it won't work. To use it, you have to setcollectCoverage in thejest-playwright.config.js totrue. Per default the test coverage will be automatically saved after each navigation change (beforeunload event). If a certain code path is not covered, you can manually call and add the correspondingsaveCoverage(page) call to your tests like that:

awaitjestPlaywright.saveCoverage(page)

By using coverage collection, it will write the coverage data to the.nyc_output/coverage.json file which can be transformed usingnyc to the lcov format:

npx nyc report --reporter=lcovonly

or to HTML:

npx nyc report --reporter=html

which will create a HTML website in thecoverage directory.

It's possible to skip tests for browsers or combination of browsers and devices

it.jestPlaywrightSkip({browsers:['chromium']},'should skip this one',async()=>{consttitle=awaitpage.title()expect(title).toBe('Google')},)

Playwright engine pierces open shadow DOM bydefault.

beforeAll(async()=>{awaitpage.goto('https://mdn.github.io/web-components-examples/popup-info-box-web-component/',)})test('should display "google" text on page',async()=>{constshadowElem=awaitpage.$('.info')constshadowElemText=awaitshadowElem.innerHTML()expect(shadowElemText).toBe('Your card validation code (CVC) is an extra security feature — it is the last 3 or 4 numbers on the back of your card.',)})

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

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

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

Other options are documented injest-process-manager.

The defaultjest-playwright environment isnode, but you can use a browser-like environment throughjest-playwright-jsdom

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

There is an ESLint plugin availableeslint-plugin-jest-playwright available which includes the globals for using jest-playwright.

You can run tests for multiple browsers and devices:

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

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

It will run your tests for:

• Chromium browser andiPhone 6 device;
• Chromium browser andPixel 2 device;
• Webkit browser andiPhone 6 device;
• Webkit browser andPixel 2 device;

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

You can usejest-playwright with custom test environment for taking screenshots during test failures for example:

jest.config.json

"testEnvironment":"./CustomEnvironment.js"

CustomEnvironment.js

constPlaywrightEnvironment=require('jest-playwright-preset/lib/PlaywrightEnvironment').defaultclassCustomEnvironmentextendsPlaywrightEnvironment{asyncsetup(){awaitsuper.setup()// Your setup}asyncteardown(){// Your teardownawaitsuper.teardown()}asynchandleTestEvent(event){awaitsuper.handleTestEvent(event)if(event.name==='test_done'&&event.test.errors.length>0){constparentName=event.test.parent.name.replace(/\W/g,'-')constspecName=event.test.name.replace(/\W/g,'-')awaitthis.global.page.screenshot({path:`screenshots/${parentName}_${specName}.png`,})}}}module.exports=CustomEnvironment

jest-playwright using custom runner underhood. So if you need implement your ownrunner, you should extend it:

jest.config.json

"runner":"./CustomRunner.js"

CustomRunner.js

constPlaywrightRunner=require('jest-playwright-preset/lib/PlaywrightRunner').defaultclassCustomRunnerextendsPlaywrightRunner{constructor(...args){super(...args)this.isSerial=true}}module.exports=CustomRunner

For this use case,jest-playwright-preset exposes two methods:globalSetup andglobalTeardown, so that you can wrap them with your own global setup and global teardown methods as the following example:

// global-setup.jsimport{globalSetupasplaywrightGlobalSetup}from'jest-playwright-preset'module.exports=asyncfunctionglobalSetup(globalConfig){awaitplaywrightGlobalSetup(globalConfig)constbrowserServer=awaitchromium.launchServer()constwsEndpoint=browserServer.wsEndpoint()constbrowser=awaitchromium.connect({wsEndpoint:wsEndpoint})constpage=awaitbrowser.newPage()// your login functionawaitdoLogin(page)// store authentication dataconststorage=awaitpage.context().storageState()process.env.STORAGE=JSON.stringify(storage)}

// global-teardown.jsimport{globalTeardownasplaywrightGlobalTeardown}from'jest-playwright-preset'module.exports=asyncfunctionglobalTeardown(globalConfig){// Your global teardownawaitplaywrightGlobalTeardown(globalConfig)}

Then assigning your js file paths to theglobalSetup andglobalTeardown property in your Jest configuration.

{// ..."globalSetup":"./global-setup.js","globalTeardown":"./global-teardown.js"}

Now your customglobalSetup andglobalTeardown will be triggered once before and after all test suites.

Example Jest configuration in combination withts-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 centraltsconfig.json either viafiles:

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

or viatypes:

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

It's important to not change thetestEnvironment tonode. Otherwise it won't work.

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.)

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.

Demonstration the usage ofjest-playwright for various test cases can be found inplaywright-jest-examples

Thanks toSmooth Code for the greatjest-puppeteer.

MIT