awfltst

Async test harness and test runner.

Usage

Use like if bandage supported async functions.

'use strict';
const test = require('awfltst');

test('My Test', async function () {
  this.eq(5, 2 + 3, 'addition works');
  const result = await Promise.resolve(true);
  this.ok(result, 'promise resolved correctly');
});

test('Alternatively', async (t) => {
  t.eq(6, 2 * 3, 'multiplication works');
});

Which you can run with the bundled awfltst executable:

$ awfltst test.js

  1 My Test 1 ms

    ✔ addition works
    ✔ promise resolved correctly

  2 Alternatively 0 ms

    ✔ multiplication works


  All tests passed!


  Total:      2 tests   3 assertions
  Passing:    2 tests   3 assertions
  Duration:   3 ms

Binary

Usage:
  awfltst -h | --help
  awfltst -v | --version
  awfltst [-t | --test <test-name>]... [-g | --group <group-name>]...
          [-T | --skip-test <test-name>]... [-G | --skip-group <group-name>]...
          <file-path>...

Options:
  -h, --help                    Show usage information and exit.
  -v, --version                 Show version information and exit.
  -t, --test <test-name>        Exclusively execute a single named test.
  -T, --skip[-test] <test-name> Exclude a single named test from execution.
  -g, --group <group-name>      Exclusively execute a single test group.
  -G, --skip-group <group-name> Exclude a single test group from execution.
  --depth <depth>               Set max depth for nested properties in output.
  --reporter spec|json          Set output format. Defaults to 'spec'.
  --json                        Reformat previous json output from stdin.
  --[no-]colo[u]r               Force enable/disable coloured output.
  --[no-]capture-console        Force enable/disable console capture.
  --[no-]summary                Force enable/disable error summary.
  --[no-]filename               Force enable/disable filename from being added
                                to test names.

API

test([name], [options], test)

Create a new Test.

Kind: global function
Params

• [name] String - The name of this test.
• [options] TestOptions - Options object.
• test function - Test function.

• test([name], [options], test)
  • .only([name], [options], test)
  • .skip([name], [options], test)
  • .before([options], before)
  • .after([options], after)
  • .extend(proto) ⇒ test

test.only([name], [options], test)

Shorthand for creating a test with option.only = true.

Kind: static method of test
Params

• [name] String - The name of this test.
• [options] TestOptions - Options object.
• test function - Test function.

test.skip([name], [options], test)

Shorthand for creating a test with option.skip = true.

Kind: static method of test
Params

• [name] String - The name of this test.
• [options] TestOptions - Options object.
• test function - Test function.

test.before([options], before)

Create a before hook that will be run before every test.

Kind: static method of test
Params

• [options] HookOptions - Options object.
• before function - Setup function.

test.after([options], after)

Create an after hook that will be run after every test.

Kind: static method of test
Params

• [options] HookOptions - Options object.
• after function - Teardown function.

test.extend(proto) ⇒ test

Extend the test class prototype.

Kind: static method of test
Returns: test - A new test harness wrapping the new extended Test class.
Params

• proto Object - Map of functions and/or properties to be added to the new subclassed Test class. Note that keys beginning with _ will throw an error as these names are reserved for internal use.

TestOptions : Object

Test options.

Kind: global typedef
Properties

• skip Boolean - Whether or not to skip this test.
• only Boolean - Whether or not to run only this test.
• console Boolean - Whether or not to capture console output.
• group String | Array.<String> - The group(s) this test belongs to.
• inspect Object - Options passed to util.inspect when reporting errors.

HookOptions : Object

Hook options.

Kind: global typedef
Properties

• once Boolean - Whether or not this hook should be run only once.
• group String | Array.<String> - The group(s) this hook will be limited to.
• skipGroup String | Array.<String> - The group(s) this hook will ignore.

~this : object

Test scope inside test function.

This object is also passed as the first and only argument to the test function fore those that favours arrow functions.

