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 replayed on any URL, like a new version of your web app on localhost. Meticulous captures a screenshot at the end of each replay 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 replay-time, meaning you don’t need a backend environment to replay 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/. You will be prompted to create an organization and project.
  • Add the Meticulous CLI to your project, using one of the following two commands:

2. Record sessions

  • Grab the API token from your project page on Meticulous.
  • Start your browser with Meticulous by running the following command:
  • 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. Replay sessions

  • Grab the API token from your project page on Meticulous.
  • You can now replay a recorded session.
    • 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 dashboard on Meticulous and choose a session to replay. Note the session id. You can also use a session ID recorded from step 3.
    • Start a local replay using the following command
  • This will start a local browser in Puppeteer and replay the session against that url.
  • The replay 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 replay ID, which you can find in your Meticulous dashboard.

4. Create a Meticulous test

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


You can set up multiple tests using a Meticulous.json file, where you can specify various scenarios to test. Learn more about this at the section Setting up GitHub actions

Updated 13 Jul 2022
Did this page help you?