Directory snapshot, diff, and patch system useful for test fixtures

Features

• Directory comparison - Compare two directories for identical structure and content
• Baseline + diff architecture - Store a baseline once, then only diffs per test scenario
• Unified diff format - Human-readable patch files that can be reviewed in PRs
• Auto-update snapshots - Automatically update snapshots when tests fail
• Flexible ignore rules - Skip files, directories, or ignore content differences
• PHPUnit integration - Simple trait with intuitive assertions

Use Cases

This library is designed for testing systems that generate file output:

• Template repositories - Test scaffolds, skeletons, and boilerplate generators to ensure customization options produce the expected file structure
• Code generators - Verify that generated code matches expected output across different configuration scenarios
• Build tools - Assert that compilation or transformation processes produce correct artifacts
• Migration scripts - Validate that file transformations work correctly

For example, if you maintain a project template with customizable options (like choosing a database driver or enabling optional features), you can use this library to test each combination of options produces the correct files.

Concepts

Baseline

A baseline is a reference directory containing the expected file structure and content. It represents the "golden master" that your test output is compared against.

Snapshot (Scenario)

A snapshot (or scenario) represents differences from the baseline for a specific test case. Instead of duplicating the entire expected output, you only store the files that differ.

Diff Files

Snapshot directories contain diff files in unified diff format. These describe how a file should differ from its baseline version:

Snapshot directories can also contain:

• New files - Full file content for files not in baseline (copied as-is)
• Deletion markers - Files prefixed with - (e.g., -README.md) indicate the file should not exist in this scenario

Installation

composer require --dev alexskrypnyk/snapshot

Usage

Basic Directory Comparison

Use assertDirectoriesIdentical() to compare two directories:

Baseline + Diff Testing

For multiple test scenarios sharing common files, use a baseline directory with scenario-specific diffs:

This approach:

• Reduces duplication across test fixtures
• Makes differences between scenarios explicit
• Produces reviewable diff files in pull requests

Auto-Update Snapshots

Enable automatic snapshot updates when tests fail:

Run tests with the environment variable:

Batch Snapshot Updates

For tests with many datasets, use the update-snapshots CLI tool to update snapshots with timeout handling, automatic retries, and parallel execution:

The tool:

• Discovers all datasets from PHPUnit test list
• Runs baseline dataset first (sequentially), then remaining scenarios in parallel
• Handles timeouts with configurable retries
• Auto-commits baseline and snapshot changes
• Shows a live TUI progress display with scrolling when running in a terminal

Options:

• --root=<path> - Project root directory (default: current directory)
• --test-dir=<path> - Directory containing tests (default: tests)
• --timeout=<seconds> - Timeout per test run (default: 30)
• --retries=<count> - Max retries for timed out tests (default: 12)
• --jobs=<count> - Number of parallel jobs for scenarios (default: 4)
• --debug - Show PHPUnit output for failed tests

Parallel Execution

When updating all datasets, the baseline is always run first (since other scenarios may depend on it). Once the baseline completes, all remaining scenarios run in parallel using the number of jobs specified by --jobs.

In a TTY terminal, a live progress display shows the status of all tasks with keyboard scrolling (arrow keys and Page Up/Down). In non-TTY environments (e.g., CI), results are printed after all tasks complete.

Ignore Rules

Create a .ignorecontent file in your baseline directory to control which files are compared and how.

Why Ignore Content?

Some files should exist but have unpredictable or environment-specific content:

• composer.lock - You want to verify it was generated, but the exact content depends on dependency resolution timing and isn't meaningful to test
• package-lock.json - Same as above for npm dependencies
• Generated timestamps - Files containing build dates or version hashes
• Environment configs - Files that vary between CI and local environments

Using ^filename ensures the file exists without failing on content differences.

Pattern Reference

Programmatic API

Use the Snapshot class directly for custom workflows:

Fluent Builder API

For configured operations with rules and content processors, use SnapshotBuilder:

Programmatic Rules

Configure comparison rules programmatically using the Rules class:

Version Normalization

When updating snapshots, volatile content like version numbers, hashes, and timestamps can cause unnecessary churn. The Replacer class automatically normalizes this content during snapshot updates.

Default Behavior

The snapshotUpdateBefore() hook automatically applies version normalization using File::getReplacer()->addVersionReplacements():

The default patterns replace:

• Semver versions (1.2.3, v1.2.3-beta.1) → __VERSION__
• Git hashes (@abc123...) → @__HASH__
• SRI integrity hashes (sha512-...) → __INTEGRITY__
• Docker image tags (nginx:1.21.0) → nginx:__VERSION__
• GitHub Actions versions (actions/checkout@v4) → actions/checkout@__VERSION__
• Package versions in JSON ("^1.2.3") → "__VERSION__"

Customizing Version Replacement

Override snapshotUpdateBefore() to customize the replacement behavior:

Or disable version replacement entirely:

Standalone Usage

Use Replacer independently for custom workflows:

Maintenance

composer install
composer lint
composer test

Performance Benchmarks

Run benchmarks to measure performance of core operations:

# Run benchmarks with baseline comparison
composer benchmark

# Create or update baseline
composer benchmark-baseline

# Quick test (verify benchmarks work)
./vendor/bin/phpbench run benchmarks/SnapshotBench.php --iterations=1 --revs=1