How to make empty placeholder tests intentionally fail in Mocha?

Question

I'm writing an API in NodeJS and testing using Mocha, Chai and SuperTest. I'm using a typical test-driven approach of writing the tests first then satisfying those tests with working code. However, because of the number of tests for all the different permutations, I've started writing empty placeholder tests so that I have all the it('should...') descriptions in place to remind me what to test when I get to that feature. For example:

it 'should not retrieve documents without an authorized user', (done) ->
    done()

The problem with this is that done() is called without any assertion so the test is considered passing, so I've added the following assertion.

false.should.equal true # force failure

but it's a hack and the reason for failure that Mocha displays can seem confusing, especially when other full tests might be failing.

Is there any official way to intentionally fail placeholder tests like this in Mocha?

Answer 1

As of 05/19/2018 this is the official way: https://mochajs.org/#pending-tests

An unimplemented test shouldn't fail, it should be marked as pending.

A succinct method of marking a mocha test as not yet implemented is to not pass a callback function to the it handler.

describe("Traverse", function(){
    describe("calls the visitor function", function(){
        it("at every element inside an array")
        it("at every level of a tree")
    })
})

Running mocha test will display your unimplemented tests as pending.

$ mocha test

  Traverse
    calls the visitor function
      - at every element inside an array
      - at every level of a tree


  0 passing (13ms)
  2 pending

Answer 2

The official way to mark tests as not being ready for testing yet is to use skip, which is a method that appears as a field of describe and it. Here's an example:

describe("not skipped", function () {
    it("bar", function () {
        throw new Error("fail");
    });

    it.skip("blah", function () {
        throw new Error("fail");
    });
});

describe.skip("skipped", function () {
    it("something", function () {
        throw new Error("fail");
    });
});

The above code, when put in a test.js file and run with $ mocha --reporter=spec test.js, produces:

  not skipped
    1) bar
    - blah

  skipped
    - something


  0 passing (4ms)
  2 pending
  1 failing

  1) not skipped bar:
     Error: fail
      at Context.<anonymous> (/tmp/t33/test.js:3:15)
      at callFn (/home/ldd/local/lib/node_modules/mocha/lib/runnable.js:223:21)
      at Test.Runnable.run (/home/ldd/local/lib/node_modules/mocha/lib/runnable.js:216:7)
      at Runner.runTest (/home/ldd/local/lib/node_modules/mocha/lib/runner.js:374:10)
      at /home/ldd/local/lib/node_modules/mocha/lib/runner.js:452:12
      at next (/home/ldd/local/lib/node_modules/mocha/lib/runner.js:299:14)
      at /home/ldd/local/lib/node_modules/mocha/lib/runner.js:309:7
      at next (/home/ldd/local/lib/node_modules/mocha/lib/runner.js:247:23)
      at Object._onImmediate (/home/ldd/local/lib/node_modules/mocha/lib/runner.js:276:5)
      at processImmediate [as _immediateCallback] (timers.js:354:15)

The test names that are preceded by - are skipped. Also, in a terminal that supports colors the tests that are skipped appear in blue (by opposition to red for failed tests and green for passing). A skipped test is said to be "pending" so Mocha reports the number of skipped tests as "2 pending".