Nervous Parrot Muttering

    snapshotgun

    1.0.1 • Public • Published

    snapshotgun

    Command line tool for automatically generating Jest snapshot tests.

    Takes a single test executor JavaScript file and a set of testcase directories and creates a JavaScript test file under each bottom level directory, automatically importing the found test files and the given executor.

    License Build Status Coverage Status npm version

    Table of contents

    Installation (npm)

    It is recommended that snapshotgun is installed globally, as it is not required as a dependency after it has been run.

    NPM

    $ npm install snapshotgun --global

    Yarn

    $ yarn global add snapshotgun

    Usage

    Generating testcases

    Snapshotgun is run from the command line with either:

    $ snapshotgun

    or its alias:

    $ ssgun

    By default, it expects to find a single JavaScript file in the current directory that it uses as the test executor. If multiple candidates, or no candidate files are found, the process terminates with failure code.

    Snapshotgun scans the current directory for test directories containing JSON files. If no directories are found, the process terminates with failure code.

    As the testcase directories are recursively scanned, snapshotgun generates a Jest snapshot test file whenever it finds a bottom level directory that contains at least some JSON files.

    For example running in the following directory:

    * testcases
      * first_test
        * input.json
      * second_test
        * input.json
    * executor.adapter.js
    

    would generate tests like so:

    * testcases
      * first_test
        * input.json
        * first_test.test.js
      * second_test
        * input.json
        * second_test.test.js
    * executor.adapter.js
    

    Snapshotgun automatically imports the given test executor as well as the found test JSON files to the testcases:

    import execute from "./../executor.adapter.js";
    import input from "./input.json";
     
    const files = {
      input
    };
     
    it("first_test", () => {
      try {
        expect(execute(files)).toMatchSnapshot();
      } catch (error) {
        expect(error).toMatchSnapshot();
      }
    });

    Once the test files have been generated, the project can be tested with Jest as usual. When the tests are run for the first time, Jest generates snapshot files alongside them, containing the output of the executor. Subsequent test runs will check the output against the previous snapshots.

    You should always verify that the first time generated snapshots match the expected output

    Test executor

    Snapshotgun requires a test executor in order to generate testcases that test the intended functionality. The executor acts as an 'adapter' between your code and snapshotgun, which is imported in the testcases, instead of the actual code.

    A test executor must contain a function default export, that receives an object containing all found test files as its sole argument:

    ES6

    export default files = myTestedFunction(files);

    CommonJS

    module.exports.default = function(files) {
      return myTestedFunction(files);
    };

    In most cases your tested function expects a specific input, so you'll have to unwrap the correct files before passing them on.

    Test directories

    Snapshotgun iterates recursively over all directories in the given test directory structure. The test directories can contain any files, but only JSON files will be scanned.

    Whenever the iteration reaches a bottom level directory, a test file is created and all found test files in the scope of that directory are linked to it.

    For example:

    * testcases
      * suite
        * first_test
          * input.json
        * second_test
          * input.json
      * test
        * input.json
    

    would generate three tests: first_test, second_test and test.

    The files found in directories are passed on to lower level directories, so you can create common files for multiple tests. Tests can also overwrite the files passed from their parent.

    For example:

    * testcases
      * data.json
      * first_test
        * input.json
      * second_test
        * input.json
      * third_test
        * input.json
        * data.json
    

    would create three tests, where the two first tests would use the common data.json from their parent directory, but the third test would overwrite it with its own.

    Tests inherit all JSON files in the file structure in this way. Naturally, the files need to be valid JSON, including objects, arrays, numbers and strings.

    Expecting errors

    If your testcase throws an error, the generated test will attempt to match that error against the existing snapshot.

    Thus, if your test throws an error the first time it is run, the snapshot will contain an error from there on.

    This is why it is extremely important to verify the generated snapshots rather than blindly trusting they are correct

    Filtering tests

    Tests can be filtered with Jest's pattern matching:

    jest -t <my-test-pattern>

    Each generated testcase is checked against the given pattern and run only if it matches.

    Another option is to manually add a 'skip' or 'only' suffix to the test name.

    Options

    Snapshotgun's behavior can be customized with command line options:

    Testcase executor

    -e, --exec string     Testcase executor path
    

    If an executor path is given, that specific executor will be used instead of scanning the current directory

    Testcase directory

    -d, --dir string      Testcase directory path
    

    If a testcase directory path is given, that specific testcase directory will be used instead of scanning the current directory.

    Target directory

    -t, --target string   Target directory path for generated tests
    

    If target directory path is given, the generated tests will be placed under that directory instead of the testcase file structure.

    Mode

    -m, --mode string     Generation mode: single or multi.
    

    Determines the generation mode. Single mode generates a single test case for each bottom level directory, while multi mode generates one for each file found in that directory. Uses single mode by default

    Note: When using multi generation mode, the executor receives the single input file as its first argument and the rest of found test files as its second argument:

    export default (input, file) = myTestedFunction(input, file);

    Overwrite

    --overwrite           Overwrite existing tests in target directories
    

    If given, overwrites any of the test files that already exist. Otherwise, they are skipped.

    Dry run

    --dry-run             Run without actually writing files
    

    Runs the process without writing any files.

    Verbose

    --dry-run             Run without actually writing files
    

    Prints more detailed output during test generation

    Format

    -f, --format          string Test format: cjs or es6
    

    Determines the format in which the generated test files should be. Uses es6 by default.

    Help

    -h, --help            Display this usage guide
    

    Install

    npm i snapshotgun

    DownloadsWeekly Downloads

    7

    Version

    1.0.1

    License

    Apache-2.0

    Unpacked Size

    241 kB

    Total Files

    87

    Last publish

    Collaborators

    • vjrasane