The main utility of the package is tape6. It runs individual files using separate threads.

There are companion utilities that can be very useful as well:

• tape6-seq — an in-process sequential test runner described below.
  • Can be faster than tape6 because no need to spin up a thread.
  • Doesn't run tests in parallel so global updates do not affect other tests.
• tape6-proc — a process-based test runner available as a separate package tape-six-proc.
  • Useful when your tests modify globals that can affect other tests when they are running in parallel.

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 [options...] [tests...]

The options can be one of the following:

• --flags FLAGS, -f FLAGS — sets the flags to use. See TAPE6_FLAGS below for details.
• --par N, -p N — sets the number of parallel tests to run. See TAPE6_PAR below for details.
• --info — prints the current configuration (runtime, reporter, flags, parallelism, resolved files) and exits without running tests.
• --self — prints its path to stdout and quits. It is used for scripting to avoid some problems with particular runtime environments.
• --help, -h — shows the help message and exits.
• --version, -v — shows the version and exits.

Options that take a value accept both --flags FO (space-separated) and --flags=FO (=-separated) forms.

Note: the = form does not support shell-style quoting of the value (e.g. --flags="FO" won't work as expected). Use the space-separated form when values need quoting: --flags "FO".

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.

Examples

Running all configured tests:

npm test

Running an individual test:

npm test -- tests/test-general.js

Running specific files:

npm test -- tests/test-general.js tests/test-async.js

Running specific tests using a glob pattern:

npm test -- tests/special/test-*.js

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 characters, which serves as flags. See Supported flags for details.

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 --par 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

TAPE6_MIN

This setting forces the use of a minimal reporter that logs basic test events. Any non-empty string is accepted. The default is empty.

It is ignored by tests running in the browser.

Example:

TAPE6_MIN=y node tests/test-general.js

TTY and other reporters

If no TAPE6_TAP, TAPE6_JSONL, or TAPE6_MIN 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

Deno

If you want to specify detailed permissions, use deno run ... variant instead:

{
  "scripts": {
    "test:deno": "deno run --allow-read --allow-env --allow-net `npx tape6 --self` --flags FO"
  }
}

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

Environment-specific notes

• Node
• Bun
• Deno

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.

tape6-seq

tape6-seq is an in-process sequential test runner. It runs tests one by one in the same process. This can be faster than tape6 because no need to spin up a thread. It doesn't run tests in parallel so global updates do not affect other tests.

It supports the same options and configuration as tape6.

By default, tape6-seq runs using Node. If you want to run it with Bun or Deno, use the following commands:

// a fragment of package.json
{
  "scripts": {
    "test:seq:bun": "bun run `npx tape6-seq --self` --flags FO",
    "test:seq:deno": "deno run -A `npx tape6-seq --self` --flags FO"
  }
}