10 files changed, 51 insertions, 36 deletions
diff --git a/docs/guides/test/bail.md b/docs/guides/test/bail.md
index 06129314f..c994de2df 100644
--- a/docs/guides/test/bail.md
+++ b/docs/guides/test/bail.md
@@ -5,7 +5,6 @@ name: Bail early with the Bun test runner
 Use the `--bail` flag to bail on a test run after a single failure. This is useful for aborting as soon as possible in a continuous integration environment.
 
 ```sh
-# re-run each test 10 times
 $ bun test --bail
 ```
 
diff --git a/docs/guides/test/coverage-threshold.md b/docs/guides/test/coverage-threshold.md
index 4180c6f1a..d0883df58 100644
--- a/docs/guides/test/coverage-threshold.md
+++ b/docs/guides/test/coverage-threshold.md
@@ -45,6 +45,8 @@ $ echo $?
 1 # this is the exit code of the previous command
 ```
 
+---
+
 Different thresholds can be set for line-level and function-level coverage.
 
 ```toml
diff --git a/docs/guides/test/coverage.md b/docs/guides/test/coverage.md
index 6103dbb90..a09d8103a 100644
--- a/docs/guides/test/coverage.md
+++ b/docs/guides/test/coverage.md
@@ -2,7 +2,7 @@
 name: Generate code coverage reports with the Bun test runner
 ---
 
-Bun's test runner supports built-in _code coverage reporting_. This makes it easy to see how much of the codebase is covered by tests, and find areas that are not currently well-tested.
+Bun's test runner supports built-in _code coverage reporting_. This makes it easy to see how much of the codebase is covered by tests and find areas that are not currently well-tested.
 
 ---
 
diff --git a/docs/guides/test/happy-dom.md b/docs/guides/test/happy-dom.md
index 42e225a5d..9c6728f88 100644
--- a/docs/guides/test/happy-dom.md
+++ b/docs/guides/test/happy-dom.md
@@ -14,7 +14,7 @@ $ bun add -d @happy-dom/global-registrator
 
 ---
 
-This module exports a "registrator" that will adds the mocked browser APIs to the global scope.
+This module exports a "registrator" that injects the mocked browser APIs to the global scope.
 
 ```ts#happydom.ts
 import { GlobalRegistrator } from "@happy-dom/global-registrator";
@@ -24,7 +24,7 @@ GlobalRegistrator.register();
 
 ---
 
-We need to make sure this file is executed before any of our test files. That's a job for Bun's built-in _preload_ functionality. Create a `bunfig.toml` file in the root of your project (if it doesn't already exist) and add the following lines.
+We need to make sure this file is executed before any of our test files. That's a job for Bun's built-in [_preload_]() functionality. Create a `bunfig.toml` file in the root of your project (if it doesn't already exist) and add the following lines.
 
 The `./happydom.ts` file should contain the registration code above.
 
diff --git a/docs/guides/test/mock-clock.md b/docs/guides/test/mock-clock.md
index 315c33f9f..d3876b6a1 100644
--- a/docs/guides/test/mock-clock.md
+++ b/docs/guides/test/mock-clock.md
@@ -5,7 +5,7 @@ name: Set the system time in Bun's test runner
 Bun's test runner supports setting the system time programmatically with the `setSystemTime` function.
 
 ```ts
