@timkendrick/scenario-builder

Unit test scenario builder for JavaScript projects

Write comprehensive unit test suites quickly and declaratively without any of the repetitive boilerplate.

Installation

npm install @timkendrick/scenario-builder --save-dev

Example

sum.spec.js:

const scenarioBuilder = require('@timkendrick/scenario-builder');

// Function to test
const sum = require('./sum');

describe('sum', () => {
  // Create a pre-bound test runner that calls the function with test input
  const runScenario = scenarioBuilder((input) => sum(...input));

  // Use the test runner to run test assertions
  runScenario('sum()', { input: [], expected: 0 });
  runScenario('sum(0)', { input: [0], expected: 0 });
  runScenario('sum(1)', { input: [1], expected: 1 });
  runScenario('sum(1, 2, 3)', { input: [1, 2, 3], expected: 6 });
  runScenario('sum(-1, -2, -3)', { input: [-1, -2, -3], expected: -6 });
  runScenario('sum(Infinity, 1)', { input: [Infinity, 1], expected: Infinity });
  runScenario('sum(NaN, 1)', { input: [NaN, 1], expected: NaN });
});

Console output:

$ jest sum.spec.js

 PASS  ./sum.spec.js
  sum
    sum()
      ✓ SHOULD return the correct results (2ms)
    sum(0)
      ✓ SHOULD return the correct results (1ms)
    sum(1)
      ✓ SHOULD return the correct results (1ms)
    sum(1, 2, 3)
      ✓ SHOULD return the correct results (1ms)
    sum(-1, -2, -3)
      ✓ SHOULD return the correct results (1ms)
    sum(Infinity, 1)
      ✓ SHOULD return the correct results (1ms)
    sum(NaN, 1)
      ✓ SHOULD return the correct results (1ms)

Test Suites: 1 passed, 1 total
Tests:       7 passed, 7 total
Snapshots:   0 total
Time:        0.115s, estimated 1s

Requirements

This package is compatible with test runners that provide the describe(), it() and beforeEach() global helpers.

Usage

scenarioBuilder(fn)

Creates a pre-bound test scenario generator function that, when called with specifics of a test scenario, can be used to assert the results of that scenario.

Arguments:

| Name | Type | Required | Default | Description | | - | - | - | - | - | | fn | (input) => any | Yes | N/A | Function that returns a result for the specified input |

Returns:

(descriptions, options) => void A function that can be invoked with details of a test scenario (see below) to assert based on the results of that scenario

scenarioBuilder(fn)(description, options)

Given a pre-bound test scenario generator, create a new describe() test suite that runs an individual scenario to assert results for the specified input.

Arguments:

| Name | Type | Required | Default | Description | | - | - | - | - | - | | description | string | Yes | N/A | Description for the scenario | | options.input | any | Yes | N/A | Input value for the scenario | | options.expected | any | No | N/A | Expected result value for the scenario | | options.async | boolean | No | false | Whether to await the result of the scenario | | options.before | () => (void \| Promise<void>) | No | N/A | Actions to perform before the scenario is run | | options.assert | (result) => (void \| Promise<void>) | No | N/A | Assertions to perform after the scenario has run |