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

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

3 files changed, 144 insertions, 0 deletions

diff --git a/docs/testing/coverage.md b/docs/testing/coverage.md
new file mode 100644
index 000000000..0899c7cbd
--- /dev/null
+++ b/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.
diff --git a/docs/testing/documentation.md b/docs/testing/documentation.md
new file mode 100644
index 000000000..f0a2061db
--- /dev/null
+++ b/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";
+}
+````
diff --git a/docs/testing/sanitizers.md b/docs/testing/sanitizers.md
new file mode 100644
index 000000000..c078e5234
--- /dev/null
+++ b/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");
+  },
+});
+```