-import { test, expect, beforeAll, setSystemTime } from "bun:test";
+import { test, expect, setSystemTime } from "bun:test";
 
 test("party like it's 1999", () => {
   const date = new Date("1999-01-01T00:00:00.000Z");
diff --git a/docs/guides/test/run-tests.md b/docs/guides/test/run-tests.md
index 6d72f43ec..14887b239 100644
--- a/docs/guides/test/run-tests.md
+++ b/docs/guides/test/run-tests.md
@@ -2,12 +2,22 @@
 name: Run your tests with the Bun test runner
 ---
 
-Bun has a built-in test runner with a Jest-like `expect` API. To use it, run `bun test` from your project directory. The test runner will search for all files in the directory that match the following patterns:
+Bun has a built-in [test runner](/docs/cli/test) with a Jest-like `expect` API.
 
-- `*.test.{js|jsx|ts|tsx}`
-- `*_test.{js|jsx|ts|tsx}`
-- `*.spec.{js|jsx|ts|tsx}`
-- `*_spec.{js|jsx|ts|tsx}`
+---
+
+To use it, run the `bun test` command from your project directory. The test runner will recursively search for all files in the directory that match the following patterns and execute the tests they contain.
+
+```txt
+*.test.{js|jsx|ts|tsx}
+*_test.{js|jsx|ts|tsx}
+*.spec.{js|jsx|ts|tsx}
+*_spec.{js|jsx|ts|tsx}
+```
+
+---
+
+Here's what the output of a typical test run looks like. In this case, there are three tests files (`test.test.js`, `test2.test.js`, and `test3.test.js`) containing two tests each (`add` and `multiply`).
 
 ```sh
 $ bun test
@@ -51,17 +61,19 @@ Ran 2 tests across 1 files. [15.00ms]
 
 ---
 
-All tests have a name, defined as the first parameter to the `test` function. Tests can also be inside a `describe` block.
+All tests have a name, defined using the first parameter to the `test` function. Tests can also be grouped into suites with `describe`.
 
 ```ts
 import { test, expect } from "bun:test";
 
-test("add", () => {
-  expect(2 + 2).toEqual(4);
-});
+describe("math", () => {
+  test("add", () => {
+    expect(2 + 2).toEqual(4);
+  });
 
-test("multiply", () => {
-  expect(2 * 2).toEqual(4);
+  test("multiply", () => {
+    expect(2 * 2).toEqual(4);
+  });
 });
 ```
 
@@ -69,7 +81,7 @@ test("multiply", () => {
 
 To filter which tests are executed by name, use the `-t`/`--test-name-pattern` flag.
 
-Adding `-t add` will only run tests with "add" in the name. This flag also checks the name of the test suite (the first parameter to `describe`).
+Adding `-t add` will only run tests with "add" in the name. This works with test names defined with `test` or test suite names defined with `describe`.
 
 ```sh
 $ bun test -t add
diff --git a/docs/guides/test/skip-tests.md b/docs/guides/test/skip-tests.md
index c067c8fc7..e56c29932 100644
--- a/docs/guides/test/skip-tests.md
+++ b/docs/guides/test/skip-tests.md
@@ -4,8 +4,10 @@ name: Skip tests with the Bun test runner
 
 To skip a test with the Bun test runner, use the `test.skip` function.
 
-```ts-diff
-test.skip("unimplemented feature", ()=>{
+```ts
+import { test } from "bun:test";
+
+test.skip("unimplemented feature", () => {
   expect(Bun.isAwesome()).toBe(true);
 });
 ```
diff --git a/docs/guides/test/snapshot.md b/docs/guides/test/snapshot.md
index 352cfa81c..69f4cc619 100644
--- a/docs/guides/test/snapshot.md
+++ b/docs/guides/test/snapshot.md
@@ -18,7 +18,7 @@ test("snapshot", () => {
 
 ---
 
-The first time this test is executed, Bun will evaluate the value passed into `expect()` (`{ foo: "bar" }`) and write it to disk in a directory called `__snapshots__` that lives alongside the test file.
+The first time this test is executed, Bun will evaluate the value passed into `expect()` and write it to disk in a directory called `__snapshots__` that lives alongside the test file. (Note the `snapshots: +1 added` line in the output.)
 
 ```sh
 $ bun test test/snap
@@ -29,7 +29,7 @@ test/snap.test.ts:
 
  1 pass
  0 fail
- snapshots: +1 added   # note: the snapshot is created automatically the first run
+ snapshots: +1 added
  1 expect() calls
 Ran 1 tests across 1 files. [82.00ms]
 ```
diff --git a/docs/guides/test/spy-on.md b/docs/guides/test/spy-on.md
index 3a43b2367..003c05d96 100644
--- a/docs/guides/test/spy-on.md
+++ b/docs/guides/test/spy-on.md
@@ -8,7 +8,7 @@ Use the `spyOn` utility to track method calls with Bun's test runner.
 import { test, expect, spyOn } from "bun:test";
 
 const leo = {
-  name: "Leonard",
+  name: "Leonardo",
   sayHi(thing: string) {
     console.log(`Sup I'm ${this.name} and I like ${thing}`);
   },
@@ -27,7 +27,7 @@ Once the spy is created, it can be used to write `expect` assertions relating to
   const leo = {
     name: "Leonardo",
     sayHi(thing: string) {
-      console.log(`Sup, I'm ${this.name} and I like ${thing}`);
+      console.log(`Sup I'm ${this.name} and I like ${thing}`);
     },
   };
 
diff --git a/docs/guides/test/todo-tests.md b/docs/guides/test/todo-tests.md
index 301cd2e00..e7310b0b3 100644
--- a/docs/guides/test/todo-tests.md
+++ b/docs/guides/test/todo-tests.md
@@ -13,18 +13,6 @@ test.todo("unimplemented feature");
 
 ---
 
-Optionally, you can provide a test implementation.
-
-```ts
-import { test, expect } from "bun:test";
-
-test.todo("unimplemented feature", () => {
-  expect(Bun.isAwesome()).toBe(true);
-});
-```
-
----
-
 The output of `bun test` indicates how many `todo` tests were encountered.
 
 ```sh
@@ -44,7 +32,19 @@ Ran 3 tests across 1 files. [74.00ms]
 
 ---
 
-Note that `todo` tests _are executed_ by the test runner! They are _expected to fail_; if a todo test passes, the `bun test` run will return a non-zero exit code to signal the failure.
+Optionally, you can provide a test implementation.
+
+```ts
+import { test, expect } from "bun:test";
+
+test.todo("unimplemented feature", () => {
+  expect(Bun.isAwesome()).toBe(true);
+});
+```
+
+---
+
+If an implementation is provides, it will be executed and _expected to fail_ by test runner! If a todo test passes, the `bun test` run will return a non-zero exit code to signal the failure.
 
 ```sh
 $ bun test