Kind: inner namespace

• ~this : object
  • .stdout : String
  • .stderr : String
  • .trace ⇒ String
  • .plan ⇒ Test
  • .compare ⇒ Test
  • .chain ⇒ Test
  • .unchain ⇒ Test
  • .fail ⇒ Test
  • .pass ⇒ Test
  • .error ⇒ Test
  • .ok ⇒ Test
  • .not ⇒ Test
  • .eq ⇒ Test
  • .ne ⇒ Test
  • .gt ⇒ Test
  • .gte ⇒ Test
  • .lte ⇒ Test
  • .lt ⇒ Test
  • .between ⇒ Test
  • .notBetween ⇒ Test
  • .approx ⇒ Test
  • .contains ⇒ Test
  • .notContains ⇒ Test
  • .in ⇒ Test
  • .notIn ⇒ Test
  • .type ⇒ Test
  • .has ⇒ Test
  • .lack ⇒ Test
  • .match ⇒ Test
  • .notMatch ⇒ Test
  • .test
  • .throws
  • .notThrows

this.stdout : String

Getter/Setter for console output written to stdout during the test up until this point.

Kind: static property of this

this.stderr : String

Getter/Setter for console output written to stderr during the test up until this point.

Kind: static property of this

this.trace ⇒ String

Trace callsite.

Kind: static property of this
Params

• [pop] Number - Number of entries in the stack to pop from this call.

this.plan ⇒ Test

Set the number of assertions planned for this test.

Kind: static property of this
Returns: Test - this
Params

• expected Number
• [name] String

this.compare ⇒ Test

Compare using a custom comparator function.

Aliases: compareWith.

Kind: static property of this
Returns: Test - this
Params

• comparator function - The comparator function to use for the assertion. The function is passed the actual and expected values as is.
• actual * - The actual value to be compared.
• expected * - The expected value to be compared against.
• [name] String - A name identifying this assertion.
• [options] Object - Additional options.
  • [.operator] String - Override the operator value for the test output. Defaults to the name of the comparator function or simply 'compare' if comparator has no name.
  • [.expected] String - Override the expected value in the test output. Defaults to inspecting the value of expected using util.inspect.
  • [.actual] String - Override the actual value in the test output. Defaults to inspecting the value of actual using util.inspect.
  • [.diffable] Boolean - Determine whether or not the actual and expected test output values are diffed in the test output. Default to false.
  • [.at] String - Override the trace-line in the test output.

this.chain ⇒ Test

Create a "chain test", a special form of sub-test created purely through chaining calls on the returned Test instance.

Kind: static property of this
Returns: Test - this, ish...
Params

• [name] String

this.unchain ⇒ Test

Return to the parent of this chain. Useful in nested chain tests.

Kind: static property of this
Returns: Test - The chain's parent, or this if this is not a chain test.

this.fail ⇒ Test

Assertion that automatically fails.

Kind: static property of this
Returns: Test - this
Params

• [name] String

this.pass ⇒ Test

Assertion that automatically succeeds.

Kind: static property of this
Returns: Test - this
Params

• [name] String

this.error ⇒ Test

Assertion that automatically fails with the given error.

Kind: static property of this
Returns: Test - this
Params

• error *
• [name] String

this.ok ⇒ Test

Assert a "truthy" value.

Aliases: true.

Kind: static property of this
Returns: Test - this
Params

• actual *
• [name] String

this.not ⇒ Test

Assert a "falsy" value. Inverse of ok.

Aliases: false, notOk, notok.

Kind: static property of this
Returns: Test - this
Params

• actual *
• [name] String

this.eq ⇒ Test

Assert deep equality.

Aliases: deepStrictEquals, deepStrictEqual, deepEquals, deepEqual, equals, equal, is.

Kind: static property of this
Returns: Test - this
Params

• actual *
• expected *
• [name] String

this.ne ⇒ Test

Assert deep inequality. Inverse of eq.

