Docs for deno test + minor other changes (#5185)

* Added fs events example.
* Added docs for `deno test`.
* Renamed file server example.
* Unified markdown code types.
* Removed plugin topics from TOC.
* Fixed links.

17 files changed, 153 insertions, 42 deletions

diff --git a/docs/contributing.md b/docs/contributing.md
index df2d1de24..f83756e9b 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -1,6 +1,6 @@
 # Contributing
 
-- Read the [style guide](contributing/style_guide.md).
+- Read the [style guide](./contributing/style_guide.md).
 
 - Please don't make [the benchmarks](https://deno.land/benchmarks.html) worse.
 
diff --git a/docs/contributing/building_from_source.md b/docs/contributing/building_from_source.md
index 62bbf2303..381ad7b03 100644
--- a/docs/contributing/building_from_source.md
+++ b/docs/contributing/building_from_source.md
@@ -8,7 +8,7 @@ Deno you can download a prebuilt executable (more information in the
 
 Clone on Linux or Mac:
 
-```bash
+```shell
 git clone --recurse-submodules https://github.com/denoland/deno.git
 ```
 
@@ -18,7 +18,7 @@ Extra steps for Windows users:
    (otherwise symlinks would require administrator privileges).
 2. Make sure you are using git version 2.19.2.windows.1 or newer.
 3. Set `core.symlinks=true` before the checkout:
-   ```bash
+   ```shell
    git config --global core.symlinks true
    git clone --recurse-submodules https://github.com/denoland/deno.git
    ```
@@ -77,7 +77,7 @@ about the V8 build.
 
 Build with Cargo:
 
-```bash
+```shell
 # Build:
 cargo build -vv
 
diff --git a/docs/contributing/development_tools.md b/docs/contributing/development_tools.md
index 35bd5a5fb..b8aa9505f 100644
--- a/docs/contributing/development_tools.md
+++ b/docs/contributing/development_tools.md
@@ -4,7 +4,7 @@
 
 Test `deno`:
 
-```bash
+```shell
 # Run the whole suite:
 cargo test
 
@@ -14,7 +14,7 @@ cargo test js_unit_tests
 
 Test `std/`:
 
-```bash
+```shell
 cargo test std_tests
 ```
 
@@ -22,13 +22,13 @@ cargo test std_tests
 
 Lint the code:
 
-```bash
+```shell
 ./tools/lint.py
 ```
 
 Format the code:
 
-```bash
+```shell
 ./tools/format.py
 ```
 
diff --git a/docs/examples/fileserver.md b/docs/examples/file_server.md
index 3ed9d90e7..9fbe27bd3 100644
--- a/docs/examples/fileserver.md
+++ b/docs/examples/file_server.md
@@ -2,7 +2,7 @@
 
 This one serves a local directory in HTTP.
 
-```bash
+```shell
 deno install --allow-net --allow-read https://deno.land/std/http/file_server.ts
 ```
 
diff --git a/docs/examples/file_system_events.md b/docs/examples/file_system_events.md
new file mode 100644
index 000000000..2abebc33e
--- /dev/null
+++ b/docs/examples/file_system_events.md
@@ -0,0 +1,18 @@
+### File system events
+
+To poll for file system events:
+
+```ts
+const watcher = Deno.watchFs("/");
+for await (const event of watcher) {
+  console.log(">>>> event", event);
+  // { kind: "create", paths: [ "/foo.txt" ] }
+}
+```
+
+Note that the exact ordering of the events can vary between operating systems.
+This feature uses different syscalls depending on the platform:
+
+- Linux: inotify
+- macOS: FSEvents
+- Windows: ReadDirectoryChangesW
diff --git a/docs/examples/tcp_echo.md b/docs/examples/tcp_echo.md
index d7c2e9e72..360c5facc 100644
--- a/docs/examples/tcp_echo.md
+++ b/docs/examples/tcp_echo.md
@@ -25,7 +25,7 @@ For security reasons, Deno does not allow programs to access the network without
 explicit permission. To allow accessing the network, use a command-line flag:
 
 ```shell
-$ deno run --allow-net https://deno.land/std/examples/echo_server.ts
+deno run --allow-net https://deno.land/std/examples/echo_server.ts
 ```
 
 To test it, try sending data to it with netcat:
diff --git a/docs/examples/unix_cat.md b/docs/examples/unix_cat.md
index 7534ef0d0..ca85ea325 100644
--- a/docs/examples/unix_cat.md
+++ b/docs/examples/unix_cat.md
@@ -20,5 +20,5 @@ I/O streams in Deno.
 Try the program:
 
 ```shell
-$ deno run --allow-read https://deno.land/std/examples/cat.ts /etc/passwd
+deno run --allow-read https://deno.land/std/examples/cat.ts /etc/passwd
 ```
diff --git a/docs/getting_started/first_steps.md b/docs/getting_started/first_steps.md
index 74dbae1b4..8c9e4ea0a 100644
--- a/docs/getting_started/first_steps.md
+++ b/docs/getting_started/first_steps.md
@@ -17,13 +17,13 @@ and use modern features wherever possible.
 Because of this browser compatibility a simple `Hello World` program is actually
 no different to one you can run in the browser:
 
-```typescript
+```ts
 console.log("Welcome to Deno 🦕");
 ```
 
 Try the program:
 
-```bash
+```shell
 deno run https://deno.land/std/examples/welcome.ts
 ```
 
@@ -37,7 +37,7 @@ Just like in the browser you can use the web standard
 [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) API to
 make HTTP calls:
 
-```typescript
+```ts
 const url = Deno.args[0];
 const res = await fetch(url);
 
@@ -60,7 +60,7 @@ Lets walk through what this application does:
 
 Try it out:
 
-```bash
+```shell
 deno run https://deno.land/std/examples/curl.ts https://example.com
 ```
 
@@ -71,7 +71,7 @@ programs the permission to do certain 'privileged' actions like network access.
 
 Try it out again with the correct permission flag:
 
-```bash
+```shell
 deno run --allow-net=example.com https://deno.land/std/examples/curl.ts https://example.com
 ```
 
@@ -103,7 +103,7 @@ I/O streams in Deno.
 
 Try the program:
 
-```bash
+```shell
 deno run --allow-read https://deno.land/std/examples/cat.ts /etc/passwd
 ```
 
diff --git a/docs/getting_started/typescript.md b/docs/getting_started/typescript.md
index ebe1e5e70..35a513b37 100644
--- a/docs/getting_started/typescript.md
+++ b/docs/getting_started/typescript.md
@@ -100,7 +100,7 @@ be provided to Deno on program execution.
 You need to explicitly tell Deno where to look for this configuration by setting
 the `-c` argument when executing your application.
 
-```bash
+```shell
 deno run -c tsconfig.json mod.ts
 ```
 
diff --git a/docs/linking_to_external_code.md b/docs/linking_to_external_code.md
index 5484a7806..e03bfdfee 100644
--- a/docs/linking_to_external_code.md
+++ b/docs/linking_to_external_code.md
@@ -1,6 +1,6 @@
 # Linking to third party code
 
-In the [Getting Started](../getting_started) section, we saw that Deno could
+In the [Getting Started](./getting_started.md) section, we saw that Deno could
 execute scripts from URLs. Like browser JavaScript, Deno can import libraries
 directly from URLs. This example uses a URL to import an assertion library:
 
@@ -52,7 +52,7 @@ specifying that path as the `$DENO_DIR` environmental variable at runtime.
 
 By using a lock file (using the `--lock` command line flag) you can ensure
 you're running the code you expect to be. You can learn more about this
-[here](./integrity_checking).
+[here](./linking_to_external_code/integrity_checking.md).
 
 ### How do you import to a specific version?
 
diff --git a/docs/runtime/program_lifecycle.md b/docs/runtime/program_lifecycle.md
index dda8a06f9..c7c3c46a3 100644
--- a/docs/runtime/program_lifecycle.md
+++ b/docs/runtime/program_lifecycle.md
@@ -8,7 +8,7 @@ Listener for `load` events can be asynchronous and will be awaited. Listener for
 
 Example:
 
-```typescript
+```ts
 // main.ts
 import "./imported.ts";
 
diff --git a/docs/runtime/stability.md b/docs/runtime/stability.md
index a158638b9..cd7c27039 100644
--- a/docs/runtime/stability.md
+++ b/docs/runtime/stability.md
@@ -10,7 +10,7 @@ are not ready because they are still in draft phase are locked behind the
 - It enables the use of unstable APIs during runtime.
 - It adds the
   [`lib.deno.unstable.d.ts`](https://github.com/denoland/deno/blob/master/cli/js/lib.deno.unstable.d.ts)
-  file to the list of TypeScript definitions that are used for typechecking.
+  file to the list of TypeScript definitions that are used for type checking.
   This includes the output of `deno types`.
 
 You should be aware that unstable APIs have probably **not undergone a security
diff --git a/docs/runtime/workers.md b/docs/runtime/workers.md
index 0418f057e..3c39d2cee 100644
--- a/docs/runtime/workers.md
+++ b/docs/runtime/workers.md
@@ -20,7 +20,8 @@ new Worker("./worker.js", { type: "classic" });
 
 ### Using Deno in worker
 
-**UNSTABLE**: This feature is unstable and requires `--unstable` flag
+> This is an unstable Deno feature. Learn more about
+> [unstable features](./stability.md).
 
 By default `Deno` namespace is not available in worker scope.
 
diff --git a/docs/testing.md b/docs/testing.md
new file mode 100644
index 000000000..d6f59e3ec
--- /dev/null
+++ b/docs/testing.md
@@ -0,0 +1,105 @@
+# Testing
+
+Deno has a built-in test runner that you can use for testing JavaScript or
+TypeScript code.
+
+## Writing tests
+
+To define a test you need to call `Deno.test` with a name and function to be
+tested:
+
+```ts
+Deno.test("hello world", () => {
+  const x = 1 + 2;
+  if (x !== 3) {
+    throw Error("x should be equal to 3");
+  }
+});
+```
+
+There are some useful assertion utilities at https://deno.land/std/testing to
+make testing easier:
+
+```ts
+import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
+
+Deno.test("hello world", () => {
+  const x = 1 + 2;
+  assertEquals(x, 3);
+});
+```
+
+### Async functions
+
+You can also test asynchronous code by passing a test function that returns a
+promise. For this you can use the `async` keyword when defining a function:
+
+```ts
+Deno.test("async hello world", async () => {
+  const x = 1 + 2;
+
+  // await some async task
+  await delay(100);
+
+  if (x !== 3) {
+    throw Error("x should be equal to 3");
+  }
+});
+```
+
+### 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,
+});
+```
+
+### Ignoring tests
+
+Sometimes you want to ignore tests based on some sort of condition (for example
+you only want a test to run on Windows). For this you can use the `ignore`
+boolean in the test definition. If it is set to true the test will be skipped.
+
+```ts
+Deno.test({
+  name: "do macOS feature",
+  ignore: Deno.build.os !== "darwin",
+  fn() {
+    doMacOSFeature();
+  },
+});
+```
+
+## Running tests
+
+To run the test, call `deno test` with the file that contains your test
+function:
+
+```shell
+deno test my_test.ts
+```
+
+You can also omit the file name, in which case all tests in the current
+directory (recursively) that match the glob `{*_,}test.{js,ts,jsx,tsx}` will be
+run. If you pass a directory, all files in the directory that match this glob
+will be run.
diff --git a/docs/toc.json b/docs/toc.json
index 061ba66f6..5369a0065 100644
--- a/docs/toc.json
+++ b/docs/toc.json
@@ -17,7 +17,7 @@
     "name": "The Runtime",
     "children": {
       "stability": "Stability",
-      "program_lifecycle": "Program Lifecycle",
+      "program_lifecycle": "Program lifecycle",
       "compiler_apis": "Compiler APIs",
       "workers": "Workers"
     }
@@ -32,19 +32,7 @@
     }
   },
   "testing": {
-    "name": "Testing",
-    "children": {
-      "writing": "Writing tests",
-      "running": "Running tests"
-    }
-  },
-  "plugins": {
-    "name": "Plugins",
-    "children": {
-      "how_do_plugins_work": "How do plugins work?",
-      "creating_plugins": "Creating plugins",
-      "using_plugins": "Using plugins"
-    }
+    "name": "Testing"
   },
   "tools": {
     "name": "Tools",
@@ -73,7 +61,7 @@
     "name": "Examples",
     "children": {
       "unix_cat": "Unix cat program",
-      "fileserver": "File server",
+      "file_server": "File server",
       "tcp_echo": "TCP echo server",
       "subprocess": "Creating a subprocess",
       "permissions": "Inspecting and revoking permissions",
diff --git a/docs/tools.md b/docs/tools.md
index f3dae49e8..904bf027f 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -6,7 +6,7 @@ and TypeScript:
 <!-- prettier-ignore-start -->
 <!-- prettier incorrectly moves the coming soon links to new lines -->
 
-- [test runner (`deno test`)](../testing)
+- [test runner (`deno test`)](./testing.md)
 - [code formatter (`deno fmt`)](./tools/formatter.md)
 - [bundler (`deno bundle`)](./tools/bundler.md)
 - [debugger (`--debug`)](./tools/debugger.md)
diff --git a/docs/tools/script_installer.md b/docs/tools/script_installer.md
index ffd920cf3..6badd6436 100644
--- a/docs/tools/script_installer.md
+++ b/docs/tools/script_installer.md
@@ -61,9 +61,8 @@ $ deno install --allow-net --allow-read https://deno.land/std/http/file_server.t
 The above command creates an executable called `file_server` that runs with
 write and read permissions and binds to port 8080.
 
-For good practice, use the
-[`import.meta.main`](#testing-if-current-file-is-the-main-program) idiom to
-specify the entry point in an executable script.
+For good practice, use the [`import.meta.main`](../examples/testing_if_main.md)
+idiom to specify the entry point in an executable script.
 
 Example: