Docs - ReadyTest

ReadyTest methods are accessible as globals by default. In the browser they are defined on window. In node they are defined on the global object, but this behavior can be turned off, requiring methods to be accessed via require or import statments.

Defines a suite of tests. describe blocks can be nested. Code inside a describe block but outside of tests will be run only once. Returning a promise will wait for this code to run.

*describe('User', () => {*
  // Tests...
*});*

describe(str, fn)

Flags a test suite as "focused". If this flag is enabled, other suites will be ignored.

*fdescribe('User', () => {*
  // Tests...
*});*

fdescribe(str, fn)

Flags a suite as "skipped", which is useful for temporarily disabling tests.

*xdescribe('User', () => {*
  // Tests...
*});*

xdescribe(str, fn)

Flags a suite as "perf". If this flag is enabled, tests will additionally evaluate runtime performance and output results at the end. Perf suites can also carry "focused" or "skipped" flags like other suites using fpdescribe, xpdescribe, pfdescribe or pxdescribe.

*pdescribe('User', () => {*
  // Tests...
*});*

pdescribe(str, fn)

Defines a test. it blocks can not be nested or used outside describe blocks.

*it('should save', () => {*
  // Assertions...
*});*

it(str, fn)

Flags a test as "focused". If this flag is enabled, other tests will be ignored.

*fit('should save', () => {*
  // Assertions...
*});*

fit(str, fn)

Flags a test as "skipped", which is useful for temporarily disabling tests.

*xit('should save', () => {*
  // Assertions...
*});*

xit(str, fn)

Flags a test as "perf". If this flag is enabled, it will additionally evaluate runtime performance and output results at the end. Perf tests can also carry "focused" or "skipped" flags like other tests using fpit, xpit, pfit or pxit. An optional number may be passed as the first argument to allow multiple iterations of the test. This can be useful to exaggerate differences in performance for comparison.

*pit('should be fast', () => {*
  // Runs once and calculates performance.
*});*

*pit(1000, 'should be fast', () => {*
  // Runs 1000 times and calculates performance.
*});*

pit(str, fn)

pit(num, str, fn)

Defines a block that will run before all tests in the suite start. This method is functionally the same as code directly in the describe block, except that it will run each time the suite is re-run instead of only once on init. Before blocks always run outside in when inside nested suites.

describe('User', () => {
  *beforeAll(() => {*
    // Executes before all tests start.
  *});*
});

beforeAll(fn)

Defines a block that will run before each test starts. Before blocks always run outside in when inside nested suites.

describe('User', () => {
  *beforeEach(() => {*
    // Executes before each test.
  *});*
});

beforeEach(fn)

Defines a block that will run after all tests in the suite are finished. After blocks always run inside out when inside nested suites.

describe('User', () => {
  *afterAll(() => {*
    // Executes after all tests finish.
  *});*
});

afterAll(fn)

Defines a block that will run after each test finishes. After blocks always run inside out when inside nested suites.

describe('User', () => {
  *afterEach(() => {*
    // Executes after each test.
  *});*
});

afterEach(fn)

Alias for beforeEach.

describe('User', () => {
  *setup(() => {*
    // Executes before each test.
  *});*
});

setup(fn)

Alias for afterEach.

describe('User', () => {
  *teardown(() => {*
    // Executes after each test.
  *});*
});

teardown(fn)

When called with one argument, this method is functionally equvalent to assertTruthy. When called with two arguments it is equivalent to assertEqual. An optional third argument will output a custom message.

it('...', () => {
  *assert(true);*   // Pass
  *assert('a');*    // Pass
  *assert(1, 1);*   // Pass
  *assert(false);*  // Fail
  *assert('');*     // Fail
  *assert(1, '1');* // Fail
});

assert(arg1, [arg2], [msg])

Asserts that the passed argument is true. An optional second argument will output a custom message.

it('...', () => {
  *assertTrue(true);*  // Pass
  *assertTrue(false);* // Fail
});

assertTrue(arg, [msg])

Asserts that the passed argument is false. An optional second argument will output a custom message.

