< Back to Blog Overview

Headless Testing with Puppeteer and Jest

Headless Testing with Puppeteer and Jest

Jest-Puppeteer is a package that provides Jest testing on browsers controlled with Puppeteer. This package is very useful if you are looking to run headless tests on Chrome, Firefox and other browsers compatible with Puppeteer.

Installing jest-puppeteer

To get started, install the jest-puppeteer package via npm or yarn:

npm install --save-dev jest-puppeteer puppeteer jest

Once you've installed the package, you will need to instruct Jest to use the package during your test run:

Add the following code to a file called jest.config.js

module.exports = {
  rootDir: '.',
  testTimeout: 20000,
  testMatch: [
  preset: 'jest-puppeteer'

Configuring jest-puppeteer

Before you can use jest-puppeteer with our browser service, you will need to add the configuration below in a file called jest-puppeteer.config.js :

module.exports = {
  connect: {
    browserWSEndpoint: 'wss://chrome.headlesstesting.com/?token=[TOKEN]'

With this configuration, Jest will run the tests you specified in your *.spec.js files with the connect option you specified in the jest-puppeteer.config.js file.

You can replace the chrome.headlesstesting.com with other endpoints such as:

  • wss://firefox.headlesstesting.com
  • wss://edge.headlesstesting.com
  • wss://chrome.headlesstesting.com

Run your first test with jest-puppeteer

To run your first test, you can create a simple test such as the example below:

describe('Google', () => {
  beforeAll(async () => {
    await page.goto('https://google.com')

  it('should display google text on page', async () => {
    await expect(page).toMatch('google')

This Jest Puppeteer Test will open a browser in our grid, navigate to Google and verify if the word Google appears on the page.

Running Headless Tests from your CI Server

Once you have a couple of tests, the next step is to run these in a CI (Continuous Integration) environment.
There are multiple advantages to using such a system:

  • You can schedule your tests to run at specific times or intervals
  • Run tests after every commit
  • Scalability and Sharing

Schedule Headless Tests

With most CI systems, you can indicate when you want to run your tests.
For example with Jenkins, you can set up a new Project, instruct Jenkins to pull the latest code from your repository and run the tests at a specific time.

You could run your tests every night at 1AM, run your tests every hour, or specify whichever interval you prefer.

If a test fails, you can have your CI send you an alert, through for example e-mail, Slack or another alert service.

Once you've set this up, you are guaranteed that your code is tested on regular intervals. If a bad code push introduces a test failure, you will be alerted and can resolve the potential bug from reaching your production environment.

Run Headless Tests after every commit

Another CI strategy is to set up a hook to run your tests after every commit.

You can configure your CI system to poll your git repository for changes.
Once the CI system detects a new commit, it can run all your headless tests and verify if the new code does not break your tests.

You can even take it a step further, and have your CI system merge your develop/staging branch into your master branch only when all tests pass.
This is a great way to make sure your master branch is always passing all tests, and is always ready for deployment to production.

Scalability and Sharing

Using a CI system in combination with our service provides for Scalability: you can run multiple tests at the same time and drastically shorten your total test duration.
Shortening your test duration is important, since it gives your developers early feedback in the quality of their code.

Each member of your team can access the CI system and examine test results. Our service also provides team accounts to make sharing your tests easy.

Advanced usage with Jest Puppeteer

Jest-Puppeteer provides several helpers and options to expand your test cases.
You can access anything via Puppeteer: the browser object, page(s), context and set debug options.


Headless Testing with Puppeteer and Jest works really well. In combination with our service, you can achieve full parallelism of your headless tests and keep everyone in your company happy.

HeadlessTesting Logo

Sign up for a Free Trial

Start Headless Testing instantly.

No credit card required!