From 4c1db7d9638ca4c4057c788b5ec2d7dac5a6744b Mon Sep 17 00:00:00 2001
From: Luca Raveri <lucaraveri993@gmail.com>
Date: Wed, 28 Jan 2026 17:16:55 +0100
Subject: [PATCH] doc: move describe/it aliases section before expectFailure

---
 doc/api/test.md | 68 ++++++++++++++++++++++++-------------------------
 1 file changed, 34 insertions(+), 34 deletions(-)

diff --git a/doc/api/test.md b/doc/api/test.md
index b12e6c9212af3b..1707e7b8f9c743 100644
--- a/doc/api/test.md
+++ b/doc/api/test.md
@@ -224,6 +224,40 @@ test('todo() method with message', (t) => {
 });
 ```
 
+## `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');
+```
+
 ## Expecting tests to fail
 
 <!-- YAML
@@ -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