Repository: nodejs/node
Pull request: doc: move describe/it aliases section before expectFailure

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.

Changed files:
filename: doc/api/test.md
patch: @@ -125,34 +125,6 @@ Any subtests that are still outstanding when their parent finishes
 are cancelled and treated as failures. Any subtest failures cause the parent
 test to fail.
 
-## Skipping tests
-
-Individual tests can be skipped by passing the `skip` option to the test, or by
-calling the test context's `skip()` method as shown in the
-following example.
-
-```js
-// The skip option is used, but no message is provided.
-test('skip option', { skip: true }, (t) => {
-  // This code is never executed.
-});
-
-// The skip option is used, and a message is provided.
-test('skip option with message', { skip: 'this is skipped' }, (t) => {
-  // This code is never executed.
-});
-
-test('skip() method', (t) => {
-  // Make sure to return here as well if the test contains additional logic.
-  t.skip();
-});
-
-test('skip() method with message', (t) => {
-  // Make sure to return here as well if the test contains additional logic.
-  t.skip('this is skipped');
-});
-```
-
 ## Rerunning failed tests
 
 The test runner supports persisting the state of the run to a file, allowing
@@ -193,6 +165,68 @@ When the `--test-rerun-failures` option is used, the test runner will only run t
 node --test-rerun-failures /path/to/state/file
 ```
 
+## `describe()` and `it()` aliases
+
+Suites and tests can also be written using the `describe()` and `it()`
+functions. [`describe()`][] is an alias for [`suite()`][], and [`it()`][] is an
+alias for [`test()`][].
+
+```js
+describe('A thing', () => {
+  it('should work', () => {
+    assert.strictEqual(1, 1);
+  });
+
+  it('should be ok', () => {
+    assert.strictEqual(2, 2);
+  });
+
+  describe('a nested thing', () => {
+    it('should work', () => {
+      assert.strictEqual(3, 3);
+    });
+  });
+});
+```
+
+`describe()` and `it()` are imported from the `node:test` module.
+
+```mjs
+import { describe, it } from 'node:test';
+```
+
+```cjs
+const { describe, it } = require('node:test');
+```
+
+## Skipping tests
+
+Individual tests can be skipped by passing the `skip` option to the test, or by
+calling the test context's `skip()` method as shown in the
+following example.
+
+```js
+// The skip option is used, but no message is provided.
+test('skip option', { skip: true }, (t) => {
+  // This code is never executed.
+});
+
+// The skip option is used, and a message is provided.
+test('skip option with message', { skip: 'this is skipped' }, (t) => {
+  // This code is never executed.
+});
+
+test('skip() method', (t) => {
+  // Make sure to return here as well if the test contains additional logic.
+  t.skip();
+});
+
+test('skip() method with message', (t) => {
+  // Make sure to return here as well if the test contains additional logic.
+  t.skip('this is skipped');
+});
+```
+
 ## TODO tests
 
 Individual tests can be marked as flaky or incomplete by passing the `todo`
@@ -275,40 +309,6 @@ it.todo('should do the thing', { expectFailure: true }, () => {
 });
 ```
 
-## `describe()` and `it()` aliases
-
-Suites and tests can also be written using the `describe()` and `it()`
-functions. [`describe()`][] is an alias for [`suite()`][], and [`it()`][] is an
-alias for [`test()`][].
-
-```js
-describe('A thing', () => {
-  it('should work', () => {
-    assert.strictEqual(1, 1);
-  });
-
-  it('should be ok', () => {
-    assert.strictEqual(2, 2);
-  });
-
-  describe('a nested thing', () => {
-    it('should work', () => {
-      assert.strictEqual(3, 3);
-    });
-  });
-});
-```
-
-`describe()` and `it()` are imported from the `node:test` module.
-
-```mjs
-import { describe, it } from 'node:test';
-```
-
-```cjs
-const { describe, it } = require('node:test');
-```
-
 ## `only` tests
 
 If Node.js is started with the [`--test-only`][] command-line option, or test