@datashard/snapshot
v3.0.0-beta.1
Published
Adds JSON Snapshot testing support to Cypress
Downloads
464
Maintainers
Readme
@datashard/snapshot
Adds JSON Snapshot comparison to Cypress
⚠️ Breaking Changes ⚠️
- With V3, the
readFileMaybe
task has been removed, we now rely oncy.fixture
internally. - the previous
SNAPSHOT_UPDATE
Environment/Config Variable has been changed toupdateSnapshots
[!DANGER] This means that previous tests will likely be broken, please make sure that your tests pass before updating to the latest version of this Plugin.
This current release will be released as 3.0.0-beta
, should Bugs be found by me or my Employer, I will open Issues/PRs to fix those, should anyone else find Bugs/Edgecases, etc. please open an Issue.
Install
Requires Node 16 or above
npm i --save-dev @datashard/snapshot
Import
After Installing, you'll need to add the following import into your Commands/Support File
by default this will be
cypress/support/e2e.js
require('@datashard/snapshot').regsiter()
This will register a new Command .snapshot()
, to create and compare JSON Snapshots.
Config
You can pass updateSnapshots
and useFolders
as options in the cypress.config.js
file
Alternatively, you can also add snapshotUpdate
as an Environment Variable to update your snapshots.
Simply pass --env updateSnapshots=true
when running Cypress.
Usage
If properly added, usage of this plugin is rather simple, just add .snapshot()
to cypress functions that return valid JSON. (i.e. cy.wrap
)
When properly added, you can chain .snapshot()
off of cy
functions like cy.wrap
, just make sure they return valid JSON.
Example
describe("my test", () => {
it("works", () => {
cy.log("first snapshot");
cy.wrap({ foo: 42 }).snapshot("foo");
cy.log("second snapshot");
cy.wrap({ bar: 101 }).snapshot("bar");
});
});
This Plugin will then save your snapshots as
// useFolders: false
cypress/fixtures/my-test__works__foo.json
cypress/fixtures/my-test__works__bar.json
// useFolders: true
cypress/fixtures/my-test/works/foo.json
cypress/fixtures/my-test/works/bar.json
// {fixtureFolder}/<Context>-<Describe>-<It>-<Name?>.json
// {fixtureFolder}/<Context>/<Describe>/<It>/<Name?>.json
Snapshots will generally be saved using this the Convention mentioned in the Comment of the above Codeblock, which is provided by the named Cypress Test Steps.
Passing a name to the Snapshot function is required, but not checked, if you want to take multiple snapshots in the same block.
If you have two or more Snapshots in the same Block, the next one WILL always overwrite the previous one while updating, causing the First Snapshot in the Block to Fail. While running your Tests, if a value changed, it will, of course, no longer match the snapshot and throw an Error.
Which will look like this:
When the Test succeeds, it will instead log a Success in the Log and let you know where the File has been saved to, relative to the Fixture Snapshot Folder