Is There a Standard Syntax for Mocha's (BDD) Describe, and if so What is the Logic Behind It?

Question

If you look at the examples on the official Mocha page, you'll see that they use the following describe syntax (for their BDD mode):

describe('Array', function() {
    describe('#indexOf()', function () {

However, I can't seem to find anything (on the Mocha site or elsewhere) explaining why the second describe should be #indexOf() and not #indexOf or just indexOf. #indexOf seems to be a pretty common format (I've seen it in OSS code), but I've never seen anyone add parenthesis before. Then again, the Mocha people certainly know a lot more about testing than I do, so I've got to figure they use that syntax for a reason.

So, my question is, can anyone point me towards a resource that either:

• is a "source of truth" (eg. somewhere on the Mocha site, or on some major testing site) saying that ____ is the default convention for describe (I realize this might not even be a JS source at all, since I know a lot of this stuff originated in RSpec)
• describes the practical benefits of adopting this syntax

And if you could provide one of each (or one that does both) that'd be even better. Alternatively I'd also love a direct answer (ie. not a link to a resource), if its possible to just explain it directly.

Basically I just want to understand where this syntax came from and why I should use it (with both "because smart person ____ said so" and "because of practical reason ____" being legitimate answers).

Answer 1

I don't have an authoritative source regarding this. The #indexOf() is not special as far as Mocha is concerned. It treats it as it would treat any other text.

The only similar syntax I've ever encountered is JSDoc's syntax for referring to parts of a class. The #name syntax is used to refer to members that are used on instances of a class. In the JSDoc 3 syntax Array#indexOf is a meaningful expression which refers to the indexOf method used on an Array instance. Note how I do not have the parentheses though. I don't recall ever using parentheses in JSDoc 3.

The [documentation](MyConstructor#instanceMember MyConstructor.staticMember MyConstructor~innerMember) gives an example of instance, static and inner functions:

/** @constructor */
Person = function() {
    this.say = function() {
        return "I'm an instance.";
    }

    function say() {
        return "I'm inner.";
    }
}
Person.say = function() {
    return "I'm static.";
}

var p = new Person();
p.say();      // I'm an instance.
Person.say(); // I'm static.
// there is no way to directly access the inner function from here

And shows how you would refer to them in JSDoc 3 documentation:

Person#say  // the instance method named "say."
Person.say  // the static method named "say."
Person~say  // the inner method named "say."

JSDoc 3 reused this syntax (with one modification for inner methods) from JSDoc 2, which, as far as I can tell, predates Mocha.