Get started with Meticulous

Meticulous is a tool to record and replay user sessions. A user session is a sequence of interactions on a web application, like clicking on the sign-up button, typing in an email address and clicking submit. Meticulous can be used to replay these user sessions on new code. This allows you to find out information about the runtime execution of that code, prior to that code being released. You can do this without causing side effects or hitting your backend. You can read more about the concept of 'replay testing' here.

Our customers use Meticulous for many different purposes, such as:

• Replaying sessions on new code, seeing how flows change or break when replaying the same user flow, or viewing them side-by-side to see how the flow differs.
• Recording sessions and sharing them with other engineers' to quickly share a bug reproduction.
• Using our JS snippet to record all dev, QA, staging sessions and integrating our replay into CI in order to build an automated visual diff regression system.

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

• 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:

• 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.

• 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.
• You can access data such as: what network requests were made, snapshot dom sequence and what exceptions were thrown.

You can replay against any URL, such as a preview url. So if you wanted to build a system to test for regressions, you could replay on a head commit and base commit, and diff data from the two.

You can do this if you want to generate preview URLs to replay against. By uploading your builds, we can then serve your web app up for you to replay against.

• Grab the API token from your project page on Meticulous
• Add the Meticulous CLI to your project:

• Test the CLI and make sure you have a Meticulous Project ready to upload builds to. You can grab the API_TOKEN from your project page on Meticulous.

Note that you can also set the METICULOUS_API_TOKEN environment variable and omit the --apiToken argument.

• Upload a build
  • Build your app
  • Upload your build artifacts to Meticulous

• Troubleshooting:
  • The CLI tries to guess the commit SHA1, if this fails it's possible to manually set it with the --commitSha argument.

The Meticulous JavaScript snippet will record user sessions. Customers' inject this onto their sites, normally non-production environments, in order to automatically and passively capture a pool of session data. This data can then be used for replay.

To set up the snippet:

• Go to your project page to copy the javascript code snippet to insert inside your application. You will see something similar to this below:

• Copy the code snippet and insert it in your app. We recommend doing this on all non-production environments (staging, development and local).

• Record a session in your local dev environment and check that it appears on the Meticulous app. It may take a few minutes before it appears.