From e4f9cbc5cfa786e697843e89d0ed5413b62152de Mon Sep 17 00:00:00 2001 From: Joshua Date: Thu, 25 Apr 2024 14:09:41 +0200 Subject: [PATCH] finish most writings --- .npmignore | 3 ++- LICENSE | 2 +- README.md | 55 +++++++++++++++++++++++++++++++----------------------- 3 files changed, 35 insertions(+), 25 deletions(-) diff --git a/.npmignore b/.npmignore index 6aed89d..76237e1 100644 --- a/.npmignore +++ b/.npmignore @@ -1,4 +1,5 @@ cypress/ cypress.config.js .github/workflows/ -.vscode/ \ No newline at end of file +.vscode/ +renovate.json \ No newline at end of file diff --git a/LICENSE b/LICENSE index 2c12d72..b22f0b8 100644 --- a/LICENSE +++ b/LICENSE @@ -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 diff --git a/README.md b/README.md index 7e36e12..6aaec3f 100644 --- a/README.md +++ b/README.md @@ -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}/---.json +// {fixtureFolder}////.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}/---.json -{fixtureFolder}////.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)