Approvals (Approval Tests for Node.js)

Contents

• Intro
• Badges
• Integrations
• Getting Started
  • Jest Typescript Starter Project
  • Mocha
• Documentation
• CLI
  • Install Approvals CLI
  • CLI Help
    • Usage
    • Examples
      • Simple hello world
      • Specify diff reporter (great for C.I.)
      • Multiple diff reporters
• Reporters
  • Built-In Reporters
• Supported Diff Tools
  • Custom Reporter
• Configuration
• API
• approvals
  • approvals.reporters
    • reporters.MultiReporter
  • approvals~configure(overrideOptions)
  • approvals~getConfig(overrideOptions) ⇒ Object
  • approvals~mocha(optionalBaseDir)
  • approvals~verifyAndScrub(dirName, testName, data, scrubber, optionsOverride)
  • approvals~verify(dirName, testName, data, optionsOverride)
  • approvals~verifyAsJSON(dirName, testName, data, optionsOverride)
  • approvals~verifyAsJSONAndScrub(dirName, testName, data, scrubber, optionsOverride)
  • approvals~verifyWithControl(namer, writer, [reporterFactory], [optionsOverride])
• Source Control
  • Git
• Contributing
• License

What is an approval test? Check out a brief overview here or learn more about Approvals at approvaltests.com.

Badges

Service	Status
Package	@approval-tests/approvals on npm
Github (Linux, Mac, Windows)

• Mocha tests, see the getting-started
• Approvals API (require('@approval-tests/approvals').verify(...))
• Command line Utility

If you want to jump start a new project, clone the Jest Starter Project

Mocha

Below is a simple getting started using Mocha.

1. Create a project (folder)

   mkdir MyProject
   cd MyProject
   

2. Install approvals

   npm install --save-dev @approval-tests/approvals
   

3. Install Mocha in the project to execute our tests

   npm install --save-dev mocha
   

4. Create a sample Mocha test file called SimpleLogger.test.js.

   require("@approval-tests/approvals").mocha();
   
   describe("When running some tests", function () {
     it("should be able to use Approvals", function () {
       var data = "Hello World!";
       this.verify(data); // or this.verifyAsJSON(data)
     });
   });
   

5. Test the file with mocha.

   npx mocha SimpleLogger.test.js
   

6. You should be presented with a diff tool. (if not, you may need to install one?)

If using Jest, see more documentation here.

You can check out the Examples section of the below CLI help. Or a blog post introducing the tool here: Approval Tests - Command Line Tool (CLI).

Install Approvals CLI

npm install -g @approval-tests/approvals

CLI Help

By running approvals --help

Usage

approvals testName [options]

Examples

Simple hello world

echo 'Hello World!' | approvals helloWorldTest

Specify diff reporter (great for C.I.)

echo 'Hello World!' | approvals helloWorldTest --reporter gitdiff

Multiple diff reporters

echo 'Hello World!' | approvals helloWorldTest --reporter gitdiff --reporter p4merge

    /* OR a custom reporter object. Below is an example custom reporter */
    {
      /**
       * Determine if the file that needs to be reported on can be handled by this reporter object.
       * @param {string} receivedFilePath - The path to a received file.
       */
      canReportOn(receivedFilePath) {
        return true;
      }

      /**
       * Apply the logic necessary to report a difference.
       *  EX:
       *     - Open a diff program using the approved & received files
       *     - Generate and email a report showing the differences.
       * @param {string} approvedFilePath - The path to an approved file.
       * @param {string} receivedFilePath - The path to a received file.
       */
      // Actually execute the diff against the two files
      report(approvedFilePath, receivedFilePath) {
        // Do some reporting.
        // Typically by launching a diff tool
      }
    }

1. Starting with the defaults (as shown in the JS object below) this is defined in lib/config.ts.
2. We then take and override the defaults (and only the properties specified) with config in a yaml or json file in your home directory ~/.approvalsConfig.
3. You can then call approvals.configure({...}).
4. Then passing any specific configuration at the test level as the last parameter in the verify function .verify(..., {...overridden config...});. See API for specific parameters.

Here's an example of using a single reporter p4merge, and overriding whatever is configured. This will only override this specific test.

it("should use a specific reporter", function () {
  this.verify("some data", {
    reporters: ["p4merge"],
  });
});

If you have the need to execute multiple reporters on a single failure.

Say you made an "awesomeDiffReporter" and wanted it to run that in combination with a "notifyTheBossViaEmailReporter" you can use the MultiReporter like below.

var approvals = require("@approval-tests/approvals");
var MultiReporter = approvals.reporters.MultiReporter;

it("should use a multiple reporters", function () {
  this.verify("some data", {
    reporters: [new MultiReporter(["p4merge", "copycommand"])],
  });
});

