Meticulous Onboarding Guide

Before installing the Meticulous session recorder, you should decide which environments are a good fit for recording user sessions:

• The session recorder should always be installed on localhost to ensure that sessions generated by engineers developing and testing your application locally are captured.
• We also recommended installing it on other internal environments, like staging stacks or preview URLs.
• If you are interested in recording production sessions, please reach out to Meticulous support for additional details.

There are two approaches to installing the recorder:

1. Frontend framework specific installation
2. If you cannot ensure that the Meticulous snippet is the first script to execute on your page when installing through your frontend framework, you can try installing the recorder using a script tag.

More information on troubleshooting recorder problems can be found here and here.

Before setting up tests to run in CI, you should ensure that sessions can be simulated on your local machine. Debugging any issues on your local machine is much easier than debugging any issues that occur in CI. You can replay locally using the following CLI command:

npx @alwaysmeticulous/cli simulate
  --apiToken="<API_TOKEN>"
  --sessionId="<SESSION_ID>"
  --appUrl="<URL_WHERE_APP_IS_RUNNING_LOCALLY>"

Important session simulation scenarios to check:

• Can you simulate sessions on authenticated pages? If not, see this doc on troubleshooting authentication & authorization issues.
• Can you simulate sessions on a different environment from where they were recorded (e.g. can you simulate a session recorded on sandbox against your localhost environment)? If not, see this doc on troubleshooting cross environment issues

Two tools to debug simulation issues:

• Once a simulation has completed and been uploaded to Meticulous, you can view all the events that happened during the simulation on the Timeline & Logs tab of the simulation’s page in the Meticulous UI
• Simulating a session with the flags --debugger --devToolsCopy to clipboard will let you step through the simulation one user event at a time and pinpoint exactly where the issue is occurring

For test runs to be executed in CI, Meticulous needs to be able to simulate sessions in 3 different contexts:

1. PR test runs: whenever a new commit is pushed to a PR branch, Meticulous kicks off a test run where it simulates user sessions against the app running that commit. Ideally, this version of the app would be hosted on a commit-specific URL, but Meticulous can also run against the app if it's spun up in CI.
2. New-commit-on-main test runs: whenever a new commit is pushed to the main branch, Meticulous kicks off a test run to take new baseline screenshots. Ideally, Meticulous would run against a commit-specific URL here as well, but running the app in CI also works.
3. Session selection test runs: each night, Meticulous simulates every new session from the last 24 hours to determine if any of them add new coverage and should be included in the selected set. In this context, we want to test against the latest version of your app, so usually a publicly accessible staging URL works best.

How to get Meticulous to trigger test runs across these contexts depends on how you build and serve your app:

• [Recommended] Vercel preview URLs. If you use Vercel preview URLs, the complexity of dealing with three different environments is completely abstracted. You can add Meticulous’ Vercel integration here and then follow the guide here to complete installation.
• Other preview URL providers (e.g. Netlify). If you deploy your app to a preview URL without Vercel, you can follow the doc here to set up Meticulous.
• Only in CI. If you only build and run your app in CI, you can follow the guide here to configure the Meticulous GitHub action.

Once Meticulous is set up to run in CI, there is usually a tuning period (~1-2 weeks) required to get Meticulous working at full capacity. A variety of features that can be used to tune Meticulous are described below.

If you make heavy use of feature flags we recommend configuring Meticulous to support using old sessions to test new features that are gated behind feature flags. Get started here.

If you feel that coverage is insufficient, you can try to address it in a couple different ways:

• Increase the number of selected sessions. When you click the Configure button in the Selected Session tab of your project dashboard in the Meticulous UI, you will see a Number of Sessions to Auto Select section. Below this, Meticulous will recommend increasing the number of selected sessions if it will add more coverage.
• Enable the session recorder on production. Increasing the number of sessions being ingested by Meticulous should increase the level of coverage that Meticulous is able to provide. If you are interested in this option, please reach out to Meticulous support for more information.

You may run into a flake or false diff during the tuning period — below are some strategies to manage them:

• If the flake is not too frequent or problematic, you can click on the screenshot of the diff and then click Flag as Unexpected. This sends a bug report to the Meticulous team so that the flake can be prioritized and fixed.
• If the flake is problematic, you can use the techniques described in this doc to debug or ignore the problematic element