Description
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?