Get started with Meticulous

Meticulous is a tool to create UI tests without writing code and without requiring a staging environment. Use our CLI to open an instrumented browser which records your actions as you execute a workflow on your web app. This sequence of actions can then be simulated on any URL, like a new version of your web app on localhost. Meticulous captures a screenshot at the end of each simulation and a test consists of diffing these two screenshots. Meticulous makes it easy to integrate these tests into your CI.

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. You can also 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 https://app.meticulous.ai/signup. 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

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

yarn

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

2. Record sessions

  • Start your browser with Meticulous by running the following command:

Record sessions

npm

npx meticulous record --apiToken="<API_TOKEN>"

yarn

yarn meticulous record --apiToken="<API_TOKEN>"
  • This will open up a blank page. You can now navigate to the site which you want to record a session on. This could be localhost, or any URL.
  • You can now interact with the site and your session will be recorded.
  • Navigate back to your terminal and you will see that a link has been printed out. That link is the session recording on the Meticulous dashboard where you can watch a video playback.
  • Once you are finished, just close the tab and exit the command.

3. Simulate sessions

  • Start a local dev server of your app (e.g. npm run dev) such that your web app is being served on localhost.
  • Go onto your Meticulous dashboard on Meticulous and choose a session to simulate. Note the session id. You can also use a session ID recorded from step 3.
  • Start a local simulation using the following command

Simulate sessions

npm

npx meticulous simulate --apiToken="<API_TOKEN>" \
  --sessionId="2022-02-28T13:47:34.163Z_ADvadSSEdvca" \
  --appUrl="http://localhost:3000/" \
  --screenshot

yarn

yarn meticulous simulate --apiToken="<API_TOKEN>" \
  --sessionId="2022-02-28T13:47:34.163Z_ADvadSSEdvca" \
  --appUrl="http://localhost:3000/" \
  --screenshot
  • This will start a local browser in Puppeteer and simulate the session against that url.
  • The simulation should now appear on your Meticulous dashboard. You can watch a video playback here.
  • The screenshot option saves a screenshot locally and to your Meticulous dashboard. This can then be used for future tests.
  • Make a note of the simulation ID, which you can find in your Meticulous dashboard.

4. Create a Meticulous test

Suppose you ran the above simulation twice, on two different versions of code. We will now execute a single test using the screenshot-diff command. You can retrieve simulation reference IDs from your Meticulous dashboard. In the example below we assume that our reference simulation is abc123 performed against the main branch of our webapp and the our new simulation is xyz789 done against a new version of the frontend.

A Meticulous test is defined by specifying 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.

Define these in a meticulous.json, like below:

{
  "testCases": [
    {
      "title": "Sign in flow",
      "sessionId": "2022-02-28T13:47:34.163Z_ADvadSSEdvca",
      "baseReplayId": "BmQYthZKWheJxWQEYdT8H"
    }
  ]
}

You can then execute the run-all-tests command, like below:

Run All Tests

npm

npx meticulous run-all-tests --apiToken="<API_TOKEN>" \
  --appUrl=http://localhost:3000/ \
  --headless

yarn

yarn meticulous run-all-tests --apiToken="<API_TOKEN>" \
  --appUrl=http://localhost:3000/ \
  --headless

This command opens a browser in headless mode and simulates the sequence of actions against the URL provided. A screenshot is taken at the end, and diffed against the baseline screenshot of the baseline simulation. This command prints out a link to the test run, where you can easily update the tests (if the change is expected) or inspect the visual differences.

Learn more about integrating Meticulous into CI in Setting up GitHub actions.