What is the use case of sub tests

[theScottyJam]

Affected URL(s)

https://nodejs.org/api/test.html#subtests

Description of the problem

Node describes this concept of a subtest, which was a novel concept to me - I'm not aware of any other test runner that does this sort of thing (not that I'm deeply familiar with tons of different test runners though). It's difficult to piece together from the small bit of documentation what subtests are meant for. My first impression was that they were just another way of doing the typical describe/it pattern - the parent test being the "describe" block and the subtests being the "it"s. But Node also provides explicit support for describe, so as far as I can tell that's not supposed to be it.

More recently, I figured out a different powerful use for it. You can do "arrange" and "act" logic in the parent test, and then different "assert"s in a number of subtests, thus allowing those asserts to fail independent of each other. This seemed really powerful to me, but then I found out that using sub-tests in this way created problems - specifically, if you were also using a beforeEach() or afterEach(), those would get run between every subtest, potentially cleaning things up between them, which could be problematic if your future subtests still needed things to not be cleaned up. I would assume that if what I was describing was really the intended use for them, then beforeEach() and afterEach() would be designed differently so as to not run on every subtest, only the parent test.

So, what is the use of these subtests? And could we update the documentation to help people like me who aren't familiar with this concept? Maybe by providing a more realistic example or something?

[marco-ippolito]

AFAIK it's the same behavior as BDD syntax (describe, it) @nodejs/test_runner

[MoLow]

its just another flavor/syntax for authoring tests. the behavior is pretty much the same

[MoLow]

Improvements to the documentation are always welcomed

[ljharb]

@theScottyJam i'm not aware of a test runner that doesn't support subtests - do you have one in mind that doesn't?

[theScottyJam]

Sorry for the delay in responding, and thanks for addressing the concerns - the documentation changes look great.

To @ljharb's point, the test runners I've used in the past are Mocha, Jasmine, and Jest, and as far as I can tell, none of those support subtests (though I haven't thoroughly read through all of the documentation of each one). I did find this issue confirming that Mocha doesn't support it.