@xutl/test - Simple BDD Test Framework

One eXtremely Useful Tool Library providing a simple and small test-framework for node stuff that’s basically half of Mocha. The half it doesn’t support is configurability and coverage, since those are easy to add with separate tools.

Large dependencies are a problem. Use them sparingly but whenever useful. When creating them, keep them light.

Install

npm install --save-dev @xutl/test

Usage

basic-test.js

import { define, it, before, beforeEach, afterEach, after } from '@xutl/test';
describe('suite 1', () => {
	it('assertion 1', () => {
		// assert something
	});
	it('assertion 2', () => {
		// assert something
	});
});

npx -p @xutl/test basic-test.js

xutltest has an option to put the functions into the global objects, which enables it to run mocha tests which don’t import the library.

xutltest [–global][glob-pattern] –global : put functions into global object

The --global option puts describe, it, before, beforeEach, afterEach, after into the global object, so that test-drivers don’t need to require them.

Motivation

I really like BDD style testing and TAP output. However mocha and its ilk, always bring in everything and the kitchen sink. I don’t want to download gigabytes of packages just to have some basic tests; instead I’d rather my test-framework is small and does just what it’s core job is.

If I want more (coverage) there are tools for that. Just run the tests with c8 (or instanbul) and be merry. There is no reason that a test framework needs to be heavy weight.

There is also a more detailed rationale for why it’s a good idea to create “yet another test-framework”.

API

All API functions are bound so they can be assigned to scope variables to imitate the global behaviour that Mocha provides.

describe(name : string, setup : function)

Defines a test. The setup function may contain calls to any of the other API functions. It is however a synchronous function, so you need to use the before(), beforeEach(), afterEach() and after() function to do any asynchronous setup.

describe.skip(name : string, setup : function)

Defines a test just like describe except when the tests are actually run these will be skipped.

describe.only(name : string, setup : function)

Defines a test just like describe except when the tests are actually run only those defined via .only will actually be executed. However this filtering is per test-suite. So children of tests that are run or other parents are not affected.

describe.todo(name : string, setup : function)

Defines a test just like describe except when the tests are actually run these will be skipped.

it(name : string, test : function)

Defines an assertion. This function can return a promise which will be awaited before the next assertion is made.

Calling it() is illegal outside the synchronous describe() setup function.

it.skip(name : string, test : function)

Defines an assertion just like it except that it will be skipped when running the tests.

it.only(name : string, test : function)

Defines an assertion just like it except that when the assertions are actually made only those defined with only (of this suite) will be run.

it.todo(name : string, test : function)

Defines an assertion just like it and marks it as to do indicating that a failure is not a regression, but rather unimplemented.

timeout(name : string, ms: number, test : function)

Defines an assertion that will time out after ms milliseconds. This is similar to it(), except the test times out after ms milli-seconds.

Calling timeout() is illegal outside the synchronous describe() setup function.

Setup/Teardown Functions

@xutl/test provides the following Setup/Teardown functions.

before(setup : function)
beforeEach(setup : function)
afterEach(setup : function)
after(setup : function)

The passed runner function may return a then-able to perform asynchronous setup/teardown. If the returned then-able rejects, the entire test-case fails.

Calling these setup/teardown functions is illegal outside the synchronous describe() setup function.

License

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

eXtremely Useful Tool Libraries

tiny packages that give you just the right tool and no more