> Meticulous records real user sessions from a web app and replays them against each commit to catch visual regressions.
>
> Full AI-readable docs index (complete project setup journey + every page as markdown): https://app.meticulous.ai/llms.txt

# Architecture Overview

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

---

## The Big Picture

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.

---

## The Four Phases

### 1. Recording Phase

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

---

### 2. Selection Phase

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

---

### 3. Replay Phase

**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

---

### 4. Integration Phase

**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

---

## Key Concepts Explained

### Network Stubbing: Testing Without a Backend

**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](/docs/concepts/network-recording-and-patching).

---

### Sessions, Test Runs, and Replays

**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 vs Head: How Diffs Are Detected

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

---

## How Sessions Become Tests

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

---

## Deployment Types

### Option 1: Upload Static Assets (Recommended for static sites)

**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

---

### Option 2: Upload a Docker Container (Recommended for server-rendered apps)

**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

---

### Option 3: Preview URLs

**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

---

## Common Questions

### "Do I need my backend running during tests?"

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

### "What if my backend changes?"

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

### "What if I change an API response format?"

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](/docs/concepts/network-recording-and-patching).

### "How does Meticulous know what changed?"

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

### "Can't I just approve all diffs and move on?"

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

---

## What Meticulous Tests

**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)

---

## Why This Architecture?

**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

---

## Summary

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.