docs(manual): split testing into multiple chapters (#11067)

Co-authored-by: Bartek Iwańczuk <biwanczuk@gmail.com>

docs/testing.md

@@ -11,8 +11,8 @@ TypeScript code.
 
 ## Writing tests
 
-To define a test you need to call `Deno.test` with a name and function to be
-tested. There are two styles you can use.
+To define a test you need to register it with a call to `Deno.test` with a name
+and function to be tested. There are two styles you can use.
 
 ```ts
 import { assertEquals } from "https://deno.land/std@$STD_VERSION/testing/asserts.ts";
@@ -33,24 +33,6 @@ Deno.test({
 });
 ```
 
-## Assertions
-
-There are some useful assertion utilities at
-https://deno.land/std@$STD_VERSION/testing#usage to make testing easier:
-
-```ts
-import {
-  assertArrayIncludes,
-  assertEquals,
-} from "https://deno.land/std@$STD_VERSION/testing/asserts.ts";
-
-Deno.test("hello world", () => {
-  const x = 1 + 2;
-  assertEquals(x, 3);
-  assertArrayIncludes([1, 2, 3, 4, 5, 6], [3], "Expected 3 to be in the array");
-});
-```
-
 ### Async functions
 
 You can also test asynchronous code by passing a test function that returns a
@@ -71,58 +53,6 @@ Deno.test("async hello world", async () => {
 });
 ```
 
-### Resource and async op sanitizers
-
-Certain actions in Deno create resources in the resource table
-([learn more here](./contributing/architecture.md)). These resources should be
-closed after you are done using them.
-
-For each test definition, the test runner checks that all resources created in
-this test have been closed. This is to prevent resource 'leaks'. This is enabled
-by default for all tests, but can be disabled by setting the `sanitizeResources`
-boolean to false in the test definition.
-
-The same is true for async operation like interacting with the filesystem. The
-test runner checks that each operation you start in the test is completed before
-the end of the test. This is enabled by default for all tests, but can be
-disabled by setting the `sanitizeOps` boolean to false in the test definition.
-
-```ts
-Deno.test({
-  name: "leaky test",
-  fn() {
-    Deno.open("hello.txt");
-  },
-  sanitizeResources: false,
-  sanitizeOps: false,
-});
-```
-
-### Exit sanitizer
-
-There's also the exit sanitizer which ensures that tested code doesn't call
-Deno.exit() signaling a false test success.
-
-This is enabled by default for all tests, but can be disabled by setting the
-`sanitizeExit` boolean to false in thetest definition.
-
-```ts
-Deno.test({
-  name: "false success",
-  fn() {
-    Deno.exit(0);
-  },
-  sanitizeExit: false,
-});
-
-Deno.test({
-  name: "failing test",
-  fn() {
-    throw new Error("this test fails");
-  },
-});
-```
-
 ## Running tests
 
 To run the test, call `deno test` with the file that contains your test
@@ -237,39 +167,3 @@ failure, you can specify the `--fail-fast` flag when running the suite.
 ```shell
 deno test --fail-fast
 ```
-
-## Test coverage
-
-Deno will collect test coverage into a directory for your code if you specify
-the `--coverage` flag when starting `deno test`.
-
-This coverage information is acquired directly from the JavaScript engine (V8)
-which is very accurate.
-
-This can then be further processed from the internal format into well known
-formats by the `deno coverage` tool.
-
-```
-# Go into your project's working directory
-git clone https://github.com/oakserver/oak && cd oak
-
-# Collect your coverage profile with deno test --coverage=<output_directory>
-deno test --coverage=cov_profile
-
-# From this you can get a pretty printed diff of uncovered lines
-deno coverage cov_profile
-
-# Or generate an lcov report
-deno coverage cov_profile --lcov > cov_profile.lcov
-
-# Which can then be further processed by tools like genhtml
-genhtml -o cov_profile/html cov_profile.lcov
-```
-
-By default, `deno coverage` will exclude any files matching the regular
-expression `test\.(js|mjs|ts|jsx|tsx)` and only consider including files
-matching the regular expression `^file:`.
-
-These filters can be overridden using the `--exclude` and `--include` flags. A
-source file's url must match both regular expressions for it to be a part of the
-report.

docs/testing/coverage.md

@@ -0,0 +1,36 @@
+# Test coverage
+
+Deno will collect test coverage into a directory for your code if you specify
+the `--coverage` flag when starting `deno test`.
+
+This coverage information is acquired directly from the JavaScript engine (V8)
+which is very accurate.
+
+This can then be further processed from the internal format into well known
+formats by the `deno coverage` tool.
+
+```bash
+# Go into your project's working directory
+git clone https://github.com/oakserver/oak && cd oak
+
+# Collect your coverage profile with deno test --coverage=<output_directory>
+deno test --coverage=cov_profile
+
+# From this you can get a pretty printed diff of uncovered lines
+deno coverage cov_profile
+
+# Or generate an lcov report
+deno coverage cov_profile --lcov > cov_profile.lcov
+
+# Which can then be further processed by tools like genhtml
+genhtml -o cov_profile/html cov_profile.lcov
+```
+
+By default, `deno coverage` will exclude any files matching the regular
+expression `test\.(js|mjs|ts|jsx|tsx)` and only consider including specifiers
+matching the regular expression `^file:` - ie. remote files will be excluded
+from coverage report.
+
+These filters can be overridden using the `--exclude` and `--include` flags. A
+module specifier must _match_ the include_regular expression and _not match_ the
+exclude_ expression for it to be a part of the report.

docs/testing/documentation.md

@@ -0,0 +1,39 @@
+# Documentation tests
+
+Deno supports type-checking your documentation examples.
+
+This makes sure that examples within your documentation are up to date and
+working.
+
+The basic idea is this:
+
+````ts
+/**
+ * # Examples
+ *
+ * ```ts
+ * const x = 42;
+ * ```
+ */
+````
+
+The triple backticks mark the start and end of code blocks.
+
+If this example was in a file named foo.ts, running `deno test --doc foo.ts`
+will extract this example, and then type-check it as a standalone module living
+in the same directory as the module being documented.
+
+To document your exports, import the module using a relative path specifier:
+
+````ts
+/**
+ * # Examples
+ *
+ * ```ts
+ * import { foo } from "./foo.ts";
+ * ```
+ */
+export function foo(): string {
+  return "foo";
+}
+````

docs/testing/sanitizers.md

@@ -0,0 +1,69 @@
+# Test Sanitizers
+
+The test runner offers several sanitizers to ensure that the test behaves in a
+reasonable and expected way.
+
+### Resource sanitizer
+
+Certain actions in Deno create resources in the resource table
+([learn more here](./contributing/architecture.md)).
+
+These resources should be closed after you are done using them.
+
+For each test definition, the test runner checks that all resources created in
+this test have been closed. This is to prevent resource 'leaks'. This is enabled
+by default for all tests, but can be disabled by setting the `sanitizeResources`
+boolean to false in the test definition.
+
+```ts
+Deno.test({
+  name: "leaky resource test",
+  async fn() {
+    await Deno.open("hello.txt");
+  },
+  sanitizeResources: false,
+});
+```
+
+### Op sanitizer
+
+The same is true for async operation like interacting with the filesystem. The
+test runner checks that each operation you start in the test is completed before
+the end of the test. This is enabled by default for all tests, but can be
+disabled by setting the `sanitizeOps` boolean to false in the test definition.
+
+```ts
+Deno.test({
+  name: "leaky operation test",
+  fn() {
+    setTimeout(function () {}, 1000);
+  },
+  sanitizeOps: false,
+});
+```
+
+### Exit sanitizer
+
+There's also the exit sanitizer which ensures that tested code doesn't call
+`Deno.exit()` signaling a false test success.
+
+This is enabled by default for all tests, but can be disabled by setting the
+`sanitizeExit` boolean to false in the test definition.
+
+```ts
+Deno.test({
+  name: "false success",
+  fn() {
+    Deno.exit(0);
+  },
+  sanitizeExit: false,
+});
+
+// This test never runs, because the process exits during "false success" test
+Deno.test({
+  name: "failing test",
+  fn() {
+    throw new Error("this test fails");
+  },
+});
+```

docs/toc.json

@@ -72,7 +72,10 @@
   "testing": {
     "name": "Testing",
     "children": {
-      "assertions": "Assertions"
+      "assertions": "Assertions",
+      "coverage": "Coverage",
+      "documentation": "Documentation",
+      "sanitizers": "Sanitizers"
     }
   },
   "tools": {