finish most writings

This commit is contained in:
Joshua 2024-04-25 14:09:41 +02:00
parent 71fe145047
commit e4f9cbc5cf
3 changed files with 35 additions and 25 deletions

View file

@ -2,3 +2,4 @@ cypress/
cypress.config.js
.github/workflows/
.vscode/
renovate.json

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,20 +21,22 @@ 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.
@ -38,9 +45,12 @@ Simply pass `--env updateSnapshots=true` when running Cypress.
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");
@ -50,31 +60,30 @@ 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 the Cypress Test Steps:
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 Snapshots in the same Block, the last one ***WILL*** overwrite the previous one while updating and the then updated Test will fail on the first snapshot.
```
{fixtureFolder}/<Context>-<Describe>-<It>-<Name?>.json
{fixtureFolder}/<Context>/<Describe>/<It>/<Name?>.json
```
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 looks like this:
Which will look like this:
![](./.github/assets/Error.png)