Why does describe.skip still execute code in the suite?

[oliversalzburg]

In a test file I have code similar to this:

describe.skip( "skip this", () => {
	throw new Error( "was executed anyway" );
} );

I expected that describe.skip skips executing the entire suite, but it only skips executing tests declared in it. Is that by-design? I feel like the documentation is unclear about this.

[juergba]

Yes, this behavior is made by design, please see #3630 (comment)

[plroebuck]

Although the comment from #3630 answers his question, I'm reopening this.

Since it is not the first issue brought up on the subject, the relevant documentation should be updated to make clear that describe.skip is really just syntactic sugar for marking any child test (it) as if it had been written as it.skip, but the namespace (i.e., describe's function argument) is still executed.

[oliversalzburg]

@plroebuck That'd be great. I often refer to the mocha documentation, even though I have been using it for years and this surprised me. I'm amazed I haven't noticed this earlier.

But I believe the relevant documentation should be https://mochajs.org/#inclusive-tests, which currently states:

By appending .skip(), you may tell Mocha to simply ignore these suite(s) and test case(s).

This is misleading, because the suites aren't ignored, only the tests contained within them.

[plroebuck]

@oliversalzburg, care to draft what it should say?

[oliversalzburg]

The documentation currently starts the introduction to inclusive tests with suites, then points out the behavior for individual tests. I think it would be better to start with the tests, then say that putting .skip on a suite is identical to putting .skip on every test in the suite (and that is also overrides any .only on tests in that suite) and skipping hooks declared in the suite.

I believe that is different, because if you'd put .skip on every test individually, then you'd have no reason to think remaining code in the suite was ignored.

What do you think?

[plroebuck]

Difficult to evaluate without seeing the replacement text...

[oliversalzburg]

@plroebuck Could you have a look at my PR?