Skip to content

01 Installation

Jump to bottom
Łukasz Makuch edited this page Mar 30, 2023 · 5 revisions

The neccessary software

Frontend testing tools are written in Node.js and distributed as an npm package.

This is how you install frontend testing tools and most of its peer dependencies:

npm i frontend-testing-tools jest endpoint-imposter

It requires the following pieces of software to be installed:

Prearing your app for being tested

All you have to do to prepare your app for being testing is to add a couple of lines of code.

Most apps require some test-specific setup, such as mocking out the API or the current time. Settings this up isn't instant. That's why to make your tests stable we kindly ask you to configure your app so that when the string frontend-testing-tools occurs in the User-Agent your app isn't instantialized until the window._testContinueRendering function is called. It'll be called by the frontend testing utils once all the problematic moving pieces are swapped for stable mocks.

Here's how this part of the setup may be done in React:

// This functions does the initial render:
window._testContinueRendering = () => root.render(toRender);
// This part is responsible for immediately rendering the app if it's not being controlled by frontend-testing-utils.
if (!/frontend-testing-tools/.test(navigator.userAgent))
  window._testContinueRendering();

If your app makes HTTP requests, you may want to expose a function that will be used by the frontend testing tools to instruct your app to communicate with Endpoint Imposter instead of the real backend:

// The name must be exactly that:
window._testSetHttpApiUrl = function (url) {
  // In the body of this function,
  // do whatever is needed to change the
  // address of the API your app communicates with.
  // For example change some global variable
  // representing the root URL of the API.
  window.API_ROOT = url;
};

Depending on how you create production builds, you may consider stripping this test-specific setup code out in your production builds. But it's not necessary, unless your users use browsers that identify themselves as "frontend-testing-utils"

Setting up Jest

To use these tools, you'll need to set up Jest to use the configuration files attached to this npm package:

In your frontend-tests/jest.config.js write:

const { defaults } = require("jest-config");

module.exports = {
  ...defaults,
  testEnvironment:
    "../node_modules/frontend-testing-tools/src/jestEnvironment.js",
  setupFilesAfterEnv: [
    "../node_modules/frontend-testing-tools/src/setupFilesAfterEnv.js",
  ],
  globalSetup: "../node_modules/frontend-testing-tools/src/globalSetup.js",
  globalTeardown:
    "../node_modules/frontend-testing-tools/src/globalTeardown.js",
};

Then don't forget to instruct Jest to use this config file as described below.

The "test" command

{
  "scripts": {
    "test": "APP_ROOT_URL=http://localhost:3000/ jest -c frontend-tests/jest.config.js"
  }
}

Optional configuration

You can specify project-relevant options in the package.json file:

  "frontend-testing-tools": {
    "screenshot": {
      "deviceMetrics": {
        "width": 1024,
        "height": 576,
        "deviceScaleFactor": 2,
        "mobile": false
      }
    }
  }

A complete list of available parameters, their descriptions and default values can be found in the defaultConfig.js file.

You can also override these values for each test case through the config module.

Environmental variables

Some options depend on the current environment, that is the machine the tests are running on, and not on the project itself. You specify them as environmental variables.

Here's a list of environmental variables you can use:

  • APP_ROOT_URL where the app under test is running, like "http://localhost:3000"
  • SCREENSHOT_DEVICE_TYPE overrides the destination folder of screenshots, such as "mac_x2" or "linux_x1"
Clone this wiki locally