Get started with Meticulous

Meticulous is a tool for software engineers to easily create end-to-end tests. Use the Meticulous open source CLI to open an instrumented browser which records your actions and translates them into a visual regression test.

Meticulous records network calls at record-time and automatically mocks out all network calls at simulation time, meaning you don't need a backend environment to simulate against or to implement a mechanism for resetting state after executing a test that mutates state. It also means you don't need to worry about any mocks. You can switch this network mocking off if you wish to hit a backend environment.

There are four steps to get started with Meticulous and create your first test, which we go through below. This takes four to six minutes.

1. Install Meticulous

  • Sign up at You will be prompted to create an organization and project.
  • Add the Meticulous CLI to your project, using one of the following two commands:

Install Meticulous


npm install --save-dev @alwaysmeticulous/cli @alwaysmeticulous/replayer @alwaysmeticulous/record


yarn add --dev @alwaysmeticulous/cli @alwaysmeticulous/replayer @alwaysmeticulous/record

2. Run Meticulous bootstrap.

Run the bootstrap command:

Meticulous Bootstrap


npx meticulous bootstrap


yarn meticulous bootstrap

This will create an empty meticulous.json file and add a command to the package.json file which looks like this:

"test:meticulous": "meticulous run-all-tests --headless --parallelize"

Once we've created our Meticulous tests, you will now be able to execute them with npm run test:meticulous or yarn run test:meticulous

3. Create a test.

You can watch a demo of how to create a test here or follow the instructions below.

  • You can get your API token from your project page in Meticulous.

  • You can create a test with Meticulous by running the following command:

Create tests


npx meticulous create-test --apiToken="<API_TOKEN>"


yarn meticulous create-test --apiToken="<API_TOKEN>"
  • This will open up a web browser with a blank page. You can now navigate to the site which you want to record a test on. This could be your production URL, or localhost.
  • Your interactions with the site will be recorded. Go through the flow that you wish to record.
  • Once you are finished close the browser. Do not exit the command.
  • Meticulous will now validate the test and simulate the recorded sequence of actions in a headless browser.
  • Meticulous will take a screenshot at the end of this simulation, which forms the basis of the test.
  • Click on the links printed out in the terminal to verify that the screenshot matches your expectations.
  • Save the test to your meticulous.json file by answering 'Y' on the prompt.

A Meticulous test is defined by three pieces of data, which our create-test command added to meticulous.json. If you open meticulous.json, you'll find the three pieces of data:

  1. A title to describe the test.

  2. An ID of a recorded session. This session contains the sequence of actions which will be simulated on the new version of code.

  3. The ID of the baseline simulation. This is the baseline simulation which will be diffed against.

The create-test command handled the creation of the recording and simulation.

Congratulations! You've created your first test and this can be integrated into CI. Now let's try running our test.

3. Execute a Meticulous test.

We will now execute this test using the test:meticulous command added earlier. This executes the run-all-tests command, which reads from the meticulous.json file.

You can execute the command below:

Run All Tests


npm run test:meticulous --apiToken=<API_TOKEN>


yarn run test:meticulous --apiToken=<API_TOKEN>

This command opens a browser in headless mode and simulates the recorded sequence of actions against a URL. By default, this URL is the starting URL that was captured when you recorded a test. There is a option to specify a URL to execute the test against. For instance, maybe you created a test by recording on localhost but want to execute the test against a preview URL or staging.

A screenshot is taken at the end of the simulation. This is diffed against the baseline screenshot of the baseline simulation. This command prints out a link to the test execution, where you can update the tests (if the change is expected) or inspect the visual differences.

You can execute this command in your CI, and test against a URL of your choice, such as a preview URL or localhost. Learn more about integrating Meticulous into CI in Setting up GitHub actions.

There are many important command-line options, which you can learn about by appending the --help flag to a command. If you want a deeper look, check out our open-source CLI.