1.4.2 • Public • Published


    Tests Jest preset plugin that allows you to run your tests against a Chromium instance running in Docker





    This plugin uses jest-puppeteer, an awesome plugin created by the developers at Smooth Code, for using Puppeteer in your tests. If you are not doing Visual Regression Testing, you may want to use that plugin directly instead.

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

    Note: You should set an environment variable PUPPETEER_SKIP_CHROMIUM_DOWNLOAD to true to avoid unnecessarily downloading a local copy of Chromium, since we will be using a container.

    Basic Usage


    module.exports = {
        preset: 'jest-puppeteer-docker'

    Use Puppeteer in your tests:

    describe('Google', () => {
        beforeAll(async () => {
            await page.goto('');
        it('should display "google" text on page', async () => {
            await expect(page).toMatch('google');

    Jest Puppeteer Config

    By default, Jest Puppeteer is configured by this library to connect to Chromium in the Docker container instead of launching it on the host machine. You may wish to add additional configuration, as per the puppeteer.connect options. You can add a jest-puppeteer.config.js in your package root, or reference a custom location by setting process.env.JEST_PUPPETEER_CONFIG.

    Additionally, you can pass in Chromium flags to modify your launch criteria by providing a chromiumFlags array as well as other Docker Chromium arguments.


    const getConfig = require('jest-puppeteer-docker/lib/config');
    const baseConfig = getConfig();
    const customConfig = Object.assign({}, baseConfig);
    customConfig.connect.defaultViewport = {
        width: 500,
        height: 500
    customConfig.chromiumFlags = ['–ignore-certificate-errors'];
    module.exports = customConfig;

    How it works

    jest-puppeteer-docker will pull down a Docker image with Chromium installed with the version matching the one associated with the Puppeteer dependency in your project.

    When you run your tests, the container is started and jest-puppeteer-docker will connect to the Chromium instance within the container via the Chrome Debugging Protocol. Your browser navigation and interactions will be performed in the container, while the test themselves are executed in your host environment.

    Once the tests finish running, the Docker container will automatically be shutdown.

    Accessing Host

    If you are running a web server on your host environment, you should be able to access it from the browser in the container at host.docker.internal.

    For example, if you have a server running at http://localhost:3000, you can do the following in your test:

    await page.goto('http://host.docker.internal:3000/my-page');

    If for any reason this doesn't work for you, check the Troubleshooting section, or create an issue.

    Visual Regression Testing

    📃 Blog post: Visual Regression Testing

    The main benefit of using Docker here is to support Visual Regression Testing. Without Docker, different environments may yield unexpected results with image comparisons, due to anti-aliasing techniques. By providing a containerized environment, we can guarantee that the images produced are always the same.

    Example Test

    jest-image-snapshot is a plugin that you can install, which will compare a screenshot with a baseline image that was previously generated when the test executed for the first time.

    it('should position the title and body correctly', async () => {
        const element = await$('.my-element');
        const image = await element.screenshot();

    Example Config

    Before tests execute, we can configure jest-image-snapshot globally with a threshold value, among other options, using the setupFilesAfterEnv hook provided by Jest.


    module.exports = {
        preset: 'jest-puppeteer-docker',
        setupFilesAfterEnv: ['./test-environment-setup.js']


    const { configureToMatchImageSnapshot } = require('jest-image-snapshot');
    const toMatchImageSnapshot = configureToMatchImageSnapshot({
        failureThreshold: '0.01',
        failureThresholdType: 'percent'
    expect.extend({ toMatchImageSnapshot });

    Example Result

    Example Result

    Advanced Config

    As per standard Jest configuration, we can provide a globalSetup and globalTeardown hook for doing tasks that need to happen before the test suite initializes (e.g. starting a server), and after it finishes (e.g. closing a server).

    module.exports = {
        preset: 'jest-puppeteer-docker',
        globalSetup: './setup.js',
        globalTeardown: './teardown.js',
        setupFilesAfterEnv: ['./test-environment-setup.js']


    const { setup: setupPuppeteer } = require('jest-puppeteer-docker');
    module.exports = async jestConfig => {
        // any stuff you need to do can go here
        await setupPuppeteer(jestConfig);


    const { teardown: teardownPuppeteer } = require('jest-puppeteer-docker');
    module.exports = async jestConfig => {
        await teardownPuppeteer(jestConfig);
        // any stuff you need to do can go here

    Check out the example in this repository for an end-to-end example with reporting.



    When configuring CircleCI, we need to enable the remote Docker engine to be able to run Docker Compose commands for building the Chrome container. This is achieved by adding the setup_remote_docker build step.

    However, the job that runs in the base container is on a separate environment from the remote Docker engine (for security reasons). This means the remote container cannot access network resources from the base container, and is a problem for us. You can read more about Running Docker commands.

    In order to get around this, we can use machine executor instead of the Docker one. This comes with Docker Compose installed, allowing us to interact with the container over the same network.

    Checkout the example CircleCI config. It's worth noting that we need to set the NVM environment variable for every task because it gets reset, which is rather annoying.

    If you have a better solution than this, please let me know as I don't know CircleCI very well.




    npm i jest-puppeteer-docker

    DownloadsWeekly Downloads






    Unpacked Size

    600 kB

    Total Files


    Last publish


    • gidztech