it('...', () => {
  *assertFalse(false);* // Pass
  *assertFalse(true);*  // Fail
});

assertFalse(arg, [msg])

Asserts both arguments are strictly equal. Equivalent to the === operator. An optional third argument will output a custom message.

it('...', () => {
  *assertEqual(1, 1);*   // Pass
  *assertEqual(1, '1');* // Fail
});

assertEqual(arg1, arg2, [msg])

Asserts both arguments are not strictly equal. Equivalent to the !== operator. An optional third argument will output a custom message.

it('...', () => {
  *assertNotEqual(0, 1);*   // Pass
  *assertNotEqual(1, '1');* // Pass
  *assertNotEqual(1, 1);*   // Fail
});

assertNotEqual(arg1, arg2, [msg])

Asserts that the passed argument is null. An optional second argument will output a custom message.

it('...', () => {
  *assertNull(null);*       // Pass
  *assertNull(1);*          // Fail
  *assertNull(undefined);*  // Fail
});

assertNull(arg, [msg])

Asserts that the passed argument is undefined. An optional second argument will output a custom message.

it('...', () => {
  *assertUndefined(undefined);* // Pass
  *assertUndefined(1);*         // Fail
  *assertUndefined(null);*      // Fail
});

assertUndefined(arg, [msg])

Asserts that the passed argument is truthy. An optional second argument will output a custom message.

it('...', () => {
  *assertTruthy(1);*   // Pass
  *assertTruthy('a');* // Pass
  *assertTruthy(0);*   // Fail
  *assertTruthy('');*  // Fail
});

assertTruthy(arg, [msg])

Asserts that the passed argument is falsy. An optional second argument will output a custom message.

it('...', () => {
  *assertFalsy(0);*   // Pass
  *assertFalsy('');*  // Pass
  *assertFalsy(1);*   // Fail
  *assertFalsy('a');* // Fail
});

assertFalsy(arg, [msg])

Asserts that the string passed as the first argument matches the regex passed as the second argument. An optional third argument will output a custom message.

it('...', () => {
  *assertMatch('foo', /^foo$/);* // Pass
  *assertMatch('foo', /^bar$/);* // Fail
});

assertMatch(str, reg, [msg])

Asserts that the string passed as the first argument does not match the regex passed as the second argument. An optional third argument will output a custom message.

it('...', () => {
  *assertNoMatch('foo', /^foo$/);* // Pass
  *assertNoMatch('foo', /^bar$/);* // Fail
});

assertNoMatch(str, reg, [msg])

Asserts that the function passed as the first argument throws an error. The second argument will restrict the assertion to only checking for a specific error type. An optional third argument will output a custom message.

it('...', () => {
  *assertError(throwsError);*                 // Pass
  *assertError(throwsTypeError, TypeError);*  // Pass
  *assertError(doesNotThrowError);*           // Fail
  *assertError(throwsRangeError, TypeError);* // Fail
});

assertError(fn, [error], [msg])

Asserts that the function passed as the first argument does not throw an error. The second argument will restrict the assertion to only checking for a specific error type. An optional third argument will output a custom message.

it('...', () => {
  *assertNoError(doesNotThrowError);*           // Pass
  *assertNoError(throwsRangeError, TypeError);* // Pass
  *assertNoError(throwsError);*                 // Fail
  *assertNoError(throwsTypeError, TypeError);*  // Fail
});

assertNoError(fn, [error], [msg])

Asserts that both objects are deeply equal. This method will recursively check each property and perform a strict equality check === on all properties that are not themselves objects. If any property is not equivalent, a diff will be output highlighting all properties that differ. This assertion will fail if either argument is not an object, and only enumerable, non-inherited properties will be compared. An optional third argument will output a custom message.

Note that although argument order will not affect the outcome, diff output uses messages like "property missing" which are more readable when the expected object is the second argument.

it('...', () => {
  *assertObjectEqual({}, {});*         // Pass
  *assertObjectEqual({a:1}, {a:1});*   // Pass
  *assertObjectEqual({}, {a:1});*      // Fail
  *assertObjectEqual({a:1}, {a:'1'});* // Fail
});

