Download the PHP package bmarsaud/phpunit-snapshot-assertions without Composer
On this page you can find all versions of the php package bmarsaud/phpunit-snapshot-assertions. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download bmarsaud/phpunit-snapshot-assertions
More information about bmarsaud/phpunit-snapshot-assertions
Files in bmarsaud/phpunit-snapshot-assertions
Package phpunit-snapshot-assertions
Short Description Snapshot testing with PHPUnit
License MIT
Homepage https://github.com/bmarsaud/phpunit-snapshot-assertions
Informations about the package phpunit-snapshot-assertions
Snapshot testing with PHPUnit
Why this fork ?
The purpose of this fork is to make the spatie/phpunit-snapshot-assertions
package compatible with PHP 7.3.
The compatibility is ensured using Rector.
Note that he only version currently available is the 4.2.2
.
A more durable and reliable way would be to use a GitHub action applying Rector on each tag pushed on the original repository.
Description
Snapshot testing is a way to test without writing actual test cases
On the first run, the test runner will create a new snapshot.
On subsequent runs, the test will pass as long as the snapshot doesn't change.
If there's a regression, the test will fail!
Support us
Learn how to create a package like this one, by watching our premium video course:
We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.
We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.
Installation
You can install the package via composer:
Usage
To make snapshot assertions, use the Spatie\Snapshots\MatchesSnapshots
trait in your test case class. This adds a set of assertion methods to the class:
assertMatchesSnapshot($actual)
assertMatchesFileHashSnapshot($actual)
assertMatchesFileSnapshot($actual)
assertMatchesHtmlSnapshot($actual)
assertMatchesJsonSnapshot($actual)
assertMatchesObjectSnapshot($actual)
assertMatchesTextSnapshot($actual)
assertMatchesXmlSnapshot($actual)
assertMatchesYamlSnapshot($actual)
Snapshot Testing 101
Let's do a snapshot assertion for a simple string, "foo".
The first time the assertion runs, it doesn't have a snapshot to compare the string with. The test runner generates a new snapshot and marks the test as incomplete.
Snapshot ids are generated based on the test and testcase's names. Basic snapshots return a plain text or YAML representation of the actual value.
Let's rerun the test. The test runner will see that there's already a snapshot for the assertion and do a comparison.
If we change actual value to "bar", the test will fail because the snapshot still returns "foo".
When we expect a changed value, we need to tell the test runner to update the existing snapshots instead of failing the test. This is possible by adding a-d --update-snapshots
flag to the phpunit
command.
As a result, our snapshot file returns "bar" instead of "foo".
File snapshots
The MatchesSnapshots
trait offers two ways to assert that a file is identical to the snapshot that was made the first time the test was run:
The assertMatchesFileHashSnapshot($filePath)
assertion asserts that the hash of the file passed into the function and the hash saved in the snapshot match. This assertion is fast and uses very little disk space. The downside of this assertion is that there is no easy way to see how the two files differ if the test fails.
The assertMatchesFileSnapshot($filePath)
assertion works almost the same way as the file hash assertion, except that it actually saves the whole file in the snapshots directory. If the assertion fails, it places the failed file next to the snapshot file so they can easily be manually compared. The persisted failed file is automatically deleted when the test passes. This assertion is most useful when working with binary files that should be manually compared like images or pdfs.
Customizing Snapshot Ids and Directories
Snapshot ids are generated via the getSnapshotId
method on the MatchesSnapshot
trait. Override the method to customize the id. By default, a snapshot id exists of the test name, the test case name and an incrementing value, e.g. Test__my_test_case__1
.
Example: Replacing the __
Delimiter With --
By default, snapshots are stored in a __snapshots__
directory relative to the test class. This can be changed by overriding the getSnapshotDirectory
method.
Example: Renaming the __snapshots__
directory to snapshots
Using specific Drivers
The driver used to serialize the data can be specificied as second argument of the
assertMatchesSnapshot
method, so you can pick one that better suits your needs:
Writing Custom Drivers
Drivers ensure that different types of data can be serialized and matched in their own way. A driver is a class that implements the Spatie\Snapshots\Driver
interface, which requires three method implementations: serialize
, extension
and match
.
Let's take a quick quick look at the JsonDriver
.
- The
serialize
method returns a string which will be written to the snapshot file. In theJsonDriver
, we'll decode and re-encode the json string to ensure the snapshot has pretty printing. - We want to save json snapshots as json files, so we'll use
json
as their file extension. - When matching the expected data with the actual data, we want to use PHPUnit's built in json assertions, so we'll call the specific
assertJsonStringEqualsJsonString
method.
Drivers can be used by passing them as assertMatchesSnapshot
's second argument.
Usage in CI
When running your tests in Continuous Integration you would possibly want to disable the creation of snapshots.
By using the --without-creating-snapshots
parameter, PHPUnit will fail if the snapshots don't exist.
A note for Windows users
Windows users should configure their line endings in .gitattributes
.
Changelog
Please see CHANGELOG for more information what has changed recently.
Testing
Contributing
Please see CONTRIBUTING for details.
Security
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
Postcardware
You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.
Our address is: Spatie, Samberstraat 69D, 2060 Antwerp, Belgium.
We publish all received postcards on our company website.
Credits
- Sebastian De Deyne
- Alex Vanderbist
- All Contributors
License
The MIT License (MIT). Please see License File for more information.
All versions of phpunit-snapshot-assertions with dependencies
ext-dom Version *
ext-json Version *
phpunit/phpunit Version ^8.3|^9.0
symfony/property-access Version ^4.0|^5.0
symfony/serializer Version ^4.0|^5.0
symfony/yaml Version ^4.0|^5.0