Glossary

Alphabetical reference of Meticulous terminology and concepts.

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

Related docs: GitHub Actions setup

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, Base Test Run, Diff

Related docs: Architecture overview

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, Base Commit, Test Run

Related docs: FAQ and troubleshooting

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

Related concepts: Secure Tunnel, Preview URL

Related docs: GitHub Actions setup

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, Cloud Compute

Related docs: Cloud replay guide

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:

companion-assets-folder: "companion-assets"
companion-assets-regex: "^/_next/static/"

Related concepts: Secure Tunnel, Static Assets

Related docs: Companion assets advanced guide

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

Related docs: Custom event API guide

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, File Upload

Related docs: Record custom values, Handle file uploads

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, Head Test Run, Screenshot

Related docs: Reviewing diffs

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, Network Stubbing

Related docs: Handle file uploads

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 Selection

Related docs: Architecture overview

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, Head Test Run

Related docs: Architecture overview

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, Head Commit, Test Run

Related docs: Architecture overview

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

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, Session

Related docs: Architecture overview, FAQ

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, Secure Tunnel

Related docs: Cloud replay guide

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, Session

Related docs: Getting started

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 Recording

Related docs: Recorder installation

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, Test Run, Session

Related docs: Architecture overview

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, Replay

Related docs: Troubleshoot replay accuracy

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, Test Run

Related docs: Architecture overview

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, Companion Assets

Related docs: Tunnel advanced options

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, Replay, Golden Set

Related docs: Architecture overview

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, Session

Related docs: Architecture overview

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, Session

Related docs: Architecture overview

Definition: The process of replaying a session. Synonym for Replay.

Simulation accuracy: See Replay Accuracy

Related concepts: Replay, Session

Related docs: Architecture overview

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

Related docs: GitHub Actions setup, Companion assets advanced

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, Base Test Run, Head Test Run

Related docs: Architecture overview

See Secure Tunnel.

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

Related concepts: Static Assets

Related docs: GitHub Actions setup

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, Screenshot

Related docs: Architecture overview

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 Event API

Related docs: window.Meticulous object reference

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, Base Test Run

Related docs: GitHub Actions setup