Wallaby.js Introduction: Running selected test(s)

Wallaby provides a number of options for optimizing the execution and output of your test runs. You may run a selected test, or set of tests, and may limit code coverage and runtime value output to only the test(s) you are working on. Together with with Value Explorer and Advanced Logging, these features enable a highly productive workflow.

Exclusive test run

If you are working in a larger project and only want to run a subset of tests, Wallaby’s Exclusive Test Run feature for VS Code and JetBrains IDEs allows you to start Wallaby for a selected file or folder using the Start Exclusive Test Run command.

Wallaby’s Smart Start feature is very similar in behavior to an Exclusive Test Run and may be preferred if you find you are often using the Exclusive Test Run feature.

After Wallaby has started, when you open any other tests (that were not a part of the original exclusive test run), the opened test files will be automatically added to the test run and executed. This way you may start Wallaby very quickly on a large project by executing a single test file that you are planning to start working on, and then automatically add more tests as you open them. You may override the default behavior to only add on edit or to never add using the Smart Start configuration settings.

You may also manually add more tests found within a file or folder to the Exclusive Test Run using the Add to Exclusive Test Run command.

If Wallaby was started normally (without using Start Exclusive Test Run) then the first time Add to Exclusive Test Run is used after start, only the tests for the selected file or folder will be executed.

Note: when using Jest, Webpack or Angular CLI, Wallaby’s Exclusive Test Run feature only processes selected test files which may be many times faster than running all tests within your project.

Test filtering

Wallaby’s Test Filtering feature allows you to limit the display of inline code coverage indicators and inline run-time values to only the test that you are working on instead of all tests in your project.

Test Filtering allows you to switch focus between individual tests and their execution results instantly. Editor-specific commands are referenced on each editor’s tutorial page (VS Code, JetBrains IDEs, Visual Studio, Sublime). Filter selection can also be toggled within Wallaby App.

Note: Test filtering will continue to run all tests affected by the code changes that you make. If the number of tests has been limited by an Exclusive Test Run, Test focusing, or Test file selection, then only those tests will be executed.

Test focusing

Sometimes when writing or debugging a test, set of tests or a test file for a particular feature, you may need to see code coverage and output only for this specific test, set of tests or test file.

However, because a piece of code can be covered by multiple tests (from the same test file, or from multiple test files), by default wallaby re-runs all affected tests and displays combined code coverage for the covered piece of code.

Testing frameworks support special functions, that allow to focus a specific test or a test suite. In Jest, Mocha, and AVA you may use .only to specify which tests are the only ones you want to run in a test file:

describe('suite', () => {
  it.only('test 1', () => { // to only run test 1
    ...
  });

  it('test 2', () => {
    ...
  });
});

describe.only('suite 1', () => { // to only run suite 1
  ...
});

describe('suite 2', () => {
  ...
});

In Jasmine you may use fit/fdescribe:

describe('suite', () => {
  fit('test 1', () => { // to only run test 1
    ...
  });

  it('test 2', () => {
    ...
  });
});

fdescribe('suite 1', () => { // to only run suite 1
  ...
});

describe('suite 2', () => {
  ...
});

When wallaby detects the use of the test/suite focusing functions in a test file, it automatically starts running only this specific test/suite, and stops running tests from other test files. As a result, in this mode wallaby will display code coverage and output only for this specific test/suite.

To find out whether wallaby is operating in this mode and is only executing some of your tests, you may inspect the Wallaby Tests output header. In the default mode it usually says:

No failing tests, N passing

and if some tests are selected, it’ll also display names of test files with focused/selected tests.

No failing tests, N passing (only executed test.js)

Note: unlike the Exclusive Test Run feature which is reset when Wallaby stops, if your code is unchanged, the focused tests will be the same when Wallaby is restarted.

Additional configuration

Because wallaby attempts to detect the use of test focusing functions before actually running your tests, it may sometimes miss some cases (or produce false positives) due to the dynamic nature of JavaScript and because of the unlimited variety of ways to use the test focusing functions.

If you have some focused tests/suite in a test file, but wallaby is still displaying results from other test files, you may force wallaby to select and run this specific test file only, by adding the special file.only comment anywhere in the test file:

// file.only
...

This way wallaby will only be running focused tests from the test file, or all tests in the test file if none of them is marked with a test selection function, such as .only/fit.

If you encounter a scenario when using the automatic test focusing is not desirable, you may turn the feature off in your wallaby config:

module.exports = function (wallaby) {
  return {
    ...
    automaticTestFileSelection: false
  };
};

Test file selection

Sometimes you may also need to tell wallaby to only run (or to ignore) a specific test file (or a set of test files), without changing your wallaby config file. To allow it, wallaby supports special comments.

To only run a specific test file (or test files), you may add the following comment anywhere in the test file (or files):

// file.only
...

To skip a specific test file (or test files) and don’t run it, you may add the following comment anywhere in the test file (or files):

// file.skip
...

You may change the default comments by using the hints.testFileSelection setting and by specifying any regular expression you want:

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

    hints: {
      testFileSelection: {
        include: /file\.only/,
        exclude: /file\.skip/
      }
    }
  };
};

If you want to configure wallaby to run zero tests if none are selected, rather than run all the tests if none are selected, you may use the runSelectedTestsOnly setting:

module.exports = function (wallaby) {
  return {
    ...
    runSelectedTestsOnly: true
  };
};

Once configured this way, Wallaby will not run any tests until you select some of them by using .only/fit modifiers or special comment.

For example if you want to only work with some set of tests within a describe block, you may add a .only modifier to the block:

describe.only('...', () => {
  ...
});

and only tests in that block will be running.

If you want a specific test to run, you may do the same to the test:

it.only('...', () => {
  ...
});

If you want to run all tests in a test file, you may add the // file.only comment anywhere in the test file’s code.