> 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

# Glossary

Alphabetical reference of Meticulous terminology and concepts.

---

## API Token

**Definition**: A secret authentication token used to authenticate Meticulous API requests.

**Where used**: CI workflows, CLI commands

**How to get**: From the Meticulous dashboard project settings

**Security**: Should be stored as a CI secret (e.g., `METICULOUS_API_TOKEN`)

**Related concepts**: [Project](#project)

**Related docs**: GitHub Actions setup

---

## Base Commit

**Definition**: The commit from your main/target branch that a PR is based on.

**Purpose**: Provides the comparison point for detecting diffs. The **base test run** shows how the app looked before your changes.

**Example**:
- Main branch is at commit `abc123`
- You create a PR from commit `abc123`
- Base commit = `abc123`
- Head commit = Your latest PR commit

**Related concepts**: [Head Commit](#head-commit), [Base Test Run](#base-test-run), [Diff](#diff)

**Related docs**: Architecture overview

---

## Base Test Run

**Definition**: A test run executed on the **base commit** (main branch).

**Purpose**: Serves as the comparison baseline for detecting visual changes in a PR.

**When created**:
- Automatically on pushes to main branch
- Manually via `workflow_dispatch`

**Why it matters**: Without a base test run, Meticulous cannot detect diffs (no comparison point).

**Common issue**: "No base test run found" - occurs when main branch hasn't run yet after adding Meticulous.

**Related concepts**: [Head Test Run](#head-test-run), [Base Commit](#base-commit), [Test Run](#test-run)

**Related docs**: FAQ and troubleshooting

---

## Cloud Compute

**Definition**: Meticulous execution mode where tests run in Meticulous' cloud infrastructure using a secure tunnel or preview URL.

**Use cases**:
- Testing locally-served apps via secure tunnel
- Testing preview URLs (Vercel, Netlify)
- Next.js and server-rendered applications

**GitHub Action**: `alwaysmeticulous/report-diffs-action/cloud-compute@v1`

**Alternative**: [Upload Assets](#upload-assets)

**Related concepts**: [Secure Tunnel](#secure-tunnel), [Preview URL](#preview-url)

**Related docs**: GitHub Actions setup

---

## Cloud Replay

**Definition**: Testing mode where Meticulous connects directly to a preview URL without a secure tunnel.

**Use cases**: Apps deployed to Vercel, Netlify, or other preview URL providers

**Advantages**: Faster than tunnel, tests real deployment environment

**Configuration**: Requires preview URL integration

**Related concepts**: [Preview URL](#preview-url), [Cloud Compute](#cloud-compute)

**Related docs**: Cloud replay guide

---

## Companion Assets

**Definition**: Static files uploaded alongside your app and served directly by Meticulous instead of proxying through the tunnel.

**Use cases**:
- Next.js `/_next/static/` folders
- Large static assets (images, fonts, videos)
- Assets on CDN during recording but local during testing

**Configuration**: Requires both:
- `companion-assets-folder`: Path to local folder
- `companion-assets-regex`: Regex pattern to match requests

**Example**:
```yaml
companion-assets-folder: "companion-assets"
companion-assets-regex: "^/_next/static/"
```

**Related concepts**: [Secure Tunnel](#secure-tunnel), [Static Assets](#static-assets)

**Related docs**: Companion assets advanced guide

---

## Custom Event API

**Definition**: Advanced Meticulous API for recording and replaying custom events with fine-grained control.

**Use cases**:
- Complex scenarios beyond custom values API
- Timing-sensitive event replay
- Custom integration logic

**Related concepts**: [Custom Values API](#custom-values-api)

**Related docs**: Custom event API guide

---

## Custom Values API

**Definition**: Meticulous API for storing custom data during recording and retrieving it during replay.

**Use cases**:
- File upload handling (storing file contents)
- Feature flag values
- User context
- Dynamic configuration

**Size limits**:
- Development: 20MB per value
- Production: 1MB per value

**API methods**:
- `window.Meticulous.recordCustomValues({})`
- `window.Meticulous.getCustomValues()`

**Related concepts**: [Custom Event API](#custom-event-api), [File Upload](#file-upload)

**Related docs**: Record custom values, Handle file uploads

---

## Diff

**Definition**: A detected visual difference between base and head test runs.

**How detected**: Pixel-by-pixel screenshot comparison

**States**:
- **Unapproved**: Detected, not reviewed
- **Approved**: Reviewed and accepted as expected
- **Rejected**: Identified as a bug to fix

**Workflow**:
1. Diff detected in test run
2. Posted to PR comment
3. Developer reviews in Meticulous UI
4. Developer approves or rejects

**Related concepts**: [Base Test Run](#base-test-run), [Head Test Run](#head-test-run), [Screenshot](#screenshot)

**Related docs**: Reviewing diffs

---

## File Upload

**Definition**: Handling of file input elements and drag-and-drop uploads in Meticulous tests.

**Challenge**: Meticulous doesn't store uploaded files by default.

**Solutions**:
1. **Skip validation** (recommended): Use `window.Meticulous.isRunningAsTest` to bypass file validation
2. **Store contents**: Use custom values API for small files
3. **Custom events**: For complex scenarios

**Related concepts**: [Custom Values API](#custom-values-api), [Network Stubbing](#network-stubbing)

**Related docs**: Handle file uploads

---

## Golden Set

**Definition**: The curated subset of recorded sessions selected for testing. Also called **Selected Sessions**.

**Selection criteria**:
- Code coverage
- Page coverage
- User flow diversity
- Recency

**Typical size**: 200-500 sessions

**Updates**: Automatically refreshed as new sessions are recorded

**Related concepts**: [Session](#session), [Session Selection](#session-selection)

**Related docs**: Architecture overview

---

## Head Commit

**Definition**: The latest commit in a PR branch being tested.

**Purpose**: The **head test run** shows how the app looks with your PR changes.

**Related concepts**: [Base Commit](#base-commit), [Head Test Run](#head-test-run)

**Related docs**: Architecture overview

---

## Head Test Run

**Definition**: A test run executed on the **head commit** (PR branch).

**Purpose**: Shows how the app looks with your changes. Compared against base test run to detect diffs.

**When created**: On every PR commit

**Related concepts**: [Base Test Run](#base-test-run), [Head Commit](#head-commit), [Test Run](#test-run)

**Related docs**: Architecture overview

---

## Network Stubbing

**Definition**: Technique where recorded network requests/responses are replayed instead of making real network calls.

**How it works**:
- During recording: Capture request + response
- During replay: Intercept request → Return recorded response
- Over time: Patch stale response shapes from newer recordings, and replace sessions that no longer add unique coverage

**Benefits**:
- No backend needed during tests
- Deterministic behavior
- Faster test execution

**What's stubbed**: All HTTP/HTTPS requests from browser

**What's not stubbed**: WebSockets (unless configured), excluded domains

**Related concepts**: [Replay](#replay), [Session](#session)

**Related docs**: [Network Recording & Patching](/docs/concepts/network-recording-and-patching), Architecture overview, FAQ

---

## Preview URL

**Definition**: A unique URL generated by deployment platforms (Vercel, Netlify) for each PR.

**Use with Meticulous**: Cloud replay can test preview URLs directly without a tunnel.

**Advantages**: Faster than tunnel, tests real deployment

**Related concepts**: [Cloud Replay](#cloud-replay), [Secure Tunnel](#secure-tunnel)

**Related docs**: Cloud replay guide

---

## Project

**Definition**: A Meticulous project represents a single application being tested.

**Contains**:
- API token for authentication
- Recorded sessions
- Selected sessions (golden set)
- Test runs
- Configuration settings

**One project per app**: If you have multiple apps, create multiple projects.

**Related concepts**: [API Token](#api-token), [Session](#session)

**Related docs**: Getting started

---

## Recorder

**Definition**: JavaScript snippet injected into your app that captures user sessions.

**Installation methods**:
1. Script tag in HTML
2. NPM dependency

**What it captures**:
- User interactions (clicks, typing, scrolling)
- Network requests and responses
- DOM snapshots
- Page metadata

**When active**: During user sessions on production/staging

**Related concepts**: [Session](#session), [Session Recording](#session-recording)

**Related docs**: Recorder installation

---

## Replay

**Definition**: The execution of a recorded session in a test environment.

**Process**:
1. Launch browser
2. Navigate to initial URL
3. Replay user interactions
4. Stub network requests
5. Capture screenshots

**States**:
- **Success**: All interactions replayed
- **Failure**: Errors encountered
- **Partial**: Some interactions skipped

**Related concepts**: [Simulation](#simulation), [Test Run](#test-run), [Session](#session)

**Related docs**: Architecture overview

---

## Replay Accuracy

**Definition**: Percentage of user interactions successfully replayed.

**Calculation**: (Replayed interactions / Total interactions) × 100

**Scores**:
- **100%**: Perfect replay
- **80-99%**: Mostly successful
- **<80%**: Significant issues

**Factors affecting**:
- DOM changes (elements removed/moved)
- Timing issues (async loading)
- Non-deterministic behavior

**Related concepts**: [Simulation](#simulation), [Replay](#replay)

**Related docs**: Troubleshoot replay accuracy

---

## Screenshot

**Definition**: An image captured during replay showing the app state at a specific moment.

**When captured**:
- Page navigations
- Significant DOM changes
- User-specified moments

**Used for**: Visual comparison between base and head test runs

**Storage**: S3 with metadata in database

**Related concepts**: [Diff](#diff), [Test Run](#test-run)

**Related docs**: Architecture overview

---

## Secure Tunnel

**Definition**: An encrypted connection from Meticulous' cloud environment to your CI runner, allowing tests to access locally-served apps.

**How it works**:
1. CI starts local app (e.g., `localhost:3000`)
2. Meticulous establishes tunnel connection
3. Cloud replay environment connects through tunnel
4. Requests proxied to local app

**Security**: HTTP Basic Authentication, encrypted connection

**Debugging**: Add `meticulous-debug` to PR title for tunnel access

**Related concepts**: [Cloud Compute](#cloud-compute), [Companion Assets](#companion-assets)

**Related docs**: Tunnel advanced options

---

## Session

**Definition**: A recorded user journey through your application from entry to exit.

**Contains**:
- Sequence of user interactions
- Network requests and responses
- Initial URL and metadata
- Duration and timestamp

**Lifecycle**:
1. User interacts with app
2. Recorder captures session
3. Session uploaded to S3
4. Session processed and stored
5. Session may be selected for golden set

**Example**: Homepage → Products → Add to cart → Checkout

**Related concepts**: [Recorder](#recorder), [Replay](#replay), [Golden Set](#golden-set)

**Related docs**: Architecture overview

---

## Session Recording

**Definition**: The process of capturing user sessions using the Meticulous recorder.

**Phase**: First phase of Meticulous workflow

**Where it happens**: Production or staging environment with real users

**Related concepts**: [Recorder](#recorder), [Session](#session)

**Related docs**: Architecture overview

---

## Session Selection

**Definition**: The process of choosing which recorded sessions to include in the golden set for testing.

**Goal**: Maximize coverage while minimizing redundancy

**Criteria**:
- Code coverage
- Page coverage
- Flow diversity
- Recency

**When it happens**: Automatically after new sessions recorded

**Related concepts**: [Golden Set](#golden-set), [Session](#session)

**Related docs**: Architecture overview

---

## Simulation

**Definition**: The process of replaying a session. Synonym for [Replay](#replay).

**Simulation accuracy**: See [Replay Accuracy](#replay-accuracy)

**Related concepts**: [Replay](#replay), [Session](#session)

**Related docs**: Architecture overview

---

## Static Assets

**Definition**: Files like JavaScript, CSS, images, fonts that don't change based on runtime logic.

**Challenges with Meticulous**:
- Absolute URLs aren't automatically rewritten
- Large files slow down tunnel
- Next.js `/_next/static/` folders

**Solutions**:
- Use relative URLs instead of absolute
- Use companion assets for large files
- Use companion assets for Next.js static folders

**Related concepts**: [Companion Assets](#companion-assets)

**Related docs**: GitHub Actions setup, Companion assets advanced

---

## Test Run

**Definition**: A single execution of tests for a specific commit, containing multiple replays.

**Contains**:
- Commit SHA
- Multiple replays (one per selected session)
- Screenshots from all replays
- Overall status

**Types**:
- **Base test run**: On base commit
- **Head test run**: On head commit (PR)

**Lifecycle**:
1. Triggered by CI (PR or push to main)
2. Fetch selected sessions
3. Replay each session
4. Capture screenshots
5. Compare to base (if available)
6. Post results

**Related concepts**: [Replay](#replay), [Base Test Run](#base-test-run), [Head Test Run](#head-test-run)

**Related docs**: Architecture overview

---

## Tunnel

See [Secure Tunnel](#secure-tunnel).

---

## Upload Assets

**Definition**: Meticulous execution mode where built static assets are uploaded for testing.

**Use cases**: Static sites (Vite, Create React App) that can be served as HTML/CSS/JS

**Not recommended for**: Next.js, server-rendered apps

**GitHub Action**: `alwaysmeticulous/report-diffs-action/upload-assets@v1`

**Alternative**: [Cloud Compute](#cloud-compute)

**Related concepts**: [Static Assets](#static-assets)

**Related docs**: GitHub Actions setup

---

## Visual Regression

**Definition**: Unintended visual changes in the UI (layout shifts, style changes, broken components).

**How Meticulous detects**: Screenshot comparison between base and head test runs

**Examples**:
- Button moved to wrong position
- Text color changed unexpectedly
- Image not loading
- Layout broken on mobile

**Related concepts**: [Diff](#diff), [Screenshot](#screenshot)

**Related docs**: Architecture overview

---

## Window.Meticulous

**Definition**: JavaScript API exposed by the Meticulous recorder for runtime integration.

**Available methods**:
- `isRunningAsTest`: Check if running in test mode
- `recordCustomValues()`: Store custom data
- `getCustomValues()`: Retrieve stored data
- `recordCustomEvent()`: Record custom event
- `pause()`, `resume()`: Control replay timing

**Availability**: Only when recorder snippet is loaded

**Related concepts**: [Custom Values API](#custom-values-api), [Custom Event API](#custom-event-api)

**Related docs**: window.Meticulous object reference

---

## Workflow

**Definition**: CI/CD automation file that defines when and how to run Meticulous tests.

**Common locations**:
- GitHub Actions: `.github/workflows/meticulous.yaml`
- GitLab CI: `.gitlab-ci.yml`

**Required triggers**:
- `push` to main branch (for base runs)
- `pull_request` (for head runs)
- `workflow_dispatch` (for manual triggers)

**Related concepts**: [Test Run](#test-run), [Base Test Run](#base-test-run)

**Related docs**: GitHub Actions setup