Inclusive Tests

This feature is the inverse of .only(). By appending .skip(), you may tell Mocha to ignore test case(s). Anything skipped will be marked as pending, and reported as such. Here’s an example of skipping an individual test:

describe("Array", function () {
  describe("#indexOf()", function () {
    it.skip("should return -1 unless present", function () {
      // this test will not be run
    });

    it("should return the index when present", function () {
      // this test will be run
    });
  });
});

You can also put .skip() on an entire suite. This is equivalent to appending .skip() onto all tests in the suite. Hooks in the suite are also skipped.

describe("Array", function () {
  describe.skip("#indexOf()", function () {
    it("should return -1 unless present", function () {
      // this test will not be run
    });
  });
});

Note: Code in skipped suites, that is placed outside of hooks or tests is still executed, as mocha will still invoke the suite function to build up the suite structure for visualization.

Best practice

Use .skip() instead of commenting tests out.

You may also skip at runtime using this.skip(). If a test needs an environment or configuration which cannot be detected beforehand, a runtime skip is appropriate. For example:

it('should only test in the correct environment', function() {
  if (/* check test environment */) {
    // make assertions
  } else {
    this.skip();
  }
});

The above test will be reported as pending. It’s also important to note that calling this.skip() will effectively abort the test.

Best practice

To avoid confusion, do not execute further instructions in a test or hook after calling this.skip().

Contrast the above test with the following code:

it('should only test in the correct environment', function() {
  if (/* check test environment */) {
    // make assertions
  } else {
    // do nothing
  }
});

Because this test does nothing, it will be reported as passing.

Best practice

Don’t do nothing! A test should make an assertion or use this.skip().

To skip multiple tests in this manner, use this.skip() in a “before all” hook:

before(function() {
  if (/* check test environment */) {
    // setup code
  } else {
    this.skip();
  }
});

This will skip all it, beforeEach/afterEach, and describe blocks within the suite. before/after hooks are skipped unless they are defined at the same level as the hook containing this.skip().

describe("outer", function () {
  before(function () {
    this.skip();
  });

  after(function () {
    // will be executed
  });

  describe("inner", function () {
    before(function () {
      // will be skipped
    });

    after(function () {
      // will be skipped
    });
  });
});

Updated in v7.0.0

Skipping a test within an “after all” hook is disallowed and will throw an exception. Use a return statement or other means to abort hook execution.

Before Mocha v3.0.0, this.skip() was not supported in asynchronous tests and hooks.