Utility ‐ tape6 - uhop/tape-six GitHub Wiki

The main utility of the package is tape6.

Usage

Assuming that the tests are properly configured (see Set-up tests), it can be invoked without arguments:

npx tape6

Most projects can configure special commands for that in their package.json. Example:

{
  // ...
  "scripts": {
    "test": "tape6 --flags FO",
    "start": "tape6-server --trace"
  }
  // ...
  "tape6": {
    "tests": ["/tests/test-*.*js"],
    "importmap": {
      "imports": {
        "tape-six": "/node_modules/tape-six/index.js",
        "tape-six/": "/node_modules/tape-six/src/",
        "my-package": "/index.js",
        "my-package/": "/src/"
      }
    }
  }
}

With this configuration tape6 can be invoked as:

npm test

Configuring tape6

The utility can be invoked like that:

tape6 [flags...] [tests...]

The flags can be one of the following:

  • --flags FLAGS — sets the flags to use. See TAPE6_FLAGS below for details.
  • --par N — sets the number of parallel tests to run. See TAPE6_PAR below for details.
  • --self — prints its path to stdout and quits. It is used for scripting to avoid some problems with particular runtime environments.

All other arguments are treated as test files. If files are specified they are used as tests. Otherwise, the tests are taken from the configuration. See Set-up tests for details.

Environment variables

tape6 supports environment variables starting with TAPE6_ to configure certain aspects of the test harness.

TAPE6_FLAGS

TAPE6_FLAGS is a string of options, each of which can be one of the following:

  • F is "Failures only". Only failed tests are shown in the report.
  • T is "show Time". It controls if the time taken to run the test is shown in the report.
  • B is "show Banner". It controls if the highly visible banner is shown in the report.
  • D is "show Data". It controls if the data of a failed test is shown in the report.
  • O is "fail Once". If a test fails, the testing is immediately stopped.
  • N is "show assert Number". It controls if a assert number is shown in the report.
  • M is "Monochrome". It controls if colors can be used in console output.
    • Used only by the TAP reporter.

If a flag is capitalized, the corresponding setting is enabled, otherwise it is disabled. The default is no flags set.

Example:

// show only failures
// stop at the first error
TAPE6_FLAGS=FO node tests/test-general.js

Browser tests read the string of flags from a query parameter called flags.

Example: http://localhost:3000/?flags=FO

Additional flags used by the web application:

  • S id "show Stack". It used to show the stack of a failed test in the report. This setting can be changed in the UI of the web application. It is used to define the initial state of the flag.
  • C is "show log". If it is set, the TAP reporter (see below) will duplicate the log of each test in the browser console.
  • J is "use JSONL". It controls if JSONL reporter is used instead of the TAP reporter.

TAPE6_PAR

TAPE6_PAR is a number of parallel tests to run. The default is 0.

If this setting is not a positive number, navigator.hardwareConcurrency value is used.

This settings is used only by command-line test harness. It is ignored when running individual test files, or in a browser.

Example:

TAPE6_PAR=2 tape6
// the same as:
// tape6 --parallel 2

TAPE6_TAP

This setting forces the use of TAP reporter. Any non-empty string is accepted. The default is empty.

It is ignored by tests running in the browser.

Example:

TAPE6_TAP=y node tests/test-general.js

TAPE6_JSONL

This setting forces the use of JSONL reporter. Any non-empty string is accepted. The default is empty.

It is ignored by tests running in the browser.

It is used mostly for postprocessing of test results. See tape-six-proc.

Example:

TAPE6_JSONL=y node tests/test-general.js

TTY and other reporters

If no TAPE6_TAP or TAPE6_JSONL is set, the TTY reporter is used by default.

Browser tests use a special web application to display the test results in the browser. If the web application is not used and the J flag is not set, the TAP reporter is used by default. Otherwise, the JSONL reporter is used.

Implementation details

Technically, tape6 is an executable command-line utility, which is set to be executed with the current Node. It is nothing more than a dispatcher: it detects the runtime environment and starts the proper test harness: tape6-node, tape6-deno, or tape6-bun. Those utilities can be invoked directly.

Example of package.json:

{
  "scripts": {
    "test": "tape6 --flags FO",
    "test:node": "tape6-node --flags FO",
    "test:bun": "tape6-bun --flags FO",
    "test:deno": "tape6-deno --flags FO"
  }
}

With scripts like above you can test your project in different environments:

npm test
npm run test:bun
npm run test:deno

Warning: As of 10/6/2024 Deno doesn't run the test harness as expected. The workaround is to set it up like that:

{
  "scripts": {
    "test:deno": "deno run -A `npx tape6 --self` --flags FO"
  }
}

Now you know why we need the --self flag.

Environment-specific notes

Test environment

All environments use Worker to run tests. Deno and Bun use standard web workers. Node uses worker threads.

If you like to run tests in separate processes, consider using tape-six-proc, which is a companion package.