Custom checks

Meticulous visual tests catch any regression that affects the functional or visual behaviour of the application as perceived by a user. By replaying real user sessions and comparing screenshots pixel by pixel, they surface unintended visual changes before they reach production, and through this also surface any behavioural changes that affect these user workflows. But not every regression is visible. A change can leave every screen looking identical while still making your app slower, chattier, or heavier to load.

Meticulous custom checks let you catch those regressions too. They let you define additional rules that run on top of the same test run — passing, warning, or requiring a reviewer's acknowledgement — surfacing the regressions a screenshot comparison cannot see. Because they reuse the sessions Meticulous already replays on every commit, you get this coverage without writing or maintaining a separate suite of tests.

The most common use case is catching performance and resource regressions. A refactor might double the number of API calls a page makes, a new dependency might increase the size of your JavaScript bundle, or a change might introduce extra round-trips on a critical flow — all while the UI looks pixel-perfect. Custom checks let you assert on these metrics: compare each session's behaviour on the head commit against its baseline, and surface a warning when a threshold is crossed.

Your check logic runs in your own CI pipeline and is built with the @alwaysmeticulous/custom-checks npm package. Unlike visual regressions — which Meticulous detects the same way for everyone — every organisation has different needs when it comes to non-visual regressions: which metrics matter, what counts as an acceptable change, and where to draw the line between a warning and a failure. Running the check logic in your own CI gives you full control to encode exactly those rules, rather than forcing your requirements into a one-size-fits-all check.

Complete, runnable example checks live in the custom-checks-examples repository.

Custom checks split into three phases:

1. Snapshot collection (during replay). As Meticulous replays each session on the head and base deployments, it captures snapshots — structured data points stored alongside the replay so they can be downloaded later. Some snapshot types require no changes in your application, such as network-requests, js-bundle-sizes, and react-renders (see Built-in snapshot types), and you can also record your own from browser code via window.Meticulous.replay.recordCustomSnapshot(...) (see Recording custom snapshots).
2. Check computation (in your CI). After a test run finishes, a script you own downloads the base and head snapshots, runs your comparison logic, and posts the verdicts back to Meticulous in a single API call. For example, a check might sum each session's network requests on base and head, then require a reviewer's acknowledgement if any session makes more than 20% more API calls on head than it did on base.
3. Reporting and acknowledgement (on the PR). Custom checks get their own dedicated status check on the pull request — Meticulous Custom Checks — separate from the visual-diff check, so a non-visual regression can be surfaced without cluttering the visual results (and vice versa). Each check decides how strict to be: it can simply warn that something looks potentially off without blocking the pull request, or it can require a reviewer to explicitly acknowledge the result in the Meticulous UI before the pull request can proceed, the same way visual diffs are reviewed.