Approvals (Approval Tests for Node.js)

<!-- toc -->

Contents

• Intro
• Badges
• Integrations
• Getting Started
  • Jest Typescript Starter Project
  • Mocha
• Documentation
• CLI
  • Install Approvals CLI
  • CLI Help
• 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) ⇒ <code>Object</code>
  • 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<!-- endToc -->

<a name="intro" />

Intro

Approval Tests Library - Capturing Human Intelligence

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

<a name="build-details" />

Badges

| Service | Status | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Package | | | Github (Linux, Mac, Windows) | |

<a name="integrations" />

Integrations

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

<a name="getting-started" />

Getting Started

Jest Typescript Starter Project

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 approvals
   

3. Install Mocha globally to execute our tests

   npm install -g mocha
   

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

   require("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.

   mocha SimpleLogger.test.js
   

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

<a name="documentation">

Documentation

If using Jest, see more documentation here.

<a name="cli">

CLI

Approvals.NodeJS has a version that can be run as a command line tool.

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 approvals

CLI Help

By running approvals --help

<!--BEGIN-CLI-DOCS--> <!-- GENERATED - DO NOT MODIFY API DOCS IN THIS README --> <!-- Update docs in the source ./bin/help.md -->

# Usage

`approvals testName [options]`

| Arg                       | Description                                                                                                                                                                     |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| \*\*[-f                   | --forceapproveall]\*\*                                                                                                                                                          | Skip the approve step and apply the results to the .approved.txt file (good for a first time run) |
| [--reporter difftool] | supports multiple EX: `--reporter opendiff --reporter gitdiff`                                                                                                                  |
| [--outdir]            | dir to place approval file - defaults to current directory                                                                                                                      |
| [--verbose]           | extra debug info                                                                                                                                                                |
| TODO:                 | We need to extend the supported args to include other approval options. (file an [issue](https://github.com/approvals/Approvals.NodeJS/issues) if you need one that's not here) |

# 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

<!--END-CLI-DOCS--> <a name="reporters" />

Reporters

Built-In Reporters

Any of the following reporter may suite your needs. Some support images, some only diffing text, some on mac and linux, some only on windows... Feel free to configure the system to automatically choose your favorite.

Supported Diff Tools

| approval name | Program | Windows | Mac/Linux | Notes | | --------------- | ---------------------------------------------------------------------------------------------------------------- | :------: | :-------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | beyondcompare | Beyond Compare | ✓ | ✓ | | | copycommand | git diff (console diff) | ✓ | ✓ | Great for C.I. builds runs. | | diffmerge | DiffMerge | ✓ | ✓ | | | donothing | | ✓ | ✓ | This one does what it says - nothing.