Skip to content

Commit 8ca5bdd

Browse files
committed
CONTRIBUTING.md: Improve asyncHelpers documentation
* Only mention `$DONE` after `asyncTest`. * Document that `asyncTest` is not intended to be called multiple times per file.
1 parent 5492929 commit 8ca5bdd

File tree

1 file changed

+4
-3
lines changed

1 file changed

+4
-3
lines changed

CONTRIBUTING.md

+4-3
Original file line numberDiff line numberDiff line change
@@ -209,8 +209,9 @@ This key is for boolean properties associated with the test.
209209
- **raw** - execute the test without any modification (no harness files will be
210210
included); necessary to test the behavior of directive prologue; implies
211211
`noStrict`
212-
- **async** - defer interpretation of test results until after the invocation
213-
of the global `$DONE` function
212+
- **async** - defer interpretation of test results until settlement of an
213+
`asyncTest` callback promise or manual invocation of `$DONE`; refer to
214+
[Writing Asynchronous Tests](#writing-asynchronous-tests) for details
214215
- **generated** - informative flag used to denote test files that were
215216
created procedurally using the project's test generation tool; refer to
216217
[Procedurally-generated tests](#procedurally-generated-tests)
@@ -346,7 +347,7 @@ Consumers that violate the spec by throwing exceptions for parsing errors at run
346347

347348
An asynchronous test is any test that include the `async` frontmatter flag.
348349

349-
For most asynchronous tests, the `asyncHelpers.js` harness file includes an `asyncTest` method that precludes needing to interact with the test runner via the `$DONE` function. `asyncTest` takes an async function and will ensure that `$DONE` is called properly if the async function returns or throws an exception. For example, a test written using `asyncTest` might look like:
350+
Most asynchronous tests should include the `asyncHelpers.js` harness file and call its `asyncTest` function **exactly once**, with a callback returning a promise that indicates test failure via rejection and otherwise fulfills upon test conclusion (such as an async function).
350351

351352
```js
352353
/*---

0 commit comments

Comments
 (0)