babel-plugin-spock

babel-plugin-spock

Structured JS test cases, inspired by Spock Framework

Note: This module is in an early stage of development and currently provides only a small set of features.

Example test case

test('basic arithmetic', () => {
  expect: {
    1 + 2 === 3;
    3 * 3 >= 4 * 4; // falsy
  }
});

Expected value to be (operator: ==):
  true
Received:
  false

  assert(3 * 3 >= 4 * 4)
           |   |    |
           |   |    16
           9   false

Installation

npm install --save-dev babel-plugin-spock power-assert

This module is a Babel plugin that needs to transform your test sources in order to generate assertions, so your test runner will need support for Babel. Babel integrates quite nicely into most modern test runners. Check the documentation of your test runner for instructions on how to configure Babel (e.g. for Jest, AVA etc.) or consult Babel's own documentation.

Once Babel is set up for your test files, simply add "babel-plugin-spock" to the plugins array in your babel configuration and you're good to go.

Note: The last version of this plugin that supports Babel 6 is 0.1.0

Usage

Assertion blocks

Note: At the moment, your test files need to import assert from 'power-assert'; for this to work. In the future, the plugin will be able to handle this for you automatically.

Inside of a block labeled with expect: or then:, all statements will be considered assertions and evaluated to check for truth:

expect: {
  1 < 2;
}

when-then blocks can be particularly useful and expressive for code with side effects:

// The 'when' label here does not have a special meaning
// It is used simply to make the test more structured
when: {
  abc.setXyz(1);
}

then: {
  abc.getXyz() === 1;
}

Single labeled statements are also possible:

expect: 'a' + 'b' === 'ab';

Note that these blocks can only contain statements that can be evaluated as expressions. For example, an if statement would not be valid:

// BAD
expect: {
  if (x < 1) x === 0.5;
  else x === 2;
}

However, you can nest an assertion block into other structures:

// GOOD
if (x < 1) expect: x === 0.5;
else expect: x === 2;

If you want to perform more complicated checks, it might be helpful to look for small helper libraries on npm. For example, deep-strict-equal can help perform deep equality checks on object structures. In the future, this plugin might provide special syntax for such use cases.

Linters

The test you will write using this plugin often employ syntax that is otherwise uncommon in JavaScript code. For this reason, if you use a linter such as ESLint, you will likely see annoying warnings all over your tests. To work around this, most linters will give you multiple options:

• Disable the problematic rules with special annotations in your test files. This can be a hassle because it needs to be done for every file.
• Completely disable the rules in the configuration. This means that they will no longer apply to production code either.
• Create a separate config for tests that extends the base config, but disables the rules.

Configuration

You can configure this plugin using Babel's regular plugin configuration mechanism. The following options are available:

powerAssert

The plugin can seamlessly generate assertions that produce detailed mismatch messages to help you figure out what exactly about the assertion went wrong. Turning this feature off could be useful if you're tests appear to run slowly or you are experiencing other issues with your assertions.

This feature is powered by the awesome project power-assert.

default: true

Changelog

0.2.0 (2018-01-27)

Bug Fixes

• assertions: support non-standard JSX syntax (81fa923)

Features

• babel 7 support (830465b)

<a name="0.1.0"></a>