npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

karma-snapshot

v0.6.0

Published

Karma plugin for snapshot testing.

Downloads

14,609

Readme

Karma Plugin for Snapshot Testing

karma-snapshot provides a communication layer between browser and Karma to store and retrieve snapshots.

karma-snapshot Example

Supported Assertion Libraries

Snapshot Format

Snapshot can be stored in different formats. Right now there are two formats supported: md and indented-md.

Markdown Format

This format is preferred when you specify language for code blocks in an assertion plugin. With this format, code editors will automatically highlight syntax of code blocks.

# `src/html.js`

## `Sub Suite`

####   `HTML Snapshot`

```html
<div>
  <span />
</div>
```

Indented Markdown Format

# `src/html.js`

## `Sub Suite`

####   `HTML Snapshot`

    <div>
      <span />
    </div>

Snapshot File Path

Snapshot file path is extracted from the name of the root suit cases and stored alongside with a tested files in a __snapshots__ directory.

Snapshot file path can be changed by providing a custom pathResolver in snapshot config.

Usage Example with Mocha and Chai

$ npm install karma karma-webpack karma-sourcemap-loader karma-snapshot karma-mocha \
              karma-mocha-snapshot karma-mocha-reporter karma-chrome-launcher mocha \
              chai chai-karma-snapshot webpack --save-dev

Karma configuration:

// karma.conf.js
const webpack = require("webpack");

module.exports = function (config) {
  config.set({
    browsers: ["ChromeHeadless"],
    frameworks: ["mocha", "snapshot", "mocha-snapshot"],
    reporters: ["mocha"],
    preprocessors: {
      "**/__snapshots__/**/*.md": ["snapshot"],
      "__tests__/index.js": ["webpack", "sourcemap"]
    },
    files: [
      "**/__snapshots__/**/*.md",
      "__tests__/index.js"
    ],

    colors: true,
    autoWatch: true,

    webpack: {
      devtool: "inline-source-map",
      performance: {
        hints: false
      },
    },

    webpackMiddleware: {
      stats: "errors-only",
      noInfo: true
    },

    snapshot: {
      update: !!process.env.UPDATE,
      prune: !!process.env.PRUNE,
    },

    mochaReporter: {
      showDiff: true,
    },

    client: {
      mocha: {
        reporter: "html",
        ui: "bdd",
      }
    },
  });
};

Source file:

// src/index.js

export function test() {
  return "Snapshot Test";
}

Test file:

// __tests__/index.js
import { use, expect, assert } from "chai";
import { matchSnapshot } from "chai-karma-snapshot";
import { test } from "../src/index.js";
use(matchSnapshot);

describe("src/index.js", () => {
  it("check snapshot", () => {
    // 'expect' syntax
    expect(test()).to.matchSnapshot();
    // 'assert' syntax
    assert.matchSnapshot(test());
  });
});

Run tests:

$ karma start

Update snapshots:

$ UPDATE=1 karma start --single-run

Prune snapshots:

$ PRUNE=1 karma start --single-run

Config

function resolve(basePath, suiteName) {
  return path.join(basePath, "__snapshots__", suiteName + ".md");
}

config.set({
  ...
  snapshot: {
    update: true,           // Run snapshot tests in UPDATE mode (default: false)
    prune: false,           // Prune unused snapshots (default: false)
    format: "indented-md",  // Snapshot format (default: md)
    checkSourceFile: true,  // Checks existince of the source file associated with tests (default: false)
    pathResolver: resolve,  // Custom path resolver,
    limitUnusedSnapshotsInWarning: -1  // Limit number of unused snapshots reported in the warning
                                       // -1 means no limit

  }
});

Custom Snapshot Format

Snapshot config option format also works with custom serialization formats. Custom snapshot serializer should have interface:

interface SnapshotSerializer {
  serialize: (name: string, suite: SnapshotSuite) => string,
  deserialize: (content: string) => { name: string, suite: SnapshotSuite },
}

Internals

Snapshot Data

karma-snapshot plugin is communicating with a browser by assigning a global variable __snapshot__ on a window object.

Snapshot data has a simple data structure:

declare global {
  interface Window {
    __snapshot__: SnapshotState;
  }
}

interface SnapshotState {
  update?: boolean;
  suite: SnapshotSuite;
}

interface SnapshotSuite {
  children: { [key: string]: SnapshotSuite };
  snapshots: { [key: string]: Snapshot[] };
  visited?: boolean;
  dirty?: boolean;
}

interface Snapshot {
  lang?: string;
  code: string;
  visited?: boolean;
  dirty?: boolean;
}

When SnapshotState.update variable is true, it indicates that assertion plugin should run in update mode, and instead of checking snapshots, it should update all values.

SnapshotState.suite is a reference to the root suite.

SnapshotSuite is a tree with snapshots that has a similar structure to test suites. children property is used to store references to children suites, and snapshots is used to store snapshot lists for tests in the current snapshot. Snapshots are stored as a list because each test can have multiple snapshot checks, and they should be automatically indexed by their position.

Snapshot is an object that stores details about snapshot. lang property indicates which language should be used in a markdown format to improve readability. code property stores snapshot value that will be checked by an assertion plugin.

visited is a flag that should be marked by an assertion plugin when it visits suites and snapshots. Visited flags are used to automatically prune removed snapshots.

dirty is a flag that should be marked by an assertion plugin when it updates or adds a new snapshot.

Interface for Assertion Libraries

To make it easier to add support for assertion libraries, SnapshotState has two methods that should be used when creating an API for an assertion library.

interface SnapshotSuite {
  get(path: string[], index: number): Snapshot | undefined;
  set(path: string[], index: number, code: string, lang?: string): void;
  match(received: string, expected: string): boolean;
}

get() method tries to find a Snapshot in a current snapshot state. It also automatically marks all nodes on the path as visited.

set() method adds or updates an existing Snapshot.

match() method checks if two snapshots are matching in normalized form.

Here is an example how it should be used:

function matchSnapshot(path: string[], index: number, received: string) {
  if (snapshotState.update) {
    snapshotState.set(path, index, received);
  } else {
    const snapshot = snapshotState.get(path, index);
    if (!snapshot) {
      snapshotState.set(path, index, received);
    } else {
      const pass = snapshotState.match(received, snapshot.code);
      if (!pass) {
        throw new AssertionError(`Received value does not match stored snapshot ${index}`);
      }
    }
  }
}