Module: hcjeTools/testing/runner

Script for running tests. This is intended to be run as a Node.js script.

Usage:

  • runner configFileOrDir
    • configFileOrDir: either the path to a folder to be tested or a JSON file of a TestConfig object.

Testing a module

In order to be tested, a module requires a test module to be created and the test module's name must end with .test.js.

As a minimum, the test module must export an array named tests containing the TestDefinition objects.

It can also export the following optional functions:

  • beforeModuleTests(): called at the start of the module test.
  • beforeEachTest(): called before each individual test described by its TestDefinition
  • afterEachTest(): called after each individual test described by its TestDefinition
  • afterModuleTests(): called at the end of the module test.

Note that each TestDefinition is run synchronously to ensure tests are run in the order described in the tests object.

The runner script will look for all test modules, *.test.js, in the source folder and its subfolders and run every test described by the exported tests objects.

Example

Here is an example file which would run a single test on the parseInt function.

import * as utils from './utils.js';

export const tests = [
 {
   description: 'parseInt normal',
   run: () => utils.parseInt('4.5'),
   expected: 4,
   compare: '===',
 }
];
Source:

Methods

(inner) writeResultsToConsole(testResults)

Write the results to the console.

Parameters:
Name Type Description
testResults module:hcjeTools/testing/runner~TestResult

The test results.
Source:

(inner) writeResultsToFile(testResults, resultsFolder, noTimeStampopt) → {Promise}

Create a Markdown file of the results.

Parameters:
Name Type Attributes Description
testResults module:hcjeTools/testing/runner~TestResult

The test results.
resultsFolder string

Folder to which the results file is written. Results are written to the file test-results-timestamp.md
noTimeStamp boolean <optional>

If true the file is written without the timestamp in the filename.
Source:
Returns:
Type
Promise

Type Definitions

TestConfig

Configuration options for testing.

Type:
  • Object
Properties:
Name Type Description
noTimeStamp boolean

If true, the results file will not include a time stamp in the filename.
source string

The folder containing the modules to be tested. Testing includes all subfolders.
resultsFile string

The file to which to write the results. If it includes a directory, that will be created if necessary.
Source:

TestDefinition

Type:
  • Object
Properties:
Name Type Description
description string

Description of the test used in results.
run module:hcjeTools/testing/runner~runTest

The test function to run. This should return the result or a Promise that fulfils to the result;
expected *

The expected result. If this is an Error object, an exception is expected and the exception error message is checked against the incoming message.
check module:hcjeTools/testing/runner~check

Function to run to check the result.
compare module:hcjeTools/testing/runner~compare | string

Function to run to compare the result. If a string is provided it is used as a lookup into the standard comparisons:

  • "equivalent": both the expected and result values are converted using JSON.stringify and then a simple equality test used.
  • "exception": an exception is expected to be thrown. A "match" test described below is then used.
  • "match": the expected result should be a RegExp. The result is coerced into a string and then tested using the expected result RegExp.
  • "==": a simple equality test is used.
  • "===": a strict equality test is used.
  • "=Ndp": a simple comparison where the result and expected values are fixed to N decimal places before using a strict equality test. For convenience, there can be one to three equals signs at the beginning of the string but this will not affect the result as both the result and expect values must be numeric and a strict comparison is always used.
Source:

TestModule

Module that is to be tested.

Type:
  • Object
Properties:
Name Type Description
beforeModuleTests function

Function to run before any tests in the module run.
beforeEachTest function

Function to run before each test.
afterEachTest function

Function to run after each test.
afterModuleTests function

Function to run after all tests in the module have run.
tests Array.<module:hcjeTools/testing/runner~TestDefinition>

Tests that are to be run
Source:

TestResult

Encapsulation of the result of running a test.

Type:
  • Object
Properties:
Name Type Description
description string

Test description
result *

The actual result returned by the test. This will be undefined if the test failed.
error Error

Error if test failed. This will be undefined if the test passed.
Source:

check(result)

Function used for checking the results from module:hcjeTools/testing/runner~runTest. Unlike the Compare function, this is used for checking the result itself as opposed to comparing against a specified expected result. This is particularly useful where data used when running the test are required for evaluating whether the test was successful. In this case, the result returned from the RunTest function can return an object containing both the normal result and the data required for evaluation. As this object will be passed to the check function, the function will be able to determine whether the run was successful.

Parameters:
Name Type Description
result *

The result to check.
Source:
Throws:

Thrown if the result fails the checks.

Type
Error

compare(result, expected)

Function used for comparing the results from module:hcjeTools/testing/runner~runTest against an expected result.

Parameters:
Name Type Description
result *

The actual result
expected *

The expected result
Source:
Throws:

Thrown if the result does not compare correctly against the expected value.

Type
Error

runTest() → {*|Promise}

Function used for running tests.

Source:
Returns:

Either the result itself or a Promise that fulfils to the result.

Type
* | Promise