Requirements:

• PHP ≥ 8.3 with the uopz extension
• Node.js (for visual screenshot regression — installed automatically on first use)

Project root resolution. Every command resolves the project root in this order:

1. --root=<path> flag
2. CASSETTE_ROOT environment variable
3. Current working directory (default)

So cd /var/www/my-project && vendor/bin/cassette record run_001 just works without any flags.

Toggle uopz and inject the bootstrap line — up/down enable/disable uopz (incl. the PHP 8.5 patch) and write/remove the require_once hook in wp-config.php (WordPress) or public/index.php (Laravel):

./cassette up   --php=8.5 --root=/var/www/my-project
./cassette down --php=8.5 --root=/var/www/my-project

.cassette/config.json is created automatically on the first vendor/bin/cassette record call.

Usage

All commands accept --root=<path>. If omitted, CASSETTE_ROOT (env) is used, falling back to the current working directory.

Exit code 0 = all green, 1 = deviations found. CI-compatible.

All run data is stored in .cassette/runs/<name>/. The directory is created on the first vendor/bin/cassette invocation with a self-contained .cassette/.gitignore that excludes everything (*), so recordings stay out of git without touching the project's own .gitignore. To track screenshot baselines, replace that file's contents with negation patterns:

*
!runs/*/screenshots/
!runs/*/screenshots/*
!.gitignore

Development workflow (working on cassette itself)

When developing cassette alongside a project, you can run the CLI directly from the cassette source directory and point it at the target project — either via CASSETTE_ROOT or via --root:

cd /var/www/cassette
export CASSETTE_ROOT=/var/www/my-project
./cassette record run_001
./cassette stop   run_001
./cassette replay run_001

Or with an explicit flag:

./cassette record run_001 --root=/var/www/my-project

This way the target project's composer.json stays completely untouched — no path-repository, no minimum-stability, no symlinks. All cassette data is read from and written to /var/www/my-project/.cassette/ as usual.

Portability

Recordings are captured on one host (e.g. https://custom-tld.dev) but can be replayed anywhere — CI, localhost, staging — without re-recording:

# Replay against a different host than the one used during recording
vendor/bin/cassette replay run_001 --base-url=http://localhost

The --base-url flag replaces the host for both the HTTP diff and the Playwright screenshots. The recorded base_url in http.json is never modified.

For GitHub Actions, pass the URL as a secret:

- name: Replay cassettes
  run: vendor/bin/cassette replay run_001 --base-url=${{ secrets.APP_URL }}

No database required for replay

During replay, all database queries and outgoing HTTP calls are intercepted by uopz and served from the recorded cassette data. The server must be running and reachable, but:

• no real database connection is needed — the DB state at replay time is completely irrelevant
• no test fixtures or seed data are required
• external APIs and curl calls are mocked the same way

This makes cassette replays safe to run on CI, on a fresh machine, or against a server whose database is empty, stale, or even offline.

curl interception

To intercept __::curl() calls, add vielhuber/stringhelper to your project:

composer require vielhuber/stringhelper

Without it, cassette still records and replays all database calls — curl interception is simply skipped.

Configuration

Create .cassette/config.json to customise recording and screenshot behaviour per project:

{
    "ignoreUrls": [],
    "screenshot": {
        "headless": true,
        "zoom": 0.7,
        "maxDiffPixelRatio": 0.01,
        "maskSelectors": [],
        "maskDates": true,
        "timeout": 60000,
        "waitAfterGoto": 2000
    }
}