react-native-screenshot-test

The most straightforward UI testing library for react-native.

1. HeadLess mode

Can be used in Expo or react-native projects that can render on web using react-native-web. Your project will run in headless (no UI) mode and the server will capture screenshots.

Just wrap your UI component/widget inside withScreenshotTest. Then run the screenshot-test server. The tests will run and a report will be generated in test.html file.

Installation

npm i react-native-screenshot-test

---

2. Simulator/Device mode

Just wrap your UI component/widget inside withScreenshotTest and render it on your emulator/device.

The emulator will render your component/widget along with a button named Capture and Compare

Hit the button and the tests will run and a report will be generated in test.html file.

Installation

npm i react-native-screenshot-test react-native-view-shot react-native-fs

Rebuild and relaunch your app after installation.

---

Usage

1. In your project's package.json, under scripts, add-

"scripts": {
    ...
    ...
    "ss-test": "cd ./node_modules/screenshot-test-server/dist && node server.js true", // add this for headless mode

    // OR
    // to run the tests on simulator/device (in non-headless mode), add below line

    "ss-test": "cd ./node_modules/screenshot-test-server/dist && node server.js false" // add this for simulator/ device mode
}

Note The node server accepts 3 args-

1. isHeadLess // default true
2. uiUrl // default http://localhost:8081
3. serverPort // default 8080

2. Write your tests. Below is a sample test-

import Component1 from '/path-to-component-1';
import Component2 from '/path-to-component-2';
import { withScreenShotTest } from 'react-native-screenshot-test';

const App = () => {

    const testComponents = [
        {
            component: Component1,
            title: 'Component 1 details to be observed',
            id: 'c1',
        },
        {
            component: Component2,
            title: 'Component 2 details to be observed',
            id: 'c2',
        },
        ...
    ];

    const screenshotConfig = {
        /* properties path, localhostUrl, port, quality etc (all optional) */
    };

    const isHeadless = true / false

    return withScreenShotTest(testComponents, isHeadless, screenshotConfig);
}

3. In your projects root directory, run the below command(s)-

npx expo start -c // run this only in headless mode
npm run ss-test

This will start the test server. In headless mode, make sure to run npx expo start -c (for expo projects) or npm start (for rn projects runnable on web) before running npm run ss-test.

4. Render your test component in your simulator or device and press the "Capture and Compare" button. This step is needed only if you have NOT chosen the headless mode.

5. This will generate a folder named ss-test (or the path you provided in config) in your project's root directory.

6. Navigate to ss-test or (or the path you provided in config) folder and open the file named test.html in your browser.

Props

withScreenShotTest receives 3 parameters- Components array, isHeadless and ScreenshotConfig.

ScreenshotConfig is defined as-

interface ScreenshotConfig {
  path?: string; // path where screenshots should be saved, default: ss-test
  serverUrl?: string; // for web & iOS emulator it is http://127.0.0.1:8080, for Android emulator it is http://10.0.2.2:8080
  batchSize?: number; // number of tests to be processed at a time, default: 10
  maxWidth?: number; // maxWidth to be used in html while rendering the captured screenshot, default: 500
  backgroundColor?: string; // backgroundColor to be used in html while rendering the captured screenshot, default: transparent
  showDiffInGrayScale?: boolean; // show diff image in grayScale? default: false
  quality?: number; // quality (0 to 1) while capturing the screenshot, default: 0.9
}

Note: all these properties are optional. In fact the second parameter to withScreenShotTest is entirely optional. When omitted, the library assigns the default values to each property.

Components is an array where each item of the array has following properties-

interface Components {
  component: (props?: any) => ReactElement;
  title: string;
  id: string;
  description?: string;
  showDiffInGrayScale?: boolean;
  maxWidth?: number;
  backgroundColor?: string;
  quality?: number; // NOT used in headless mode
}

Note: only the first 3 properties- component, title and id are required, rest are optional.