Sometimes you don’t want to run your entire test suite. Here are five ways to do it.

Versions used below

{
  "mocha": "2.1.0"
}

1. File pattern

This is an easy but coarse-grained way to control what gets run. It may be all you need depending on how your tests are divided up.

You can run specific test files

$ mocha test/login-required.js

When not given a pattern, Mocha runs ./test/*.js.

2. grep

Passing --grep <pattern> on the command line will run tests and suites with names matching the pattern.

$ mocha --grep auth

3. grep with invert

Adding --invert to a command line with --grep <pattern> runs tests and suites with names that do not match the pattern.

$ mocha --grep auth --invert

4. only

Chain an it with .only(). Mocha will only run the test with the .only().

describe("using only", function() {
  it.only("this is the only test to be run", function() {

  });

  it("this is not run", function() {

  });
});

describe blocks

You can also chain .only() on a describe block to run that block exclusively.

Gotcha

.only() is implemented using the grep option. Similar naming could cause extra tests to run (issue 1481).

5. skip

This is like the reverse of .only(). Mocha will run all tests except the ones with .skip().

describe("using skip", function() {
  it.skip("this is not run", function() {

  });

  it("this runs", function() {

  });

  it("this runs too", function() {

  });
});

describe blocks

You can also chain .skip() on describe blocks to ignore the block.

6. tagging (unreleased as of Mocha 2.1.0)

A new tagging api could be coming to Mocha. This seems like it’d trump all other methods of test filtering.