From 94220babb105950dfc2d09d67b4731bf026449b5 Mon Sep 17 00:00:00 2001
From: Carl Gross <cagross@everlooksolutions.com>
Date: Tue, 26 Jan 2021 19:43:37 +0700
Subject: [PATCH] [readme] improve `t.throws` documentation

* Added usage example for when expected parameter is a validation object.

See #540.
---
 readme.markdown | 41 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/readme.markdown b/readme.markdown
index fe786e62..979d3a67 100644
--- a/readme.markdown
+++ b/readme.markdown
@@ -286,7 +286,46 @@ Aliases: `t.notLooseEqual()`, `t.notLooseEquals()`
 
 ## t.throws(fn, expected, msg)
 
-Assert that the function call `fn()` throws an exception. `expected`, if present, must be a `RegExp`, `Function`, or `Object`. The `RegExp` matches the string representation of the exception, as generated by `err.toString()`. For example, if you set `expected` to `/user/`, the test will pass only if the string representation of the exception contains the word `user`. Any other exception will result in a failed test. The `Function` is the exception thrown (e.g. `Error`). `Object` in this case corresponds to a so-called validation object, in which each property is tested for strict deep equality. This is very similar to how Node's `assert.throws()` method tests validation objects (please see the [Node _assert.throws()_ documentation](https://nodejs.org/api/assert.html#assert_assert_throws_fn_error_message) for an example). If `expected` is not of type `RegExp`, `Function`, or `Object`, or omitted entirely, any exception will result in a passed test. `msg` is an optional description of the assertion.
+Assert that the function call `fn()` throws an exception. `expected`, if present, must be a `RegExp`, `Function`, or `Object`. The `RegExp` matches the string representation of the exception, as generated by `err.toString()`. For example, if you set `expected` to `/user/`, the test will pass only if the string representation of the exception contains the word `user`. Any other exception will result in a failed test. The `Function` is the exception thrown (e.g. `Error`). `Object` in this case corresponds to a so-called validation object, in which each property is tested for strict deep equality. As an example, see the following two tests--each passes a validation object to `t.throws()` as the second parameter. The first test will pass, because all property values in the actual error object are deeply strictly equal to the property values in the validation object.
+```
+    const err = new TypeError("Wrong value");
+    err.code = 404;
+    err.check = true;
+
+    // Passing test.
+    t.throws(
+        () => {
+            throw err;
+        },
+        {
+            code: 404,
+            check: true
+        },
+        "Test message."
+    );
+```
+This next test will fail, because all property values in the actual error object are _not_ deeply strictly equal to the property values in the validation object.
+```
+    const err = new TypeError("Wrong value");
+    err.code = 404;
+    err.check = "true";
+
+    // Failing test.
+    t.throws(
+        () => {
+            throw err;
+        },
+        {
+            code: 404,
+            check: true // This is not deeply strictly equal to err.check.
+        },
+        "Test message."
+    );
+```
+
+This is very similar to how Node's `assert.throws()` method tests validation objects (please see the [Node _assert.throws()_ documentation](https://nodejs.org/api/assert.html#assert_assert_throws_fn_error_message) for more information).
+
+If `expected` is not of type `RegExp`, `Function`, or `Object`, or omitted entirely, any exception will result in a passed test. `msg` is an optional description of the assertion.
 
 Please note that the second parameter, `expected`, cannot be of type `string`. If a value of type `string` is provided for `expected`, then `t.throws(fn, expected, msg)`  will execute, but the value of `expected` will be set to  `undefined`, and the specified string will be set as the value for the `msg` parameter (regardless of what _actually_ passed as the third parameter). This can cause unexpected results, so please be mindful.