Pest Plugin Snapshots Laravel Package

Getting Started

Install the package as a dev dependency — no extra configuration needed:

composer require spatie/pest-plugin-snapshots --dev

After installation, the first snapshot test run will automatically create the tests/Snapshots/ directory and generate snapshot files. Use one of the three core patterns to assert output:

it('outputs correct string', function () {
    $result = (new Order(1))->toString();
    expect($result)->toMatchSnapshot();
});

it('returns expected JSON', function () {
    $response = $this->getJson('/api/orders/1')->json();
    assertMatchesJsonSnapshot($response);
});

Start by reading the README and the underlying phpunit-snapshot-assertions docs — this plugin is a thin, API-compatible wrapper.

Implementation Patterns

🔍 Snapshot Types & Syntax

Use expectation syntax for fluency or function calls for control:

📁 Organizing Snapshots

Group by feature/context using custom IDs to avoid fragile filenames:

it('creates an order', function () {
    $order = Order::create(['amount' => 99.99]);
    expect($order->toArray())->toMatchSnapshot('orders/create');
});

it('updates an order', function () {
    $order->update(['amount' => 149.99]);
    expect($order->toArray())->toMatchSnapshot('orders/update');
});

→ Files: tests/Snapshots/Feature/Orders/Order_creates_an_order.orders_create.snapshot

🔄 Development Workflow

• Update snapshots locally: pest --update-snapshots
• Verify all snapshots in CI: pest --no-interaction (no prompts, fails on mismatch)
• Clean unused snapshots: pest --clean-snapshots (v2.3.0+)
• Diff only failed snapshots: pest --only-failed --diff

Gotchas and Tips

⚠️ Common Pitfalls

• Test renaming breaks snapshots: Filenames embed the test description. If you rename the test, the old snapshot becomes orphaned. Prefer explicit IDs for stable paths.
• Whitespace differences cause false failures: Normalize strings explicitly (trim(), preg_replace('/\s+/', ' ', $str)) — especially important when generating HTML/Markdown.
• Image snapshots are fragile across environments: Font rendering, OS, or screen scaling differences may cause mismatches. Use controlled assets or consider tolerance options (check underlying package docs).
• Never snapshot sensitive data: Snapshots are committed. Sanitize before snapshotting (['secret' => 'REDACTED']) or use custom ID generators to redact.

🛠 Debugging & Troubleshooting

• Check snapshot path: Default is tests/Snapshots/, but can be customized via SNAPSHOT_PATH in phpunit.xml.
• Verify dependencies: Ensure spatie/phpunit-snapshot-assertions ^5.3.1 matches plugin requirements (v2.3.0+).
• Snapshot not found? Confirm the test runs with Pest (not PHPUnit) and that tests/Snapshots/ is writable.

🔌 Customization & Extensibility

• Custom snapshot ID generator: Use the SnapshotIdAware trait in your test cases or Pest config.
• Global helper in tests/Pest.php:

  function snapshot_json($data, string $id = ''): void {
      assertMatchesJsonSnapshot($data, $id);
  }
  

• Snapshot path override in phpunit.xml:

  <php>
      <server name="SNAPSHOT_PATH" value="tests/_snapshots"/>
  </php>
  

• Per-test directory isolation: Prefix custom IDs with tests/Feature/... to match project structure.