node:test

Caution

Wallaby now provides experimental support for node:test . As an experimental feature, you may encounter issues. Please report any issues or provide feedback to us via our github issues repository.

Wallaby’s integration with node:test requires node v22.3.0 or higher.

Note

The content of this page is adjusted based on your editor of choice. Your editor selection can be changed using the dropdown in the top right corner of the page.

Starting Wallaby on a project using node:test

To start Wallaby in VS Code you may run Select Configuration command and then select Automatic Configuration <project directory> option once. After that you may keep using Wallaby Start command as usual and it will start Wallaby with automatic configuration.

To start Wallaby in Sublime Text you may use the Select for Wallaby.js Automatic Configuration context menu item for your project folder in the project’s file tree. After that you may keep using Wallaby Start command as usual and it will start Wallaby with automatic configuration.

To start Wallaby in Visual Studio, you may use the Start Wallaby.js (Automatic Configuration) context menu item for your project folder in the Solution Explorer. After the first start, the selected project will be remembered for your solution and Wallaby can be started with Tools->Start Wallaby.js (Alt-W, 1).

To start Wallaby in JetBrains IDEs, you may edit (or create a new) wallaby.js Run Configuration by selecting Edit configurations from the drop-down menu in the top right-hand corner of the navigation bar, or from the Run menu. In the run configuration editor set Configuration Type filed value to Automatic.

Configuration Defaults

Wallaby will attempt to automatically detect and configure your project if it uses node:test; for most projects, you will not need to provide any additional configuration or create a configuration file.

Default File and Test Patterns

Wallaby provides default settings for files and tests and requires that at least one test file imports node:test to detect and configure your project. The default settings are shown below:

module.exports = () => ({
  autoDetect: ['node:test'],

  // Defaults source file patterns
  files: [
    // Excludes
    '!**/node_modules/**',
    '!**/dist/**',
    '!**/cypress/**',
    '!**/.{idea,git,cache,output,temp}/**',
    '!**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build}.config.*'
    '!**/*.{test,spec}.?(c|m)[jt]s?(x)',

    // Include all other files
    '**/**',
  ],

  // Default test file name pattern
  tests: [
    '**/*.{test,spec}.?(c|m)[jt]s?(x)',
  ]
});

TypeScript Compilers

If you are using TypeScript, Wallaby will automatically detect and configure your TypeScript compiler settings. Wallaby provides built-in support for TypeScript and will attempt to resolve the TypeScript compiler based on your project dependencies in the following order:

1. @swc-node/register
2. ts-node
3. tsx
4. esbuild-register (does not support ESM projects)

If you have one of the above TypeScript compilers installed in your project, there is no need to do anything else. If you do not have one of the above TypeScript compilers installed, you will need to install one of them in your project.

Wallaby’s TypeScript compiler resolution is set automatically using Wallaby’s esmHooks and preloadModules settings. You may override these settings in your Wallaby configuration file if you need to use a different TypeScript compiler, or if you need to configure another esm hook or preload module.

module.exports = () => ({
  autoDetect: ['node:test'],

  // Default override esm hooks settings if not specified
  esmHooks: [
    '@swc-node/register/esm-register',
    'ts-node/esm',
    'tsx/esm',
  ],

  // Default preload modules settings if not specified
  preloadModules: [
    '@swc-node/register',
    'ts-node/register',
    'tsx/cjs',
    'esbuild-register',
  ]
});

Limiting Automatic Configuration to node:test

If your project uses multiple testing frameworks supported by Wallaby’s automatic configuration, they will be resolved first and node:test will be ignored. To explicitly specify for Wallaby to only try to use node:test, you must set the autoDetect setting by providing and using a Wallaby configuration file:

module.exports = () => ({
  autoDetect: ['node:test']
});

Overriding Automatic Configuration

Sometimes you may want to add/override some Wallaby configuration settings to the automatically detected settings. For example, if you want to exclude some tests when you are using Wallaby but not when you are running tests from the command-line or Continuous Integration build. You may configure an override in a configuration file or package.json section.

After creating Wallaby config file to override automatic defaults in VS Code you need to run Select Configuration command and then select the config file once. After that you may keep using Wallaby Start command as usual and it will start Wallaby with the configuration file.