Aliases: notDeepStrictEquals, notDeepStrictEqual, notDeepEquals, notDeepEqual, isNotEqual, notEquals, notEqual, isNot, neq.

Kind: static property of this
Returns: Test - this
Params

• actual *
• expected *
• [name] String

this.gt ⇒ Test

Assert that actual is greater than expected.

Aliases: greaterThan, greater.

Kind: static property of this
Returns: Test - this
Params

• actual *
• expected *
• [name] String

this.gte ⇒ Test

Assert that actual is greater than or equal to expected.

Aliases: greaterThanOrEquals, greaterThanOrEqual, greaterOrEquals, greaterOrEqual, ge.

Kind: static property of this
Returns: Test - this
Params

• actual *
• expected *
• [name] String

this.lte ⇒ Test

Assert that actual is less than or equal to expected.

Aliases: lessThanOrEquals, lessThanOrEqual, lessOrEquals, lessOrEqual, le.

Kind: static property of this
Returns: Test - this
Params

• actual *
• expected *
• [name] String

this.lt ⇒ Test

Assert that actual is less than expected.

Aliases: lessThan, less.

Kind: static property of this
Returns: Test - this
Params

• actual *
• expected *
• [name] String

this.between ⇒ Test

Assert that actual is within the given range.

Kind: static property of this
Returns: Test - this
Params

• actual *
• min *
• max *
• [name] String

this.notBetween ⇒ Test

Assert that actual is not within the given range. Inverse of between.

Kind: static property of this
Returns: Test - this
Params

• actual *
• min *
• max *
• [name] String

this.approx ⇒ Test

Assert that actual is equal to expected with a variance threshold of ± variance.

Aliases: approximately.

Kind: static property of this
Returns: Test - this
Params

• actual Number
• expected Number
• variance Number
• [name] String

this.contains ⇒ Test

Assert that actual contains expected.

Kind: static property of this
Returns: Test - this
Params

• actual *
• expected *
• [name] String

this.notContains ⇒ Test

Assert that actual does not contain expected. Inverse of contains.

Kind: static property of this
Returns: Test - this
Params

• actual *
• expected *
• [name] String

this.in ⇒ Test

Assert that actual is in expected. Reversed order version of contains.

Kind: static property of this
Returns: Test - this
Params

• actual *
• expected *
• [name] String

this.notIn ⇒ Test

Assert that actual is not in expected. Inverse of in.

Kind: static property of this
Returns: Test - this
Params

• actual *
• expected *
• [name] String

this.type ⇒ Test

Assert that actual has a type of expected or is an instance of expected.

Aliases: instanceOf, instanceof, instance, typeOf, typeof.

Kind: static property of this
Returns: Test - this
Params

• actual *
• expected String | function
• [name] String

this.has ⇒ Test

Assert that actual has a property expected.

Aliases: hasOwnProperty.

Kind: static property of this
Returns: Test - this
Params

• actual Object
• expected String
• [name] String

this.lack ⇒ Test

Assert that actual does not have a property expected. Inverse of has.

Aliases: lackOwnProperty.

Kind: static property of this
Returns: Test - this
Params

• actual Object
• expected String
• [name] String

this.match ⇒ Test

Assert that actual matches the given regular expression expected.

Kind: static property of this
Returns: Test - this
Params

• actual String
• expected RegExp
• [name] String

this.notMatch ⇒ Test

Assert that actual does not match the given regular expression expected. Inverse of match.

Kind: static property of this
Returns: Test - this
Params

• actual String
• expected RegExp
• [name] String

this.test

Create a sub-test.

Aliases: subTest, subtest.

Kind: static property of this
Params

• [name] String
• [options] Object
• test function

this.throws

Assert that the given test-function throws.

Kind: static property of this
Params

• test function | Promise
• [expected] RegExp | function
• [name] String

this.notThrows

Assert that the given test-function does not throw.

Kind: static property of this
Params

• test function | Promise
• [name] String