Jest Page Tester

Extends Jest with functionality for loading real pages into jsdom.

Intended for cases where we want to run integration tests against real pages without dealing with all the implicit flakiness of running those tests in real browsers.

Installation

# npm
npm install jest-page-tester -D

# yarn
yarn add jest-page-tester -D

Setup

Add the jest-page-tester preset to your Jest config, as follows:

// jest.config.js
module.exports = {
  testEnvironment: 'jest-page-tester',
}

Usage

The following functions will be made available to your tests via the global page object.

page.loadPage()

Load a page into the DOM.

it('renders the page title', async () => {
  await page.loadPage('/my/page');

  const title = document.querySelector('h1');

  expect(title).toBe('My Page');
});

page.loadScripts()

Load external scripts (which will not be loaded by default).

it('runs the external script', async () => {
  await page.loadPage('/my/page');
  await page.loadScripts();

  // ...
});

Configuration

Jest page tester can be configured by adding a jest-page-tester.config.js file to the root of your repo, or by adding a jest-page-tester property to your package.json file.

The available options are documented below.

testURL

The base URL against which to run the tests (will be overwritten by the --testURL CLI arg).

// jest-page-tester.config.js
module.exports = {
  testURL: 'http://example.com',
}

block

A list regular expressions used to block the loading of external resources.

// jest-page-tester.config.js
const fetch = require('node-fetch');

module.exports = {
  block: [
    'www.googletagmanager.com',
    'ads.com',
  ],
};

fetch

Override the default fetch function used for requesting resources. Useful if we want to purge an edge cache each time we load a page, for example.

// jest-page-tester.config.js
const fetch = require('node-fetch');

module.exports = {
  fetch: async (url, opts) => {
    await fetch(url, { method: 'PURGE' });

    return fetch(url, opts);
  },
};

externalLogLevel

The level of messages to log when evaluating external resources (e.g. scripts). The default is to log no messages.

// jest-page-tester.config.js
module.exports = {
  externalLogLevel: 'error',
};

Cookies

Any cookies present in the document will be sent along with the request to load the page, for example:

it('sends cookies with the page request', () => {
  document.cookie = 'token=abc123;';

  await page.loadPage('/page');

  const signInThingy = document.querySelector('#signed-in');

  expect(signInThingy.textContent).toBe('Signed in cookie existed');
});

Similarly, if the response received when loading a page includes any Set-Cookie headers these will be loaded into the local DOM.

ESLint

Configure ESLint by adding the page global, as follows:

{
  "globals": {
    "page": "readonly"
  },
}