mocha-snap
    TypeScript icon, indicating that this package has built-in type declarations

    4.3.0 • Public • Published


    mocha-snap
    TypeScript Styled with prettier Build status NPM Version Downloads

    Snapshot testing for Mocha with support for both file & inline snapshots.

    Installation

    npm install mocha-snap

    Setup

    This package exposes a Mocha root hook plugin that must be loaded before any snapshots can execute. It handles writing updated files to disk and cleaning up.

    When running the Mocha CLI, provide --require mocha-snap to enable the hook. Alternatively you can add the require option to your .mocharc to look something like:

    {
      "require": ["mocha-snap"]
    }

    Inline snapshots

    Example

    import snap from "mocha-snap";
    
    it("takes a snapshot", async () => {
      await snap.inline({
        hello: "world",
      });
    });

    The above will format the data passed to snap.inline and update the test file to pass the expected content in as the second argument. This will then update the test to include the following:

    await snap.inline(
      {
        hello: "world",
      },
      `{ hello: "world" }`
    );

    After that point the expected and actual values are compared and an error is thrown if there is no match. You can update the snapshot from the cli.

    File snapshots

    Example

    import snap from "mocha-snap";
    
    it("takes a snapshot", async () => {
      await snap({
        hello: "world",
      });
    });

    The above will format the data passed to snap and save it to %TEST_DIRECTORY%/__snapshots__/takes-a-snapshot.expected.txt. If the snapshot file already exists, it will be compared with the current content and an error is thrown if there is no match. You can update the snapshot from the cli.

    Custom file name output

    The second parameter to mocha-snap is the name property which can override the default .txt file extension for the output snapshots (except when an error occurs).

    It can be useful to create utility functions for snapshotting different types of data to both normalize it, and provide the file extension.

    Below we create simple JSON and HTML snapshot wrappers.

    import snap from "mocha-snap";
    
    const snapHTML = (val) => snap(val, ".html");
    const snapJSON = (val) => snap(JSON.stringify(val), ".json");
    
    it("takes an html snapshot", async () => {
      await snapHTML("<h1>Hello World!</h1>");
    });
    
    it("takes a json snapshot", async () => {
      await snapJSON({ hello: "world" });
    });

    The name property can also be a file path which will be created within a snapshot folder with the name of the current test.

    it("takes a nested snapshot", async () => {
      await snap("Hello", "part-1.txt"); // Outputs a folder snapshot with a "part-1.txt" file.
      await snap("World", "part-2.txt"); // Adds another file ("part-2.txt") to the the above snapshot folder.
      await snap("!", "nested/part-3.txt"); // Creates another folder within the output ("nested") with the file "part-3.txt".
    });

    When multiple snapshots would have the same resolved file name, the test name is prefixed with an incrementing id. This means the following is also perfectly fine.

    it("takes a nested snapshot", async () => {
      await snap("Hello"); // outputs as normal
      await snap("World"); // outputs with a `.1` prefix
    });

    Custom __snapshots__ folder

    By default the __snapshots__ folder is created in the same directory as the running test, but you can override this by passing in the third parameter dir.

    it("puts snapshot somewhere else", async () => {
      await snap("Hello", ".md", process.cwd()); // Put the snapshot in the project root, instead of beside this test.
    });

    Output files

    Unlike some snapshotting tools this module outputs an individual file per snapshot call. This makes it easier to analyze, diff and manage the individual snapshots.

    Output snapshots match the following format: %TEST_DIRECTORY%/__snapshots__/<TEST_NAME><ACTUAL_OR_EXPECTED><NAME>.

    • TEST_DIRECTORY: the folder the current test is in.
    • TEST_NAME: a file friendly name for the current test test. Each parent suite will create a new nested directory.
    • ACTUAL_OR_EXPECTED: will be .expected when updating a test, and .actual when a test has failed the comparison. When there is an error this will become .expected.error and .actual.error.
    • NAME: If the name is a file extension (eg .json) it is appended directly to the test file, otherwise it will be joined by a path separator allowing (eg result.json will output a file in the current test folder called result.json).

    An example output file might look like src/my-component/__tests__/__snapshots__/my-test-suite/my-test-name.expected.txt.

    Updating

    Run your test command with --update. If the snapshot was previously empty it is auto saved, even without --update being used.

    mocha --update
    

    Or set the UPDATE_SNAPSHOTS environment variable.

    UPDATE_SNAPSHOTS=1 mocha
    

    Serializing snapshots

    If a string is passed to one of the snapshot api's that string will be saved as the raw snapshot content. If anything else is passed it is first serialized using using util.inspect.

    Catching errors

    You can also pass a function the snapshot api which will execute the function, await any returned promises, and snapshot the resolved value.

    The useful part here is that during that function execution all errors (including uncaught ones) are tracked. If there are any errors before we take the snapshot, the entire snapshot will error.

    When updating with a snapshot that has errored it will instead snapshot all errors. This allows you to snapshot test your errors, in aggregate.

    it("should throw some exceptions", async () => {
      await snap(async () => {
        setTimeout(() => {
          throw new Error("Fail during snapshot!");
        }, 100);
        await sleep(1000);
        return "success";
      });
    });

    Install

    npm i mocha-snap

    DownloadsWeekly Downloads

    64

    Version

    4.3.0

    License

    MIT

    Unpacked Size

    54.2 kB

    Total Files

    42

    Last publish

    Collaborators

    • dylanpiercey