Heads up, we are working on a new BigTest.

The information on this page referes to the BigTest 1.x series. Please refer to the new BigTest website for updated documentation.

Quick Start

This guide will get you up and running with BigTest in a React application. By the end you will have all of the BigTest structure setup and one passing test! We highly recommend reading the introduction before getting started. It briefly explains the different parts that make up BigTest and how they work.

At a high level we're going to cover:

This guide assumes your application is using the following technologies:

Installing Dependencies

First, install the packages you'll to need to BigTest:

 yarn add --dev @bigtest/cli @bigtest/interactor @bigtest/react

Initializing BigTest

Now that all of the dependencies are installed go to your project root and run npx bigtest init. This will create a new bigtest directory:

├── bigtest.opts
├── index.js
├── helpers/
│   └── setup-app.js
├── interactors/
│   └── app.js
└── tests/
    └── app-test.js

Importing your App

You need to import the applications root component into the bigtest/helpers/setup-app.js file. Importing your root component will look something like this:

import { setupAppForTesting } from '@bigtest/react';

// Import your applications root.
// This is typically what you pass to ReactDOM.render
import YourApp from '../../src/YourApp';

export async function setupApplicationForTesting() {
  await setupAppForTesting(YourApp, {
    mountId: 'bigtesting-container'

Launch and Serve

BigTest works by bundling your app with the test files that you have written. Any tests that are created will need to be imported to bigtest/index.js. You need to tell your bundler how to bundle the tests with the app by changing your bundler's entry point to bigtest/index.js.

The bigtest CLI sets the NODE_ENV to test for you. With Webpack for example, you can check to see if the NODE_ENV is equal to test and change the entry point as needed:

// in your webpack.config.js
let isTesting = process.env.NODE_ENV === 'test';

module.exports = {
  entry: isTesting ? '.bigtest/index.js' : './src/index.js'

bigtest run

bigtest run handles launching different browsers and actually running the tests. Add a script to your package.json:

// ..
"scripts": {
  "test": "bigtest run"

This is so we're using the projects version of @bigtest/cli that is specified in the package.json and not a global install.


The bigtest.opts file lets the launcher (bigtest run) know:

The bigtest.opts file is a configuration file for the different options you can pass as flags to the BigTest CLI. Arguments passed from the CLI take precedence over what is specified in the opts file.

Your bigtest.opts should look something like this:

--serve "yarn start"
--serve-url "http://localhost:3000"
--adapter mocha

Run the tests!

Now that everything is setup, if your applications root URL has an h1 element (it should!), you will have a passing test. You can check by running the test command we setup earlier:

yarn test

It should look something like this:

Gif of BigTest running