Architecture Overview

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

Meticulous automates end-to-end testing by:

1. Recording real user interactions in your application
2. Selecting the most valuable sessions for testing
3. Replaying those sessions on every code change
4. Comparing screenshots to detect visual differences

Think of it as "TiVo for your application" - recording how users interact with your app, then replaying those interactions to catch bugs.

What happens: As users interact with your application, Meticulous captures everything they do.

What gets recorded:

• Clicks, typing, scrolling, navigation
• Network requests and their responses
• What the page looked like at key moments

Where this happens: Wherever you install the recorder (localhost, staging, production)

The key idea: Real users create your tests just by using your app normally.

What happens: Meticulous analyzes all recorded sessions and picks the best ones for testing.

The goal: Get maximum coverage with minimal redundancy. Instead of running thousands of sessions, run the 200-500 that matter most.

How sessions are chosen:

• Do they visit unique pages?
• Do they exercise different user flows?
• Are they recent (newer sessions preferred)?
• Do they provide good coverage?

The result: A "golden set" of sessions that represent your app's core functionality.

What happens: When you create a pull request, Meticulous replays your golden set against both versions of your app.

The process:

1. Build your app from the PR code
2. Replay each session - simulating the exact same user interactions
3. Take screenshots at important moments
4. Compare with baseline - screenshots from your main branch

The magic: Network requests are "stubbed" - Meticulous replays the recorded API responses, so you don't need your backend running.

Two test runs:

• Base run: How your app looked on the main branch
• Head run: How your app looks with your changes

What happens: Results are posted back to your pull request.

You get:

• A comment showing which screenshots changed
• A status check (pass/fail)
• A link to review differences visually

What you do: Review the diffs and either:

• Approve them (if changes are intentional)
• Fix the bug (if something broke)
• Investigate false positives

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)

Session: One user'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 (your user) 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

When to use: Only if none of the above approaches work for your app

How it works:

• CI builds your app and starts a local server
• Meticulous creates a secure tunnel to reach it
• Tests run against your local server through the tunnel

Pros: Works with any setup, full control Cons: Most brittle approach; requires starting the app in CI

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.

Record new sessions with the new format. Old sessions with old responses will eventually age out of your golden set.

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)

Doesn't test:

• Backend logic (we recommend testing backend logic in unit and integration tests)
• Cross-browser compatibility (tests run in Chrome)
• Accessibility (though visual review can help)

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 real user sessions (clicks, API calls, screenshots)
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

The insight: Let users create your tests. You just record what they do and replay it.

The innovation: Network stubbing makes tests fast and deterministic without needing your backend.

The result: Catch bugs before they reach production, with minimal effort.