@test-runner/tom

This project and documentation are a work in progress.

A TOM (Test Object Model) is a data structure that defines a test suite in the same way a DOM defines a web document. The model describes your tests, how they are grouped, the order in which they should run and the config for each (timeout, max concurrency etc.)

Once defined, a TOM can be executed by a compatible runner, for example: test-runner or web-runner.

Synopsis

Trivial example building a TOM containing two tests - one pass and one fail. A test is created by supplying a name and function to tom.test. Later, when executed by the runner, if the function throws or rejects then the test is considered a fail.

import Tom from '@test-runner/tom'
const tom = new Tom()

tom.test('A successful test', function () {
  return 'This passed'
})

tom.test('A failing test', function () {
  throw new Error('This failed')
})

export default tom

Save the above to file named test.js, you can now run this test suite in several ways. For example, you can run it in Node.js by supplying it as input to test-runner.

$ test-runner test.js

Start: 2 tests loaded

✓ synopsis A successful test [This passed]
⨯ synopsis A failing test

   Error: This failed
       at TestContext.<anonymous> (file:///Users/lloyd/Documents/test-runner-js/tom/tmp/synopsis.mjs:10:9)
       ...
       at processTimers (internal/timers.js:475:7)


Completed in 10ms. Pass: 1, fail: 1, skip: 0.

Or, to verify the code under test is isomorphic, you can run the same TOM in the browser (Chromium) using web-runner.

$ web-runner test.js

Start: 2 tests loaded

✓ tom A successful test [This passed]
⨯ tom A failing test

   Error: This failed
       at TestContext.<anonymous> (http://localhost:7357/output.mjs:894:9)
       ...
       at http://localhost:7357/output.mjs:2016:21


Completed in 8ms. Pass: 1, fail: 1, skip: 0.

API summary

Supply a name and test function to tom.test. If the function throws or rejects the test is considered a fail.

tom.test('name', function () {
  // test
})

Skip a test. You can revisit this test later.

tom.skip('name', function () {
  // test
})

Skip all but this and any other tests marked as only.

tom.only('name', function () {
  // test
})

Create a sub-group.

const groupOne = tom.group('My group')

groupOne.test('first test in the group', function () {
  // test
})

Define tests to be run before and after the main tests in the group.

tom.before('name', function () {
  // test
})

tom.after('name', function () {
  // test
})

Todo. This will highlighted in test results to remind you to revisit it later.

tom.todo('name', function () {
  // Complete later
})

Reset a completed test, ready to run again.

tom.reset()

Documentation

• API reference

© 2018-21 Lloyd Brookes <[email protected]>.