1 files changed, 81 insertions, 10 deletions
diff --git a/testing/README.md b/testing/README.md
index 70968e3c7..49a6526fe 100644
--- a/testing/README.md
+++ b/testing/README.md
@@ -1,14 +1,41 @@
 # Testing
 
+This module provides a few basic utilities to make testing easier and
+consistent in Deno.
+
 ## Usage
 
+The module exports a `test` function which is the test harness in Deno. It
+accepts either a function (including async functions) or an object which
+contains a `name` property and a `fn` property. When running tests and
+outputting the results, the name of the past function is used, or if the
+object is passed, the `name` property is used to identify the test.
+
+The module also exports `assert`, `assertEqual`, and `equal`.
+
+`equal` is a deep comparision function, where `actual` and `expected` are
+compared deeply, and if they vary, `equal` returns `false`.
+
+The export `assert` is a function, but it is also decorated with other useful
+functions:
+
+- `assert()` - Expects a boolean value, throws if the value is `false`.
+- `assert.equal()` - Uses the `equal` comparison and throws if the `actual` and
+  `expected` are not equal.
+- `assert.strictEqual()` - Compares `actual` and `expected` strictly, therefore
+  for non-primitives the values must reference the same instance.
+- `assert.throws()` - Expects the passed `fn` to throw. If `fn` does not throw,
+  this function does. Also compares any errors thrown to an optional expected
+  `Error` class and checks that the error `.message` includes an optional
+  string.
+
+`assertEqual()` is the same as `assert.equal()` but maintained for backwards
+compatibility.
+
+Basic usage:
+
 ```ts
-import {
-  test,
-  assert,
-  equal,
-  assertEqual
-} from "https://deno.land/x/testing/mod.ts";
+import { test, assert, equal } from "https://deno.land/x/testing/mod.ts";
 
 test({
   name: "testing example",
@@ -17,8 +44,8 @@ test({
     assert(!equal("hello", "world"));
     assert(equal({ hello: "world" }, { hello: "world" }));
     assert(!equal({ world: "hello" }, { hello: "world" }));
-    assertEqual("world", "world");
-    assertEqual({ hello: "world" }, { hello: "world" });
+    assert.equal("world", "world");
+    assert.equal({ hello: "world" }, { hello: "world" });
   }
 });
 ```
@@ -31,7 +58,51 @@ test(function example() {
   assert(!equal("hello", "world"));
   assert(equal({ hello: "world" }, { hello: "world" }));
   assert(!equal({ world: "hello" }, { hello: "world" }));
-  assertEqual("world", "world");
-  assertEqual({ hello: "world" }, { hello: "world" });
+  assert.equal("world", "world");
+  assert.equal({ hello: "world" }, { hello: "world" });
+});
+```
+
+Using `assert.strictEqual()`:
+
+```ts
+test(function isStrictlyEqual() {
+  const a = {};
+  const b = a;
+  assert.strictEqual(a, b);
+});
+
+// This test fails
+test(function isNotStrictlyEqual() {
+  const a = {};
+  const b = {};
+  assert.strictEqual(a, b);
+});
+```
+
+Using `assert.throws()`:
+
+```ts
+test(function doesThrow() {
+  assert.throws(() => {
+    throw new TypeError("hello world!");
+  });
+  assert.throws(() => {
+    throw new TypeError("hello world!");
+  }, TypeError);
+  assert.throws(
+    () => {
+      throw new TypeError("hello world!");
+    },
+    TypeError,
+    "hello"
+  );
+});
+
+// This test will not pass
+test(function fails() {
+  assert.throws(() => {
+    console.log("Hello world");
+  });
 });
 ```