doc: move describe/it aliases section before expectFailure

[lraveri]

The “Expecting tests to fail” section uses it() before the documentation explains that it() is an alias of test().

This reorders the relevant documentation sections so that the describe() / it() aliases are introduced before being used, improving readability for first-time readers.

[nodejs-github-bot]

Review requested:

• @nodejs/test_runner

[JakobJingleheimer]

I presume this is a cut-paste

[lraveri]

I presume this is a cut-paste

yep, it is

[vassudanagunta]

I think clarity would be better served by keeping all the flag options for test together: skip, todo, expectFailure, only.

IMHO one of the following:

• change the example for expectFailure to use test instead of it. The consistency with the examples for skip and todo makes it easier to learn.

• if it and describe are so common that the learner should get used to them, then move the describe/it aliases section to the top. Then examples for other features can use either.

[JakobJingleheimer]

Let's write a proposal for it (in the nodejs/test_runner repo)

[JakobJingleheimer]

Ack, sorry. My request for a proposal was meant for a different expectFailure thread (the one about expectFailure: message) 🤦‍♂️

I think clarity would be better served by keeping all the flag options for test together: skip, todo, expectFailure, only.

I think this is probably better (and move describe & it above them).

[lraveri]

Ack sorry. My request for a proposal was meant for a different test-runner thread 🤦‍♂️ (the one about expectFail: message).

No worries. I think @vassudanagunta is right and we can change the example for expectFailure to use test instead of it and move the describe / it section where it was before.

WDYT? @JakobJingleheimer

[JakobJingleheimer]

I think either is fine, but regardless of it vs test, do keep the flags together in the docs.

I think it's slightly better to use it & describe because it's more obvious which is what than nested tests

[lraveri]

Ok, I moved the it / describe section up and grouped the flag sections together.

Here the final structure: