Architecture Overview

Understand how Meticulous works at a high level - from recording sessions to detecting visual differences in your pull requests.

Meticulous provides exhaustive verification for the most complex codebases. It works in two phases:

Meticulous starts by building a repository of 'sessions' (sequences of user actions paired with test data / network mocks). Each session is indexed by the lines of code in your codebase it executes and the various other edge cases it activates.

This repository is populated by:

1. Recording all user and agent interactions against your application, across the enterprise (on both staging stacks and local environments)
2. Generating on the fly sessions to cover any gaps

For larger codebases this repository can grow into millions of sessions. It is this rich data that gives Meticulous the knowledge of how to access every edge case in your application - each screen, feature flag combination, configuration and data edge case.

Within this repository we also maintain a 'selected set': a much smaller subset of sessions selected such that each line of code in the codebase and each edge case (via a series of other measures) is covered at least once. This selected set is updated continuously as your codebase evolves. The longer you use Meticulous the more powerful it becomes.

When you trigger Meticulous on a code change we analyze the change statically to trace the full impact through codebase, find the blast radius, and from this find all the edge cases that could be impacted. We'll pick all relevant existing sessions from within the session repository, and, if configured for your project, spin up a swarm of agents to cover any gaps (these generated sessions are fed back into the repository for future tests).

We take this set of relevant sessions, spin up browsers in our cluster and replay them against both the version of the application before your code change and the version of the application after your code change.

As we run these flows we take a sequence of screenshots, producing a set of videos of how the application behaves before your code change, and a set of videos after your code changes. This produces a set of pairs of videos -- for some changes thousands of pairs of videos, each pair testing a different edge case, or different parts of your application.

We then diff the key frames in these videos and identify all the differences. Since we run the flows in our deterministic browser, it reduces the noise by a couple orders of magnitude, sufficient to allow us to detect differences reliably at huge scale without false positives. This allows agents or humans to trust the differences returned.

The diffs will be grouped and duplicated for fast review, by human or agent. If the Meticulous test run was triggered from a pull request we'll post a comment back to your pull request, summarizing the results, and linking into Meticulous to review the diffs visually; if triggered by an agent they'll be provided to the agents, with tools and guidance to understand the set of differences.

The problem: Traditional E2E tests need your entire stack running - database, backend, third-party APIs. This is slow and brittle.

Meticulous' solution: Record API responses once, replay them forever.

How it works:

During recording:

• User clicks "Login"
• Browser sends request to your API
• API responds with user data
• Meticulous saves both the request and response

During replay (weeks later, no backend needed):

• Test clicks "Login"
• Browser tries to send the same request
• Meticulous intercepts it and returns the saved response
• Browser never knows the difference!

Why this matters:

• Tests run faster (no real API calls)
• Tests are deterministic (same input, same output)
• Tests are zero-effort to set up (no backend infrastructure needed)
• Edge cases are preserved (error responses replay exactly as recorded)

For how stubs stay useful when APIs drift, mutation-then-GET flows, and why stubs don't need to be perfect, see Network Recording & Patching.

Session: One user's or agent's journey through your app

Example: User visits homepage → clicks product → adds to cart → checks out

Test Run: All tests for one commit

Contains: Multiple replays (one per selected session) for a specific version of your code

Replay: Playing back one session

Result: Series of screenshots showing what happened

Base commit: Your main branch (the "before" state)

Head commit: Your PR branch (the "after" state)

How comparison works:

1. Run tests on base commit → get baseline screenshots
2. Run tests on head commit → get new screenshots
3. Compare them pixel-by-pixel
4. Report any differences

Why you need both: Without a baseline, there's nothing to compare against. The first PR after setup has no base, so it just establishes one.

Let's follow a session from recording to diff detection:

Day 1 - Recording:

• Sarah visits your app
• She searches for "blue shoes", clicks a result, adds to cart
• Meticulous records: every click, every API response, every screenshot

Day 2 - Selection:

• Meticulous analyzes Sarah's session
• It covers the search page, product page, and cart - good coverage!
• Session added to the golden set

Day 7 - You Create a PR:

• You change the product page layout
• CI runs Meticulous tests
• Sarah's session replays on both main branch and your PR branch

Comparison:

• Product page screenshot on main: Shows old layout
• Product page screenshot on PR: Shows your new layout
• Diff detected!

Your action:

• Review the diff
• Looks good, this was intentional
• Click "Approve"
• PR can now be merged

When to use: Pure static site (HTML/JS/CSS, no server-side rendering)

How it works:

• CI builds your static files
• Meticulous uploads them to cloud storage
• Tests run against the hosted static site

Pros: Simplest and most reliable setup

When to use: Server-rendered apps (Next.js, Nuxt, etc.)

How it works:

• CI builds a Docker image of your app
• Meticulous hosts and runs the container
• Tests run against the containerized app

Pros: Works with any server-rendered framework, reliable

When to use: You deploy to preview URLs (Vercel, Netlify, etc.)

How it works:

• Your deployment service creates a preview URL
• Meticulous tests directly against that URL
• No CI workflow changes needed

Pros: No build step in CI, tests the actual deployed version

No! That's the whole point of network stubbing. API responses are replayed from recordings.

Tests still pass as long as your frontend works correctly. Backend changes don't affect frontend tests.

Meticulous patches affected sessions using newer recordings of the same endpoint shape when possible, and replaces sessions that no longer add unique coverage. See Network Recording & Patching.

Pixel-by-pixel screenshot comparison. If even one pixel differs, it's flagged as a diff.

You could, but then you'd miss real bugs! The point is to catch unintended visual changes.

Tests:

• How your UI looks
• How user interactions work
• What users see after clicking buttons
• Visual regressions (layout shifts, styling bugs)
• Functional bugs (broken navigation, missing elements)
• Business logic in the frontend (e.g. pricing calculations, discount logic)
• Accessibility (if accessibility checks are enabled)
• Performance (if performance checks are enabled)

Not tested

• Backend logic is not tested by default, but in some configurations Meticulous can be set up to test it.

Goal: Make E2E testing so easy that teams actually use it.

Challenges with traditional E2E tests:

• Slow (wait for backend, database, APIs)
• Flaky (network issues, timing problems)
• Expensive (infrastructure costs)
• Hard to maintain (tests break when UI changes and backend logic changes)

How Meticulous solves these:

• Fast: Network stubbing removes backend dependency
• Deterministic: Recorded responses = same results every time
• Low maintenance: Tests are user sessions, not code to update

Meticulous works by:

1. 📹 Recording user and agent sessions (clicks, API calls, screenshots), and generating sessions as required to fill the gaps
2. 🎯 Selecting the best sessions for comprehensive coverage
3. ▶️ Replaying sessions on every PR (with API responses stubbed)
4. 🔍 Comparing screenshots to detect visual differences