Compare commits

..

2 commits

Author SHA1 Message Date
Joshua
e4f9cbc5cf finish most writings 2024-04-25 14:09:41 +02:00
Joshua
71fe145047 Expand Readme, remove Gleb, up version number 2024-04-25 13:01:00 +02:00
7 changed files with 46 additions and 33 deletions

BIN
.github/assets/Correct.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 9 KiB

BIN
.github/assets/Error.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 14 KiB

View file

@ -1,3 +1,5 @@
cypress/
cypress.config.js
.github/workflows/
.vscode/
renovate.json

View file

@ -1,2 +0,0 @@
{
}

View file

@ -1,4 +1,4 @@
Copyright (c) 2023-2024 Joshua <data@shard.wtf>
Copyright (c) 2023-2024 Joshua data@shard.wtf
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation

View file

@ -1,14 +1,19 @@
# @datashard/snapshot
> Adds support for Value, Object, and Dom Element Snapshot Testing to Cypress
> Adds JSON Snapshot comparison to Cypress
## Breaking Changes
> [!WARNING]
The `readFileMaybe` task was required in previous Versions, this has been changed so this Module now uses the `cy.fixture` Command to get the contents of existing files. This means that this module will only be able to write new tests if `updateSnapshots` (previously `SNAPSHOT_UPDATE`) is set to true through Environment Variables or through the Cypress config.
\
This also means, that previous tests will likely be broken, *please make sure that your tests pass before updating to the latest version of this module*
## ⚠️ Breaking Changes ⚠️
- With V3, the `readFileMaybe` task has been removed, we now rely on `cy.fixture` internally.
- the previous `SNAPSHOT_UPDATE` Environment/Config Variable has been changed to `updateSnapshots`
> [!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
```sh
@ -16,33 +21,36 @@ 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`
```js
require('@datashard/snapshot').regsiter()
```
This will register a new Command `.snapshot()`, to create new Snapshots and once created, to compare their Values.
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
![Example Settings for the Module](./.github/assets/config.png)
Alternatively, you can also add `snapshotUpdate` as an Environment Variable to update your snapshots.
Simply pass `--env updateSnapshots=true` when running Cypress.
> If you don't use the default fixture folder, you will also need to add `snapshotPath` to this module's config with the same path you use for `fixtureFolder`.
## Usage
If properly added, usage of this plugin is rather simple, simply add `.snapshot()` to cypress functions that return valid JSON.
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
```js
describe("my tests", () => {
describe("my test", () => {
it("works", () => {
cy.log("first snapshot");
cy.wrap({ foo: 42 }).snapshot("foo");
@ -52,28 +60,33 @@ describe("my tests", () => {
});
```
Depending on your settings, this module will then save your snapshots as
This Plugin will then save your snapshots as
```ts
// useFolders: false
cypress/fixtures/snapshots/my-tests__works__foo.json
cypress/fixtures/snapshots/my-tests__works__bar.json
cypress/fixtures/my-test__works__foo.json
cypress/fixtures/my-test__works__bar.json
// useFolders: true
cypress/fixtures/snapshots/my-tests/works/foo.json
cypress/fixtures/snapshots/my-tests/works/bar.json
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 convention, provided by Cypress:
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.
```
{fixtureFolder}/<Context>-<Describe>-<It>-<Name?>.json
{fixtureFolder}/<Context>/<Describe>/<It>/<Name?>.json
```
Passing a name to the Snapshot function is required, but not checked, if you want to take multiple snapshots in the same block.
If a step wasn't named, it will instead use the `<It>`for the file name, though this means that you will not be able to have more than 1 Snapshot in your It Block, as it would overwrite the previously created Snapshot files.
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:
Of course, if a value changed, it will no longer match the snapshot and throw an Error.
![](./.github/assets/Error.png)
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
![](./.github/assets/Correct.png)

View file

@ -1,8 +1,8 @@
{
"name": "@datashard/snapshot",
"description": "Adds value / object / DOM element snapshot testing support to Cypress test runner",
"version": "2.3.2",
"author": "Joshua <data@shard.wtf>, Gleb Bahmutov <gleb@cypress.io>",
"description": "Adds JSON Snapshot testing support to Cypress",
"version": "3.0.0-beta",
"author": "Joshua <data@shard.wtf>",
"bugs": "https://github.com/datashard/snapshot/issues",
"engines": {
"node": ">=6"
@ -13,13 +13,13 @@
"src/*/**",
"!src/*-spec.js"
],
"homepage": "https://github.com/datashard/snapshot#readme",
"homepage": "https://shard.wtf/snapshot",
"keywords": [
"cypress",
"cypress-io",
"plugin",
"snapshot",
"testing"
"testing", "json"
],
"license": "MIT",
"main": "src/index.js",