Codeception Snapshot Assertions Laravel Package

Getting Started

lucatume/codeception-snapshot-assertions is a Codeception snapshot-assertion helper, not a Laravel-specific package. In a Laravel app, use it in Codeception unit/functional/acceptance suites to lock down stable API payloads, DTO arrays, event payloads, and config structures.

Minimal setup:

1. Install it as a dev dependency:

   composer require --dev lucatume/codeception-snapshot-assertions
   

2. Enable the package’s module/helper or trait in your Codeception suite configuration, following the package README for the exact module name and actor wiring.
3. Start with one stable Laravel endpoint or payload. Normalize dynamic values first, then snapshot the normalized array/string:

   $I->sendGET('/api/health');
   $I->seeResponseCodeIs(200);
   
   $payload = json_decode($I->grabResponse(), true);
   
   // Use the snapshot assertion exposed by the installed package version.
   $this->assertSnapshotEquals($payload);
   

4. Run the test once to create the snapshot, then run it again to verify comparison.

Where to look first: the package README for assertion method names and snapshot directory configuration, then commit the generated snapshot files so they are reviewed like fixtures.

Implementation Patterns

• Snapshot normalized API contracts, not raw responses. Decode JSON, remove or freeze timestamps/UUIDs/IDs, sort unstable collections, then snapshot the result. This catches real contract changes without failing on incidental data.
• Use Laravel test controls around snapshots. Pair snapshot assertions with RefreshDatabase, factories, Carbon::setTestNow(), Queue::fake(), Notification::fake(), and fixed seed data so the snapshot input is deterministic.
• Prefer focused snapshots. Snapshot the relevant payload slice rather than a full HTML page or huge response. Smaller snapshots are easier to review and less brittle.
• Use data providers deliberately. 0.5.0 normalizes spaces in data set names to underscores when deriving snapshot names. Use explicit, stable data set names and re-run/update snapshots after the upgrade if existing names contained spaces.
• Treat snapshots as reviewed fixtures. Commit them to VCS and inspect diffs in pull requests. An updated snapshot should be an intentional assertion change, not an automatic accept.
• Use custom normalization/serialization hooks where the package exposes them. If your Laravel payloads contain environment-specific paths, dates, locales, or ordering, normalize centrally rather than duplicating cleanup in every test.

Gotchas and Tips

• 0.5.0 changes snapshot naming for data sets with spaces. Spaces in data set names are now converted to _. If you already have snapshot files whose names contain spaces, the new version may look for an underscore-named file instead. Migration: rename the affected snapshot files, or delete and regenerate them, then review the resulting diff.
• Watch dynamic payload fields. Timestamps, UUIDs, auto-increment IDs, absolute paths, locale-dependent strings, and unordered JSON arrays are common snapshot failures. Freeze or normalize them before assertion.
• Do not let CI silently create missing snapshots. Check how the package handles missing snapshots and configure CI so new snapshots must be committed intentionally. Use any “update snapshots” mode locally only.
• Keep data set names simple. Even though spaces are normalized in 0.5.0, prefer explicit names without spaces or path-sensitive characters to keep snapshot filenames predictable across platforms.
• Debug by inspecting the resolved snapshot path. When a snapshot unexpectedly fails, confirm the test name, data set name, and snapshot directory first; then compare the normalized actual value against the stored file.
• Extension points to check in the README: snapshot storage path, update mode/flag, custom normalizers or serializers, and any module/helper configuration. These are the safest places to adapt the package to Laravel-specific payloads.