assertObjectEqual(obj1, obj2, [msg])

Asserts that both arrays are deeply equal. An optional third argument will output a custom message. With the exception of testing that array lengths are equal up front, this method is an alias for assertObjectEqual.

it('...', () => {
  *assertArrayEqual([], []);*     // Pass
  *assertArrayEqual([1], [1]);*   // Pass
  *assertArrayEqual([], [1]);*    // Fail
  *assertArrayEqual([1], ['1']);* // Fail
});

assertArrayEqual(arr1, arr2, [msg])

Asserts that both dates are equivalent. An optional third argument will output a custom message. This method is required as dates do not have enumerable properties exposing their state, so assertObjectEqual will not work.

it('...', () => {
  *assertDateEqual(new Date(1), new Date(1));* // Pass
  *assertDateEqual(new Date(1), new Date(2));* // Fail
});

assertDateEqual(date1, date2, [msg])

Asserts that both regexes are equivalent. An optional third argument will output a custom message. This method is required as regexes do not have enumerable properties exposing their state, so assertObjectEqual will not work.

it('...', () => {
  *assertRegExpEqual(/a/, /a/);*  // Pass
  *assertRegExpEqual(/a/, /a/i);* // Fail
});

assertRegExpEqual(reg1, reg2, [msg])

Asserts that the object passed as the first argument is an instance of the class passed as the second. An optional third argument will output a custom message.

it('...', () => {
  *assertInstanceOf(3, Number);*   // Pass
  *assertInstanceOf('3', Number);* // Fail
});

assertInstanceOf(instance, class, [msg])

Asserts that the first argument is strictly equal === to at least one of the elements in an array passed as the second. An optional third argument will output a custom message.

it('...', () => {
  *assertOneOf('a', ['a','b','c']);* // Pass
  *assertOneOf('d', ['a','b','c']);* // Fail
});

assertOneOf(arg, arr, [msg])

Asserts that the passed argument is NaN. An optional second argument will output a custom message.

it('...', () => {
  *assertNaN(NaN);*  // Pass
  *assertNaN(null);* // Fail
  *assertNaN('a');*  // Fail
});

assertNaN(arg, [msg])

Creates a custom assertion. This method takes a single function that can accept any number of arguments and returns an object with the following properties:

pass: Whether or not the test has passed.
message: The failure message. Any properties set on the return object can be referenced here by wrapping them in curly braces.
diff: An optional object that outputs the diff on failure. If the pass property is not set, it will be implied by the state of the diff. For more, see createDiff.

*const assertEven = createAssertion(arg => {
  return {
    pass: arg % 2 === 0,
    message: '{num} should be an even number',
    num: arg
  };
});
assertEven(2); // Pass
assertEven(3); // Fail
*

createAssertion(fn)

Creates a diff object that can be attached to a custom assertion to output the diff of two objects (or arrays) on test failure. Both arguments must be non-primitives of object type.

*createAssertion(obj => {
  return {
    diff: createDiff(obj, expected),
    message: 'object must match expected'
  };
});*

createDiff(obj1, obj2)

ReadyTest has a few settings that can configure the runner behvaior. In the browser these are exposed as methods on the ReadyTest global as well as data attributes on the loading script tag. In node they can be used via require or import as well as options to the shell script.

Note that the shell script also has some additional configurations like the ability to watch and re-run. Run this script with the --help flag for more details.

In the browser the test runner will start on page load, however for various reasons you may want to manually control when the runner starts. You can achieve this using this method together with run. This setting can be retrieved with getAutoRun.

In the browser:

*ReadyTest.setAutoRun(false);*

This setting can also be a data attribute on the loading script tag:

*<script src="node_modules/ready-test/ready-test.js" data-auto-run="false"></script>*

In node this flag has no effect as the shell script always begins the run once tests are loaded. To manually run tests you can simply create your own runner by requiring the main script and calling run as needed.

setAutoRun(bool)

