@telefonica/acceptance-testing

Setup

1. Install jest-environment-puppeteer and @telefonica/acceptance-testing packages

yarn add --dev jest-environment-puppeteer @telefonica/acceptance-testing

2. Setup jest-environment-puppeteer in your jest.acceptance.config.js

module.exports = {
  //...
  globalSetup: 'jest-environment-puppeteer/setup',
  globalTeardown: 'jest-environment-puppeteer/teardown',
  testEnvironment: 'jest-environment-puppeteer',
  //...
};

3. Create a jest-puppeteer.config.js file in your repo

const config = require('@telefonica/acceptance-testing/jest-puppeteer-config.js');
module.exports = config;

This will make your tests to run inside a dockerized chromium when they run headless or in CI, and they will run in a local chromium (the one provided by puppeteer) when you run them with UI, for example while debugging.

If you want to autostart a server before running the acceptance tests, you can configure it in your project package.json like follows:

{
  "acceptanceTests": {
    "devServer": {
      // This is the command that starts your dev server and the port where it runs
      "command": "yarn dev",
      "port": 3000
    },
    "ciServer": {
      // The same for CI server (tipically a production build)
      "command": "yarn start",
      "port": 3000
    }
  }
}

Additionally, you can include path and protocol parameters, that will be used to check if the server is ready:

{
  "acceptanceTests": {
    "ciServer": {
      "command": "yarn dev",
      "port": 3000,
      "path": "api/health",
      "protocol": "https"
    }
  }
}

protocol

Type: string, (https, http, tcp, socket) defaults to tcp or http if path is set.

To wait for an HTTP or TCP endpoint before considering the server running, include http or tcp as a protocol. Must be used in conjunction with port.

path

Type: string, default to null.

Path to resource to wait for activity on before considering the server running. Must be used in conjunction with host and port.

4. Setup your CI to run using the web-builder docker image

Github actions example:

jobs:
  build:
    runs-on: self-hosted-novum
    container: docker.tuenti.io/service-inf/web-builder:pptr10.4-1.0.0

Important: you must use the same docker image version and remember to update it in your CI config if you update the @telefonica/acceptance-testing package. This is the best way to make sure CI uses the same dockerized chromium version that the developers use in their laptops. Otherwise the screenshot tests snapshots may not match.

Writing acceptance/screenshot tests

import {openPage, screen, serverHostName} from '@telefonica/acceptance-testing';

test('example screenshot test', async () => {
  const page = await openPage({path: '/foo'});

  await screen.findByText('Some text in the page');

  expect(await page.screenshot()).toMatchImageSnapshot();
});

Running acceptance/screenshot tests

Just run:

yarn test-acceptance

or with ui:

yarn test-acceptance --ui

Important: test-acceptance script needs a valid jest.acceptance.config.js file in your repo to work. That file should be configured with jest-environment-puppeteer as described previously. If for some reason you need a different jest config file name you can manually setup some scripts in your package.json:

"test-acceptance": "HEADLESS=1 jest --config your-jest-config.js",
"test-acceptance-ui": "jest --config your-jest-config.js",

Just take into account that the jest-environment-puppeteer must always be configured in your jest config file. Also note that tests run in UI mode by default, unless you set the HEADLESS=1 env var.

Intercepting requests

If you can intercept and mock requests in your acceptance tests you can use the interceptRequest function:

import {openPage, screen, interceptRequest} from '@telefonica/acceptance-testing';

test('example screenshot test', async () => {
  const imageSpy = interceptRequest((req) => req.url().endsWith('.jpg'));

  imageSpy.mockReturnValue({
    status: 200,
    contentType: 'image/jpeg',
    body: myMockedJpeg,
  });

  const page = await openPage({path: '/foo'});

  expect(imageSpy).toHaveBeenCalled();
});

To mock JSON api endpoints you can use interceptRequest too, but we also provide a more convenient api wrapper over interceptRequest: createApiEndpointMock

import {openPage, screen, createApiEndpointMock} from '@telefonica/acceptance-testing';

test('example screenshot test', async () => {
  const api = createApiEndpointMock({origin: 'https://my-api-endpoint.com'});

  const getSpy = api.spyOn('/some-path').mockReturnValue({a: 1, b: 2});
  const postSpy = api.spyOn('/other-path', 'POST').mockReturnValue({c: 3});

  const page = await openPage({path: '/foo'});

  expect(getSpy).toHaveBeenCalled();

  await page.click(await screen.findByRole('button', {name: 'Send'}));

  expect(postSpy).toHaveBeenCalled();
});

By default every mocked response will have a 200 status code. If you want to mock any other status code:

import {openPage, screen, createApiEndpointMock} from '@telefonica/acceptance-testing';

test('example screenshot test', async () => {
  const api = createApiEndpointMock({origin: 'https://my-api-endpoint.com'});

  const postSpy = api
    .spyOn('/other-path', 'POST')
    .mockReturnValue({status: 500, body: {message: 'Internal error'}});

  const page = await openPage({path: '/foo'});

  await page.click(await screen.findByRole('button', {name: 'Send'}));

  expect(postSpy).toHaveBeenCalled();
});

createApiEndpointMock automatically mocks CORS response headers and preflight (OPTIONS) requests for you.

Using globs

You can also use globs for API paths and origins if you need.

Some examples:

// any origin (default)
createApiEndpointMock({origin: '*'});

// any port
createApiEndpointMock({origin: 'https://example.com:*'});

// any domain
createApiEndpointMock({origin: 'https://*:3000'});

// any subdomain
createApiEndpointMock({origin: 'https://*.example.com:3000'});

// any second level path
api.spyOn('/some/*/path');

// accept any params
api.spyOn('/some/path?*');

// accept any value in specific param
api.spyOn('/some/path?param=*');

ℹ️ We use the glob-to-regexp lib internally.

⚠️ Headless acceptance tests run in a dockerized chromium, so you can't use localhost as origin. The origin will depend on the docker configuration and host OS. For simplicity, we recommend to use * as origin for tests that mock local APIs (eg. Next.js apps).

Uploading files

Due to a puppeteer bug or limitation, when the chromium is dockerized, the file to upload must exist in the host and the container with the same path.

A helper function prepareFile is provided to facilitate this:

await elementHandle.uploadFile(prepareFile('/path/to/file'));

Collecting coverage

This library automatically collects code coverage after each test by reading the window.__coverage__ object if available.

To create that object you should instrument the code with an istanbul compatible tool (for example babel-plugin-istanbul).

The coverage report for each test will be saved as json files. To change the destination folder, set the coveragePath property in your config. The default value is reports/coverage-acceptance.

Example config:

{
  "acceptanceTests": {
    "coveragePath": "coverage/acceptance"
  }
}

After running the tests, you can use a tool like nyc to generate the coverage summaries.

Troubleshooting

If you see an acceptance test failing without any apparent reason, it could be caused by an unhandled error in the browser. You can inspect it by adding a listener to the pageerror event:

page.on('pageerror', (err) => {
  console.log('Unhandled browser error:', err);
  process.emit('uncaughtException', err);
});