Mocha Snapshot Testing Utility

Common errors

• Error: 42 !== 80

  cause A previously saved snapshot value does not match the current test output, indicating a regression or an intentional change.
  fix Verify if the change is intentional. If it is, run your tests with `SNAPSHOT_UPDATE=1 npm test` to update the snapshot file. Otherwise, fix the code causing the unexpected output.

• Cannot read property 'afterAll' of undefined

  cause Running versions of `snap-shot-it` older than 7.9.2 with a test suite where all tests are skipped, which could lead to a crash in the `afterAll` hook.
  fix Upgrade to `snap-shot-it@7.9.2` or newer to resolve the `afterAll` hook crash. Alternatively, ensure at least one test is not skipped.

• SyntaxError: Unexpected token 'export' or 'import'

  cause Attempting to use ES Module syntax (`import`) in a CommonJS environment or vice-versa without proper configuration (e.g., `"type": "module"` in `package.json`).
  fix Ensure your project's module system is correctly configured. For CommonJS, use `const snapshot = require('snap-shot-it')`. For ES Modules, use `import snapshot from 'snap-shot-it'` and verify `package.json` specifies `"type": "module"` or files use `.mjs` extensions.

Warnings

• breaking Starting with version 7.9.1, `snap-shot-it` requires Node.js version 8 or above. Older Node.js versions are no longer supported.
  Fix: Upgrade your Node.js environment to version 8.x or newer.
• gotcha When using named snapshots (e.g., `snapshot('my name', value)`), the names must be unique within a single spec file by default. Duplicates will lead to unexpected behavior unless explicitly allowed.
  Fix: Ensure each named snapshot has a unique name per spec file. If intentional sharing is required, pass `{ allowSharedSnapshot: true }` as an option: `snapshot('my shared snapshot', value, { allowSharedSnapshot: true })`.
• gotcha To update, dry-run, or view snapshots, you must use specific environment variables (e.g., `SNAPSHOT_UPDATE=1`, `SNAPSHOT_DRY=1`, `SNAPSHOT_SHOW=1`) when running your tests.
  Fix: Prefix your test command with the desired environment variable, e.g., `SNAPSHOT_UPDATE=1 npm test` to update snapshots.
• gotcha `snap-shot-it` relies on spying on Mocha's global `it` function to determine test context. This approach, while effective, might cause conflicts or unexpected behavior in highly customized Mocha setups or when combined with other test utilities that also modify global test runner functions.
  Fix: If conflicts arise, review your test runner configuration and other test utilities to identify potential interactions with global `it` modifications. Consider isolating tests or using alternative snapshot solutions if deep customization is unavoidable.

Install

• npm install snap-shot-it npm
• yarn add snap-shot-it yarn
• pnpm add snap-shot-it pnpm

Imports

• snapshot
  wrong:

  const { snapshot } = require('snap-shot-it')

  correct:

  const snapshot = require('snap-shot-it')

  The primary export is a default function. Use this pattern for CommonJS modules, typically in Mocha test files.
• snapshot
  wrong:

  import { snapshot } from 'snap-shot-it'

  correct:

  import snapshot from 'snap-shot-it'

  For ES Modules and TypeScript, import the default function. The package provides TypeScript definitions for `snapshot` and its options.

Quickstart

This quickstart demonstrates how to set up `snap-shot-it` with Mocha, showing basic snapshot creation for synchronous values, strings, asynchronous results, and an example of data-driven testing. It includes instructions for running tests and updating snapshots.

/* package.json */
// {
//   "name": "my-test-project",
//   "version": "1.0.0",
//   "devDependencies": {
//     "mocha": "^10.0.0",
//     "chai": "^4.0.0",
//     "snap-shot-it": "7.x.x"
//   },
//   "scripts": {
//     "test": "mocha --require snap-shot-it spec.js"
//   }
// }

/* spec.js */
const snapshot = require('snap-shot-it');
const { expect } = require('chai');

function add(a, b) {
  return a + b;
}

describe('My Math Functions', () => {
  it('adds two numbers correctly', () => {
    const result = add(5, 7);
    snapshot(result); // First snapshot will create __snapshots__/spec.js with '12'
    expect(result).to.equal(12);
  });

  it('handles strings as snapshots', () => {
    const message = "Hello, snapshot world!";
    snapshot(message); // Second snapshot 'Hello, snapshot world!'
    expect(message).to.be.a('string');
  });

  it('can snapshot asynchronous results', async () => {
    const asyncResult = await Promise.resolve({
      id: 1,
      name: 'Async Data',
      timestamp: new Date('2023-01-01T00:00:00Z')
    });
    snapshot(asyncResult); // Third snapshot with object
    expect(asyncResult.id).to.equal(1);
  });

  // Data-driven testing example
  ['foo', 'bar', 'baz'].forEach((value) => {
    it(`processes value ${value}`, () => {
      snapshot(`processed-${value}`); // Snapshots will be named "processes value foo 1", "processes value bar 1", etc.
    });
  });
});

// To run:
// 1. npm install mocha chai snap-shot-it --save-dev
// 2. Add the 'test' script to package.json
// 3. Run: npm test
// 4. To update snapshots: SNAPSHOT_UPDATE=1 npm test