After creating Wallaby config file to override automatic defaults in JetBrains IDEs, you may edit (or create a new) wallaby.js Run Configuration by selecting Edit configurations from the drop-down menu in the top right-hand corner of the navigation bar, or from the Run menu. In the run configuration editor set Configuration Type filed value to Configuration File.

Note that if you are adding/overriding files/tests, then you need to add the autoDetect: true setting:

module.exports = () => ({
  autoDetect: true, // or autoDetect: ['node:test']

  // modify `files` automatic configuration settings
  files: {
    override: (filePatterns) => {
      // TODO: modify `filePatterns` array as required
      return filePatterns;
    }
  },

  // modify `tests` automatic configuration settings
  tests: {
    override: (testPatterns) => {
      // TODO: modify `testPatterns` array as required
      return testPatterns;
    }
  }
});

.only Behavior

When using Wallaby with node:test testing framework, .only behaves slightly differently compared to other testing frameworks.

By default, when you run tests using Node’s test runner, all tests will execute, including those marked with .only. If you want to run only .only tests, you need to start the Node test runner CLI with the --test-only option.

Wallaby currently follows the default Node test runner behavior, where all tests (both .only and others) are executed. It is not currently possible to run Wallaby with the --test-only option.

Node settings

Node version

If you’d like to use your system default node.js version or any specific locally installed version instead of using the version configured for your IDE or editor, use the env.runner property to specify a command to invoke node or a path to a node executable.

module.exports = function () {
  return {
    ...
    env: {
      runner: 'node', // or full path to any node executable
    },
  };
};

Node flags

If you need to pass some node flags, such as --harmony, you may use env.params.runner property for that:

module.exports = function () {
  return {
    ...

    env: {
      params: {
        runner: '--harmony --harmony_arrow_functions',
      },
    },
  };
};

Environment variables

If you need to pass some process.env variables to the test environment, you may just set them right in the wallaby config file:

module.exports = function () {

  process.env.NODE_ENV = 'development';

  return {
    ...
  };
};

Alternatively, you may use env.params.env property for it:

module.exports = function () {
  return {
    ...

    env: {
      params: {
        env: 'NODE_PATH=/a/b/c;HOME=/Users/a/b',
      },
    },
  };
};

Node process reuse

When running your node.js tests, wallaby by default tries to re-use previously created node.js process(es) to make the runs faster. If you are relying on the test node process re-start for each run, because your tests are not cleaning after themselves (for example, they are not closing opened database connections, not stopping started web services, or are registering some callbacks that may be invoked after your test run finishes and interfere with your next test run), then you may use workers.restart setting set to true to make wallaby.js re-start node process for each run.

module.exports = function () {
  return {
    ...

    workers: {
      restart: true,
    },
  };
};

Whether you use the setting or not, you will still benefit from wallaby.js incremental test run feature compared to the normal test runner. However, while using the setting allows you to rely on the process re-start and avoid writing any cleanup code, we recommend that you consider adding clean-up code and not recycling node workers, as wallaby.js will be able to run your tests even faster if node processes are reusable.

Node process count

By default, wallaby.js automatically decides how many processes to use to run your tests in parallel based on your system capacity. However, sometimes you may need to manually set the number of workers to be used. For example, if your tests are creating an HTTP server that is listening on a certain port (as opposed to using dynamic port allocation for your tests), you may need to set the workers count to 1, because otherwise you may have issues with different test workers trying to create the server on the same port.

module.exports = function () {
  return {
    ...


    workers: {
      initial: 1,
      regular: 1,
    },
  };
};

A better approach would be to dynamically allocate ports, so that your tests could run in parallel.

Troubleshooting

The first step of troubleshooting your project is to identify whether the same results are returned using node --test ... from the command-line. Running node --test ... from the command-line will usually show/highlight the cause of your problem.

If Wallaby is not working but node --test ... CLI is working, please report this to the Wallaby team.

If you get stuck or something isn’t working for you, you may find further troubleshooting steps here or else find a similar solved issue in our github issues repository. If you can’t find a solution, create a new issue.