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