Setting the fold mode will change the way test result output is displayed. none will output all nested suites. Conversely, all will output all tests together as if they were part of a single suite. top will only output the top level suites. The default setting is none except when using the shell script in node which sets the default to all. This setting can be retrieved with getFoldMode.

Note that this only affects output. The execution order of tests as well as before and after blocks will remain the same.

In the browser:

*ReadyTest.setFoldMode('all');*

This setting can also be a data attribute on the loading script tag:

*<script src="node_modules/ready-test/ready-test.js" data-fold-mode="all"></script>*

In the node shell script:

*./node_modules/bin/readytest --fold-mode=none*

In a custom node runner:

*const ReadyTest = require('ready-test');
ReadyTest.setFoldMode('all');

setFoldMode(str)

Sometimes the order in which tests are run may cause them to fail. These kind of failures can be hard to track down, so ReadyTest provides the ability to randomize tests and re-run them in a specific order so you can track down a failure. Running with randomization on will randomize all tests differently on each run. The final output will show the seed that was used, which can then be passed back into the runner using setSeed to run the tests in the same order. This setting can be retrieved with getRandomize.

In the browser:

*ReadyTest.setRandomize(true);*

This setting can also be a data attribute on the loading script tag:

*<script src="node_modules/ready-test/ready-test.js" data-randomize="true"></script>*

In the node shell script:

*./node_modules/bin/readytest --randomize*

In a custom node runner:

*const ReadyTest = require('ready-test');
ReadyTest.setRandomize(true);

setRandomize(bool)

Use this method to fix the order of a test run that was randomized using setRandomize. The seed used will be shown along with the final output when a run was randomized. This setting can be retrieved with getSeed.

In the browser:

*ReadyTest.setSeed(1234);*

This setting can also be a data attribute on the loading script tag:

*<script src="node_modules/ready-test/ready-test.js" data-seed="1234"></script>*

In the node shell script:

*./node_modules/bin/readytest --seed=1234*

In a custom node runner:

*const ReadyTest = require('ready-test');
ReadyTest.setSeed(1234);

setRandomize(num)

Utils are most commonly used to create a custom test runner. They are exposed in the browser through a ReadyTest global, and in node as methods that can be used through require or import.

Begins the test run. A callback can also be passed that will execute when the run is complete. In the browser this function should be used with setAutoRun.

In the browser:

*ReadyTest.run(onRunComplete);*

In a custom node runner:

*const ReadyTest = require('ready-test');
ReadyTest.run(onRunComplete);*

run([fn])

Clears all tests and suites previously defined. This method is useful when dynamically reloading tests and is used by the shell script to watch and reload.

In the browser:

*ReadyTest.clear();*

In a custom node runner:

*const ReadyTest = require('ready-test');
ReadyTest.clear();

clear()

Cancels the test run. This method can be used with custom test runners or to extend the functionality of a browser setup. Tests may be asynchronous so a function can be passed that will run when the cancel operation has completed.

In the browser:

*ReadyTest.cancel(onCancelComplete);*

In a custom node runner:

*const ReadyTest = require('ready-test');
ReadyTest.cancel(onCancelComplete);

cancel([fn])

Returns true if the test run is in progress. This method can be used with custom test runners or to extend the functionality of a browser setup. Note that this method should only return true if asynchronous tests exist that have not yet completed.

In the browser:

*ReadyTest.isRunning();*

In a custom node runner:

*const ReadyTest = require('ready-test');
ReadyTest.isRunning();

isRunning()

This method is useful in custom test runners to export all methods onto the global object so that tests do not have to require them. It has no effect in the browser as methods are already exported on the window object.

*const ReadyTest = require('ready-test');
ReadyTest.exportGlobals();

exportGlobals()

Returns the name of the current test running or null.

In the browser:

*ReadyTest.getCurrentTest();*

In a custom node runner:

*const ReadyTest = require('ready-test');
ReadyTest.getCurrentTest();

getCurrentTest()

Returns the name of the current suite running or null.

In the browser:

*ReadyTest.getCurrentSuite();*

In a custom node runner:

*const ReadyTest = require('ready-test');
ReadyTest.getCurrentSuite();

getCurrentSuite()