Skip to content

CLI

Jump to bottom
Anton edited this page Feb 4, 2020 · 3 revisions

This page describes how to use Zoroaster from the command-line interface. If it was installed globally, the zoroaster command could be used. For locally installed Zoroaster, the yarn or npm run commands are preferred with scripts added to the package.json.

On This Page

Usage

When the path passed is a directory, all test suites it contains will be constructed recursively and executed. Multiple paths can be passed.

zoroaster test/spec
yarn t test/spec test/mask

When the path is a file, it is made into a single test suite and run. Multiple files could also be given.

zoroaster test/spec/lib.js
yarn t test/spec/lib.js test/mask/lib.js

Reporter & default

The reporter will print names of each test, however there are some specifics to how test suite names are printed:

  • Whenever a file export the default test suite, the name of the test suite will be displayed as the name of the file. The names of files are printed without the .js or .jsx extensions. Any named exports will appear under the name of the file.
  • If a file is called default.js in a directory, the name of the test suite will be the name of the directory, and not default. This means that any test suite that is named default will have its tests reported under its parent name.
  • If there is a directory which contains a default.js, and a file with the same name as the directory (but with an extension), the tests in both will be merged under the same test suite.

For example, with the following directory structure:

example/reporting
├── default.js
├── methods
│   └── default.js
└── methods.js

And the test suites exported in the way shown below:

# default.js

export default {
  'testA'() {},
  'testB'() {},
}
export const functions = {
  'testC'() {},
  'testD'() {},
}

# methods/default.js

export default {
  'dir testA'() {},
  'dir testB'() {},
}

export const extra = {
  'extra testA'() {},
  'extra testB'() {},
}

# methods.js

export default {
  'file testA'() {},
  'file testB'() {},
}

export const additional = {
  'additional testC'() {},
  'additional testD'() {},
}

The reporter will produce the following output:

example/reporting
  ✓  testA
  ✓  testB
   functions
    ✓  testC
    ✓  testD
   methods
    ✓  file testA
    ✓  file testB
    ✓  dir testA
    ✓  dir testB
     extra
      ✓  extra testA
      ✓  extra testB
     additional
      ✓  additional testC
      ✓  additional testD

🦅  Executed 12 tests.

--watch, -w: Watch Files for Changes

To watch files for changes, use --watch (or -w) flag, e.g.,

zoroaster test/spec --watch
zoroaster test/spec -w

After a change to a file happens, Zoroaster will clear all dependencies and run tests again. It will not, however, clear the node_modules dependencies, so that if another package that was used in the project previously was updated to a newer version, the test runner will have to be restarted.

--timeout, -t: Timeout

Sets the global timeout for each test in ms. The default timeout is 2000ms.

--alamode, -a: require('alamode)()

ÀLaMode is a Regex-Based transpiler that allows to write import and export statements. It will transpile tests and source files on-the-fly when this option is used.

zoroaster test/spec -a

.alamoderc.json

One of the advantages of using ÀLaMode is that it can substitute paths to imported modules according to the configuration found in the .alamoderc.json file in the project directory. For example, if it is required to test the build directory instead of the src directory, the following configuration can be used:

{
  "env": {
    "test-build": {
      "import": {
        "replacement": {
          "from": "^((../)+)src",
          "to": "$1build"
        }
      }
    }
  }
}

This will make Zoroaster import source code from the build directory when the ALAMODE_ENV is set to test-build (also see package.json for a quick script which allows to do that). This is extremely useful to check that the code transpiled for publishing passes same tests as the source code.

ALAMODE_ENV can be set by passing -e env CLI argument.

--babel, -b: require(@babel/register)

To use @babel/register in tests, the --babel (or -b) flag can be passed to the CLI. It will make a call to require @babel/register, therefore it must be installed as a dependency in the project, because it's not specified as Zoroaster's dependency.

zoroaster test/spec --babel
zoroaster test/spec -b

For example, when the ES6 modules syntax (import package from 'package') is needed, the following .babelrc pattern needs to be used:

{
  "plugins": [
    "@babel/plugin-syntax-object-rest-spread",
    "@babel/plugin-transform-modules-commonjs"
  ]
}

with the following dev dependencies installed:

yarn add -E -D \
@babel/core \
@babel/register \
@babel/plugin-syntax-object-rest-spread \
@babel/plugin-transform-modules-commonjs \

However, the above set-up can be easily achieved with ÀLaMode which has much less dependencies than Babel and is faster. This option therefore should be used for cases when more advanced transforms need to be added.

--snapshot, -s

Sets the root snapshot directory, with test/snapshot as the default. For example, if the test from test/spec/test-suite.js returned some data, the snapshot would be saved in test/snapshot/test/spec/test-suite/the-name-of-the-test.txt file (see snapshot root below).

--snapshotRoot, -r

When generating snapshots, ignores the initial part of the path that matched the root. The default value is test/spec,test/mask, so that the snapshot from the example above would actually be saved at test/snapshot/test-suite/the-name-of-the-test.txt.

package.json

To be able to run tests from the project directory, it is advised to use package.json scripts. There is the main test script, and additional shorter scripts for yarn and npm that make it easy to run tests.

Command Meaning
t Command which could be used to point to the exact file, e.g., yarn t test/spec/lib.js.
test Run all tests found in the spec and mask directories.
mask Run just mask tests.
spec Run only spec tests.
test-build When a project is built into build, and ALAMODE_ENV is configured in .alamoderc.json, this allows to substitute all paths to source files in the src directory to paths in the build directory. 
{
  "scripts": {
    "t": "zoroaster -a",
    "test": "yarn t test/spec test/mask",
    "mask": "yarn t test/mask",
    "spec": "yarn t test/spec",
    "test-build": "ALAMODE_ENV=test-build yarn test",
  }
}

launch.json

The following snippet can be used in VS Code when debugging tests.

{
  "type": "node",
  "request": "launch",
  "name": "Launch Zoroaster",
  "program": "${workspaceFolder}/node_modules/.bin/zoroaster",
  "args": [
    "test/spec",
    "-a",
    "-w",
    "-t",
    "9999999",
  ],
  "console": "integratedTerminal",
  "skipFiles": [
    "<node_internals>/**/*.js"
  ]
}
Clone this wiki locally