add readme

README.md

@@ -17,6 +17,81 @@ npm install --save-dev @cypress/snapshot
 
 ## Use
 
+After installing, add the following to your `cypress/support/commands.js` file
+
+```js
+require('@cypress/snapshot')()
+```
+
+This registers a new command to create new snapshot or compare value to old snapshot
+
+```js
+describe('my tests', () => {
+  it('works', () => {
+    cy.log('first snapshot')
+    cy.wrap({ foo: 42 }).snapshot()
+    cy.log('second snapshot')
+    cy.wrap({ bar: 101 }).snapshot()
+  })
+})
+
+describe('focused input field', () => {
+  it('is empty and then typed into', () => {
+    cy.visit('http://todomvc.com/examples/react/')
+    cy
+      .focused()
+      .snapshot('initial')
+      .type('eat healthy breakfast')
+      .snapshot('after typing')
+  })
+})
+```
+
+The snapshot object can be found in file `snapshots.js`. In the above case it would look something like this
+
+```js
+module.exports = {
+  "focused input field": {
+    "is empty and then typed into": {
+      "initial": {
+        "tagName": "input",
+        "attributes": {
+          "class": "new-todo",
+          "placeholder": "What needs to be done?",
+          "value": ""
+        }
+      },
+      "after typing": {
+        "tagName": "input",
+        "attributes": {
+          "class": "new-todo",
+          "placeholder": "What needs to be done?",
+          "value": "eat healthy breakfast"
+        }
+      }
+    }
+  },
+  "my tests": {
+    "works": {
+      "1": {
+        "foo": 42
+      },
+      "2": {
+        "bar": 101
+      }
+    }
+  }
+}
+```
+
+If you change the site values, the saved snapshot will no longer match, throwing an error
+
+![Snapshot mismatch](img/snapshot-mismatch.png)
+
+## Debugging
+
+To debug this module run with environment variable `DEBUG=@cypress/snapshot`
+
 ### Small print
 
 Author: Gleb Bahmutov <gleb@cypress.io> © 2017

package.json

@@ -29,6 +29,7 @@
     "node": ">=6"
   },
   "files": [
+    "img",
     "src/*.js",
     "!src/*-spec.js"
   ],
@@ -61,13 +62,15 @@
     "size": "t=\"$(npm pack .)\"; wc -c \"${t}\"; tar tvf \"${t}\"; rm \"${t}\";",
     "test": "npm run unit",
     "unit": "mocha src/*-spec.js",
-    "unused-deps": "dependency-check --unused --no-dev ."
+    "unused-deps": "dependency-check --unused --no-dev . --entry src/add-initial-snapshot-file.js",
+    "postinstall": "node src/add-initial-snapshot-file.js"
   },
   "release": {
     "analyzeCommits": "simple-commit-message"
   },
   "devDependencies": {
     "ban-sensitive-files": "1.9.2",
+    "debug": "3.1.0",
     "dependency-check": "2.9.1",
     "deps-ok": "1.2.1",
     "eslint": "4.13.0",
@@ -80,6 +83,7 @@
   },
   "dependencies": {
     "@wildpeaks/snapshot-dom": "1.2.1",
+    "am-i-a-dependency": "1.1.2",
     "check-more-types": "2.24.0",
     "its-name": "1.0.0",
     "lazy-ass": "1.6.0",

src/add-initial-snapshot-file.js

@@ -0,0 +1,25 @@
+const debug = require('debug')('@cypress/snapshot')
+const fs = require('fs')
+const path = require('path')
+const utils = require('./utils')
+const amDependency = require('am-i-a-dependency')()
+
+if (amDependency) {
+  // yes, do something interesting
+  // someone is executing "npm install foo"
+  debug('post install - in folder', process.cwd())
+  // we are in <owner>/node_modules/@cypress/snapshot
+  // but want to be simply in <owner> folder
+  const ownerFolder = path.normalize(path.join(process.cwd(), '..', '..', '..'))
+  const filename = path.join(ownerFolder, utils.SNAPSHOT_FILE_NAME)
+
+  if (!fs.existsSync(filename)) {
+    // save initial empty snapshot object
+    debug('writing initial file', filename)
+    fs.writeFileSync(filename, '{}\n')
+  } else {
+    debug('file %s already exists', filename)
+  }
+} else {
+  debug('not a dependency install')
+}

src/index.js

@@ -14,6 +14,8 @@ function registerCypressSnapshot () {
   la(is.fn(global.after), 'missing global after function')
   la(is.object(global.Cypress), 'missing Cypress object')
 
+  console.log('registering @cypress/snapshot')
+
   let storeSnapshot
 
   // for each full test name, keeps number of snapshots
@@ -38,10 +40,8 @@ function registerCypressSnapshot () {
   function evaluateLoadedSnapShots (js) {
     la(is.string(js), 'expected JavaScript snapshot source', js)
     console.log('read snapshots.js file')
-    console.log(js)
     const store = eval(js) || {}
-    console.log('store')
-    console.log(store)
+    console.log('have %d snapshot(s)', Object.keys(store).length)
     storeSnapshot = initStore(store)
   }
 

src/utils.js

@@ -0,0 +1,3 @@
+module.exports = {
+  SNAPSHOT_FILE_NAME: 'snapshots.js'
+}