Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    approvalspublic

    Approvals (Approval Tests for Node.js)

    Table of Contents

    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.

    Builds

    Service Status
    Linux (Travis CI) Build Status
    Windows (AppVeyor) Build status
    Greenkeeper Greenkeeper badge

    Integrations

    • Mocha tests, see the getting-started
    • Jasmine tests (removed support due to lack of integration knowledge)
    • [Approvals API](https://github.com/approvals/Approvals.NodeJS/ /Manual-API) (require('approvals').verify(...))
    • Command line Utility

    Getting Started

    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 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 test.js
    6. You should be presented with a diff tool. (if not, you may need to install one?)

    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

    
    # Usage
    
    `approvals testName [options]`
    
            [-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
    
    

    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.
    gitdiff git diff (console diff) Using git cli to diff files. Useful in C.I. builds
    icdiff Icdiff
    kdiff3 KDiff3
    kompare Kompare ?
    meld Meld
    multi This allows you to run multiple reporters at the same time. EX: when verifying images, you might like to use p4merge along with the copycommand reporter to get the copy CLI command to approve an image as well as view the diff in a tool.
    nodediff nodediff (console diff) colorized CLI output without a popup of a diff tool
    opendiff opendiff
    p4merge p4merge
    tortoisemerge Tortise merge
    vimdiff
    visualstudio Visual Studio Diff tool

    Custom Reporter

    Along with the built-in reporters, you can create your own custom reporter just by taking this sample and filling out the interface with your custom reporters desired behavior.

        /* 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
          }
        }
    

    Configuration

    Or more, controlling the behavior of approvals through various tweaks to configuration.

    Approvals uses the below configuration to drive its behavior. How you communicate that configuration to approvals can happen in several ways.

    The default configuration as defined below can be overridden by using the following strategy.

    NOTE: Priority/order of config selection comes from the below list where the first item have the defined defaults and each next step having a potential to override the previous if a configuration value is specified.

    1. Starting with the defaults (as shown in the JS object below) this is defined in lib/config.js.
    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. Overrides with an approvals.configure({...}) (not a recommended approach).
    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('approvals');
    var MultiReporter = approvals.reporters.MultiReporter
     
    it("should use a multiple reporters", function () {
      this.verify('some data', {
        reporters: [
          new MultiReporter(['p4merge', 'commandclipboard'])
        ]
      });
    });
    var defaultConfig = {
      // The strategy for determining which reporter to use will likely
      // change at some point. For now, you can configure priority here.
      // What I'd prefer is if each project has a configuration file
      // and each user could setup a ~/.approvalConfig file
      // which would contain their preferred merge/diff tools
      reporters:  [
        "opendiff",
        "p4merge",
        "tortoisemerge",
        "nodediff",
        "gitdiff"
        /* OR a custom reporter object. See the above example of how to create a custom reporter. */
      ],
     
      // If you need to normalize text file line-endings
      // you can set this to something like "\n" or "\r\n"
      //
      // default value here of false or undefined will not apply any
      // line-ending replacement before writing the approval received file
      normalizeLineEndingsTo: false, // default
     
      // If approvals determines things are different, it will replacement
      // line endings CRLF with just LF and re-compare. If they are the same
      // approvals will log a warning that the files are the same except for
      // line endings. Flip this to `true` to fail tests if line-endings
      // are different
      failOnLineEndingDifferences: false,
     
      // Some diff tools automatically append an EOL to a merge file
      // Setting this to true helps with those cases... (Also see EOL below
      // for what is appended)
      appendEOL: true,
     
      // When appendEOL above is true, this value defines what will be appended at the end of the file.
      // It's really a bad name as it's not End-of-Line... but -end-of-file err end-of-line-at-end-of-file :P
      EOL:  require('os').EOL,
     
      // This helps keep the project clean of files
      // that became stale due to removal of tests
      // or after a rename
      errorOnStaleApprovedFiles: true,
     
      // This is a function called when the proc is exiting and we're
      // validating any stale *.approved.txt files. You can override
      // this function to ignore validation of some files or not
      shouldIgnoreStaleApprovedFile: function(/*fileName*/) { return false; },
     
      // On some files or projects a Byte Order
      // Mark can be inserted and cause issues,
      // this allows you to force it to be stripped
      stripBOM: false
     
      //DANGER: this can be used to force-approve a file during a test run.
      // Can be used for first time-run or if lots of tests are failing because
      // of a change you know is correct. AGAIN DANGER - don't ever check code
      // in that configures this to be on...)
      forceApproveAll: false
     
    };

    API

    approvals

    Approvals module.

    approvals.configure

    Allows you to provide overrides to the default configuration.

    Kind: static property of approvals

    Param Type
    overrideOptions *

    Example

    var approvals = require('approvals');
    approvals.configure({
      reporters: ['p4merge']
    });

    approvals.getConfig ⇒ Object

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

    Kind: static property of approvals Returns: Object - approvals config object with any options overridden.

    Param Type
    overrideOptions Object

    approvals.verify

    Kind: static property of approvals

    Param Type Description
    dirName string Typically __dirname but could be the base-directory (anywhere) to store both approved and received files.
    testName string A file name save string to call the file associated with this test.
    data string | Buffer Either the string to save as a text file or a Buffer that represents an image
    optionsOverride * An object that can contain configurational overrides as defined in the approvals configuration object.

    Example

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

    Example

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

    approvals.verifyAndScrub

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

    Kind: static property of approvals

    Param Type Description
    dirName string Typically __dirname but could be the base-directory (anywhere) to store both approved and received files.
    testName string A file name safe string to call the file associated with this test.
    data string | Buffer Either the string to save as a text file or a Buffer that represents an image
    scrubber * A function that takes a string and returns a string. Approvals will call this if it exists to scrub the "data" before writing to any files.
    optionsOverride * An object that can contain configurational overrides as defined in the approvals configuration object.

    Example

    // basic approval test with a custom scrubber
    var approvals = require('approvals');
    var 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.verifyAsJSON

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

    Kind: static property of approvals

    Param Type Description
    dirName string Typically __dirname but could be the base-directory (anywhere) to store both approved and received files.
    testName string A file name safe string to call the file associated with this test.
    data string | Buffer This can be any JavaScript object/array that will be JSON.stringified before running verify
    optionsOverride * An object that can contain configurational overrides as defined in the approvals configuration object.

    Example

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

    approvals.verifyAsJSONAndScrub

    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: static property of approvals

    Param Type Description
    dirName string Typically __dirname but could be the base-directory (anywhere) to store both approved and received files.
    testName string A file name safe string to call the file associated with this test.
    data string | Buffer This can be any JavaScript object/array that will be JSON.stringified before running verify
    scrubber * A function that takes a string and returns a string. Approvals will call this if it exists to scrub the "data" before writing to any files.
    optionsOverride * An object that can contain configurational overrides as defined in the approvals configuration object.

    Example

    // basic approval test with a custom scrubber
    var approvals = require('approvals');
    var 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

    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/readmeTests.js in this project.

    Kind: static property of approvals

    Param Type
    namer Object
    writer Object
    [reporterFactory] function
    [optionsOverride] Object

    approvals.mocha

    Configure approvals to hook into Mocha tests.

    Kind: static property of approvals

    Param Type Description
    optionalBaseDir * An optional folder to save approval files to.

    approvals.reporters

    reporters gives access to the MultiReporter

    Kind: static property of approvals Example

    var MultiReporter = approvals.reporters.MultiReporter

    approvals.scrubbers

    Contains some helpful and util scrubbers that can be used for scrubbing data before saving to a received file.

    Kind: static property of approvals

    Source Control

    The approvals tool generates 2 files and you likely want to ignore one and check in the other.

    • *.received.* files should be IGNORED.
    • *.approved.* You'll likely want to keep the approved files in source control.

    Git

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

    *.received.*

    Another issue that can crop up is the line-endings as git can change the files depending on checking out the file on linux/mac vs windows.

    A possible fix for this is to add *.approved.* binary to your .gitattributes (but that makes viewing diffs as you check in a pain).

    Contributing

    Check out the guidelines!

    License

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

    install

    npm i approvals

    Downloadsweekly downloads

    262

    version

    2.1.2

    license

    Apache-2.0

    repository

    githubgithub

    last publish

    collaborators

    • avatar