Merge pull request #13 from datashard/v3-breaking-noFS

Merge V3 into Master

.npmignore

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

LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2023-2024 Joshua [email protected]
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,55 +1,56 @@
 # @datashard/snapshot
 
-> Adds value / object / DOM element snapshot testing support to Cypress test runner
+> Adds JSON Snapshot comparison to Cypress
 
-<details>
-<summary>Changes between <code>@datashard/snapshot</code> and <code>@cypress/snapshot</code></summary>
-<br>
-They're mostly the same, as this is a fork of the Latter, though it's not a drop-in replacement.
+## ⚠️ Breaking Changes ⚠️
 
-Unlike `@cypress/snapshot`, this saves snapshots in their own files with a sensible default and strives to have ongoing Support for future Cypress Versions
+- 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`
 
-</details>
+> [!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*.
 
-<!-- [![NPM][npm-icon] ][npm-url] -->
+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](https://nodejs.org/en/) version 10 or above.
+Requires Node 16 or above
 
 ```sh
-npm install --save-dev @datashard/snapshot
+npm i --save-dev @datashard/snapshot
 ```
 
 ## Import
 
-After installing, you need to add this snippet within your Cypress Support File (default: `cypress/support/e2e.{js,ts}`)
+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").register();
+require('@datashard/snapshot').regsiter()
 ```
 
-This registers a new command to create new snapshot or compare value to old snapshot
+This will register a new Command `.snapshot()`, to create and compare JSON Snapshots.
 
-and add the following to your `cypress.config.{js,ts}`
+## Config
 
-```js
-  e2e: {
-    setupNodeEvents(on, config) {
-      require("@datashard/snapshot").tasks(on, 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.
 
-> **Note** \
-> \
-> `@datashard/snapshot` **requires** the `readFileMaybe` plugin to be included, which can be easily done using the code above
+Simply pass `--env updateSnapshots=true` when running Cypress.
 
-# Usage
+## Usage
 
-Currently, if you want to take more than one snapshot, you need to pass a Step Name to prevent overwrites / test failures
+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");
@@ -59,113 +60,33 @@ describe("my tests", () => {
 });
 ```
 
-In the above case, you can find the stored snapshot in their own files, mentioned above them
-
-```jsonc
-// cypress/snapshots/my-tests-works-foo.json
-{ "foo": 42 }
-// cypress/snapshots/my-tests-works-bar.json
-{ "bar": 101 }
-```
-
-If you change the site values, the saved snapshot will no longer match, throwing an error
-
-(picture taken from `cypress/snapshots/Arrays.json`)
-![Snapshot mismatch](.github/assets/updated-mismatch.png)
-
-Click on the `SNAPSHOT` step in the Command Log to see expected and current value printed in the DevTools.
-
-### Options
-
-You can control snapshot comparison and behavior through a few options.
-
-```js
-cy.get(...).snapshot({
-  snapshotName: 'Snapshot Name',          // Overwrite the generated Snapshot name
-  snapshotPath: 'cypress/not_snapshots', // Overwrite where the Snapshot should be stored
-  json: false                           // convert DOM elements into JSON
-})                                     // when storing in the snapshot file
-
-// will save as
-// cypress/not_snapshots/Snapshot-Name.json
-```
-
-You can also pass a "Step Name" to the Function
+This Plugin will then save your snapshots as
 
-```js
-cy.get(...).snapshot("Intercepted API Request")
-// will save as
-// cypress/snapshots/<context>-<describe>-<it>-Intercepted-API-Request.json
-// to prevent duplications
-```
+```ts
+// useFolders: false
+cypress/fixtures/my-test__works__foo.json
+cypress/fixtures/my-test__works__bar.json
 
-or both
+// useFolders: true
+cypress/fixtures/my-test/works/foo.json
+cypress/fixtures/my-test/works/bar.json
 
-```js
-cy.get(...).snapshot("Intercepted API Request", {
-  snapshotPath: "cypress/snapshots/api",
-  snapshotName: "first_intercept"
-})
+// {fixtureFolder}/<Context>-<Describe>-<It>-<Name?>.json
+// {fixtureFolder}/<Context>/<Describe>/<It>/<Name?>.json
 