export const defaultConfig: Config = {
  reporters: [
    "BeyondCompare",
    "diffmerge",
    "p4merge",
    "tortoisemerge",
    "nodediff",
    "opendiff",
    "gitdiff",
  ],
  normalizeLineEndingsTo: false,
  failOnLineEndingDifferences: false,
  appendEOL: true,
  EOL: os.EOL,
  errorOnStaleApprovedFiles: true,
  shouldIgnoreStaleApprovedFile: () => false,
  stripBOM: false,
  forceApproveAll: false,
  blockUntilReporterExits: false,
  maxLaunches: 10,
};

^{snippet source | anchor}

approvals

Approvals module.

• approvals
  • static
    • .reporters
      • .MultiReporter
  • inner
    • ~configure(overrideOptions)
    • ~getConfig(overrideOptions) ⇒ Object
    • ~mocha(optionalBaseDir)
    • ~verifyAndScrub(dirName, testName, data, scrubber, optionsOverride)
    • ~verify(dirName, testName, data, optionsOverride)
    • ~verifyAsJSON(dirName, testName, data, optionsOverride)
    • ~verifyAsJSONAndScrub(dirName, testName, data, scrubber, optionsOverride)
    • ~verifyWithControl(namer, writer, [reporterFactory], [optionsOverride])

approvals.reporters

reporters gives access to the MultiReporter

Kind: static property of approvals Example

const MultiReporter = approvals.reporters.MultiReporter

reporters.MultiReporter

This allows access to the MultiReporter constructor. You can use this to run multiple reporters at the same time.

Kind: static property of reporters Example

approvals.verify(__dirname, "multi-reporter-example", "some data", {
  reporters: [
    new MultiReporter('p4merge', 'copycommand')
  ]
});

approvals~configure(overrideOptions)

Allows you to provide overrides to the default configuration.

Kind: inner method of approvals

Example

const approvals = require('@approval-tests/approvals');
approvals.configure({
  reporters: ['p4merge']
});

approvals~getConfig(overrideOptions) ⇒ Object

Allows the creation of an approvals configuration object using any passed in options to override the defaults.

Kind: inner method of approvals Returns: Object - approvals config object with any options overridden.

approvals~mocha(optionalBaseDir)

Configure approvals to hook into Mocha tests.

Kind: inner method of approvals

approvals~verifyAndScrub(dirName, testName, data, scrubber, optionsOverride)

Use this to apply the scrubber function to any data before running verify.

Kind: inner method of approvals

Example

// basic approval test with a custom scrubber
const approvals = require('@approval-tests/approvals');
const scrubber = approvals.scrubbers.multiScrubber([
   function (data) {
     return (data || '').replace("some text", "some other text");
   },
   approvals.scrubbers.guidScrubber // to remove guids from the received data
});
approvals.verifyAndScrub(__dirname, 'sample-approval-test', "some text to verify", scrubber);

approvals~verify(dirName, testName, data, optionsOverride)

Kind: inner method of approvals

Example

// basic approval test
const approvals = require('@approval-tests/approvals');
approvals.verify(__dirname, 'sample-approval-test', "some text to verify");

Example

// basic approval test providing an option to override configuration
const approvals = require('@approval-tests/approvals');
approvals.verify(__dirname, 'sample-approval-test', "some text to verify", { normalizeLineEndingsTo: true });

approvals~verifyAsJSON(dirName, testName, data, optionsOverride)

You can pass as "data" any javascript object to be JSON.stringified and run verify against.

Kind: inner method of approvals

Example

const approvals = require('@approval-tests/approvals');
approvals.verifyAndScrub(__dirname, 'sample-approval-test', { a: "some text in an object" });

approvals~verifyAsJSONAndScrub(dirName, testName, data, scrubber, optionsOverride)

You can pass as "data" any javascript object to be JSON.stringified. Before we run verify the scrubber will be run against the complete string before running verify against it.

Kind: inner method of approvals

Example

// basic approval test with a custom scrubber
const approvals = require('@approval-tests/approvals');
const scrubber = approvals.scrubbers.multiScrubber([
   function (data) {
     return (data || '').replace("some text", "some other text");
   },
   approvals.scrubbers.guidScrubber // to remove guids from the received data
});
approvals.verifyAndScrub(__dirname, 'sample-approval-test', { a: "some text in an object" }, scrubber);

approvals~verifyWithControl(namer, writer, [reporterFactory], [optionsOverride])

This allows you to take full control of naming and writing files before verifying.

For an example that we use to generate the docs within the readme, check out the test/mocha/readmeTests.mts in this project.

Kind: inner method of approvals

If you're using Git add this to your .gitignore:

*.received.*

Depending on your operating system and your eol settings in git, the diff output on a failed test might report each line as changed because of differences in line endings. To avoid this, consider fixating eol conversion to crlf for approved files by adding this line to your .gitattributes file:

*.approved.* eol=lf

Check out the guidelines!

License

Copyright (c) 2012-2017 Llewellyn Falco, Jason Jarrett Licensed under the Apache license.