From 957fa25d33fa0c1abf78787a9acfeb0293529aef Mon Sep 17 00:00:00 2001
From: Nohea <raulg@nohea.com>
Date: Sun, 19 Dec 2021 08:04:53 -1000
Subject: [PATCH] chore(docs): add `assert.throws` example for asyncs (#172)

* Update api.assert.md

Adding a reference on the idiom of how to assert an async function throws an error:
https://github.com/lukeed/uvu/issues/35#issuecomment-896270152

* Apply suggestions from code review

* Update docs/api.assert.md

Co-authored-by: Luke Edwards <luke.edwards05@gmail.com>
---
 docs/api.assert.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/docs/api.assert.md b/docs/api.assert.md
index c7c83ae..ec06d1f 100644
--- a/docs/api.assert.md
+++ b/docs/api.assert.md
@@ -131,6 +131,19 @@ assert.throws(() => OOPS(), /Cannot read property/);
 assert.throws(() => OOPS(), err => err instanceof TypeError);
 ```
 
+If you are trying to assert that an `async` function throws an Error, the following approach [is recommended](https://github.com/lukeed/uvu/issues/35#issuecomment-896270152):
+
+```js
+try {
+  await asyncFnThatThrows();
+  assert.unreachable('should have thrown');
+} catch (err) {
+  assert.instance(err, Error);
+  assert.match(err.message, 'something specific');
+  assert.is(err.code, 'ERROR123');
+}
+```
+
 ### unreachable(msg?: Message)
 Assert that a line should never be reached.