-// will save as
-// cypress/snapshots/api/first_intercept.json
 ```
 
-### Configuration
-
-This module provides some configuration options:
-
-#### snapshot.snapshotPath
-
-Sets the default Path for saving Snapshots (default: `cypress/snapshots`)
-
-![Config Screenshot](./.github/assets/config.png)
-
-#### `ENV` CYPRESS_UPDATE_SNAPSHOTS
-
-Lets you pass a Env Variable to update failing Tests with the new Data
-
-#
-
-### Small print
-
-Authors:
-
-- Joshua &lt;[[email protected]](mailto:[email protected])&gt;
-- Gleb Bahmutov &lt;[email protected]&gt;
-
-<br>
-License: MIT - do anything with the code, but don't blame us if it does not work.
-
-Support: If you find any problems with this module [open an issue](https://github.com/datashard/snapshot/issues) on Github
+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.
 
-## MIT License
+Passing a name to the Snapshot function is required, but not checked, if you want to take multiple snapshots in the same block. 
 
-Copyright (c) 2017-2022 Cypress.io &lt;[email protected]&gt; & Joshua &lt;[email protected]&gt;
+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.
 
-Permission is hereby granted, free of charge, to any person
-obtaining a copy of this software and associated documentation
-files (the "Software"), to deal in the Software without
-restriction, including without limitation the rights to use,
-copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the
-Software is furnished to do so, subject to the following
-conditions:
+Which will look like this:
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+![](./.github/assets/Error.png)
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
-OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
-HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
+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
 
-[npm-icon]: https://nodei.co/npm/@datashard/snapshot.svg?downloads=true
-[npm-url]: https://npmjs.org/package/@datashard/snapshot
-[semantic-url]: https://github.com/semantic-release/semantic-release
-[renovate-badge]: https://img.shields.io/badge/renovate-app-blue.svg
-[renovate-app]: https://renovateapp.com/
+![](./.github/assets/Correct.png)

cypress.config.js

@@ -1,13 +1,15 @@
 const { defineConfig } = require("cypress");
-const { functions } = require("./src/utils");
 
 module.exports = defineConfig({
+  // fixturesFolder: "cypress/fixtures",
   snapshot: {
-    snapshotPath: "cypress/snapshots/",
+    // updateSnapshots: true,
+    useFolders: true,
   },
+
   e2e: {
     setupNodeEvents(on, config) {
-      functions.tasks(on, config);
+      // implement node event listeners here
     },
   },
-});
+});

cypress/e2e/1.cy.js

@@ -1,47 +1,78 @@
 /* eslint-env mocha */
 /* global cy */
-describe("@datashard/snapshot", () => {
-  context("simple types", () => {
-    it("works with objects", () => {
-      cy.fixture("File2").snapshot({
-        snapshotPath: "cypress/snapshots",
-        snapshotName: "Objects",
+describe("datashard/snapshot", () => {
+  context("simple types"
+    // , { env: { updateSnapshots: true } }
+    , () => {
+      it("works with objects", () => {
+        cy.wrap({
+          "foo": "bar",
+          "Fizzy Drink": "Pop"
+        }).snapshot();
       });
-    });
 
-    it("works with numbers", () => {
-      cy.wrap(42).snapshot({
-        snapshotPath: "cypress/snapshots",
-        snapshotName: "Numbers",
+      it("works with numbers", () => {
+        cy.wrap(42).snapshot({
+          snapshotPath: "cypress/fixtures/snapshots",
+          snapshotName: "Numbers",
+        });
       });
-    });
 
-    it("works with strings", () => {
-      cy.wrap("foo-bar").snapshot({
-        snapshotPath: "cypress/snapshots",
-        snapshotName: "Strings",
+      it("works with strings", () => {
+        cy.wrap("foo-bar").snapshot({
+          snapshotPath: "cypress/fixtures/snapshots",
+          snapshotName: "Strings",
+        });
       });
-    });
 
-    it(
-      "works with arrays",
-      {
-        env: {
-          SNAPSHOT_UPDATE: true,
+      it(
+        "works with arrays",
+        {
+          env: {
+            updateSnapshots: true,
+          },
         },
-      },
-      () => {
-        cy.wrap([1, 2, 3, 4]).snapshot({
-          snapshotPath: "cypress/snapshots",
-          snapshotName: "Arrays",
-        });
-      }
-    );
-    it('works with more "complicated" Objects', () => {
-      cy.fixture("Complex").snapshot({
-        snapshotPath: 'cypress/snapshots',
-        snapshotName: "Complex"
+        () => {
+          cy.wrap([1, 2, 3, 4]).snapshot({
+            snapshotPath: "cypress/fixtures/snapshots",
+            snapshotName: "Arrays",
+          });
+        }
+      );
+
+    });
+  context("complex types"
+    // , { env: { SNAPSHOT_UPDATE: true } }
+    , () => {
+      it('works with more "complicated" Objects', () => {
+        cy.wrap({
+          "status": 200,
+          "response": {
+            "array": [0, 1, 2, "4"],
+            "object": {
+              "with": "more details"
+            }
+          },
+          "thisisnew": "wtf"
+        }).snapshot()
       })
+      it("works based on fixtures", () => {
+        cy
+          .wrap({
+            "jsonapi": {
+              "version": "2.0"
+            },
+            "included": [
+              {
+                "type": "users",
+                "id": "2",
+                "attributes": {
+                  "name": "Test"
+                }
+              }
+            ]
+          })
+          .snapshot();
+      });
     })
-  });
 });