Add the last inline documentation.

README.md

@@ -22,6 +22,16 @@
   * [waitUntilDoesNotExist](#waituntildoesnotexist)
   * [find](#find)
   * [jQuery](#jquery)
+  * [setupAsync](#setupasync)
+  * [andThen](#andthen)
+  * [waitUntil](#waituntil)
+  * [waitMillis](#waitmillis)
+  * [waitUntilChange](#waituntilchange)
+  * [setupFakeFetchAsync](#setupfakefetchasync)
+  * [waitUntilFetchExists](#waituntilfetchexists)
+  * [setupFakeFetch](#setupfakefetch)
+  * [teardownFakeFetch](#teardownfakefetch)
+  * [fetchRespond](#fetchrespond)
   * [startFakingXhr](#startfakingxhr)
   * [stopFakingXhr](#stopfakingxhr)
   * [findXhr](#findxhr)
@@ -333,6 +343,119 @@ Returns **[jQuery](#jquery)** The jQuery object matching the selector within the
 
 Simply the jQuery constructor.
 
+### setupAsync
+
+Sets up the async test tools by adding the appropriate calls to `beforeEach` and `afterEach`.
+Call once in the top of a `describe` that you wish to use the async tools in.
+NOTE: When using [setupAndTeardownApp](#setupandteardownapp), it is not necessary to call this function separately.
+
+### andThen
+
+Triggers a callback after the previous asynchronous tool function resolves.
+
+**Parameters**
+
+-   `doThis` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** The callback function to call when the previous asynchronous tool function resolves. This
+    function will receive as argument the resolved result of that previous asynchronous tool function.
+
+**Examples**
+
+```javascript
+waitUntilExists('.some-element');
+andThen(someElementAsJqueryObject => {
+  // someElementAsJqueryObject is the result of matching '.some-element'.
+});
+```
+
+### waitUntil
+
+Waits until a callback returns any truthy value. It waits by polling the function repeatedly.
+
+**Parameters**
+
+-   `thisReturnsTruthy` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** The function to poll.
+-   `errorMessage` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function))** The string, or function returning a string, to be shown if this times out. (optional, default `` `acast-test-helpers#waitUntil() timed out since the following function never returned a truthy value within the timeout: ${thisReturnsTruthy}` ``)
+
+### waitMillis
+
+Waits a specific number of milliseconds.
+NOTE: Using this method is highly discouraged for anything other than temporary
+experiments. The reason is that it leads to either very long running or non-deterministic tests,
+none of which is desirable.
+
+**Parameters**
+
+-   `milliseconds` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** The number of milliseconds to wait.
+
+### waitUntilChange
+
+Waits until a function gives a different return value from one call to the next.
+
+**Parameters**
+
+-   `predicate` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** The function to be polled.
+-   `errorMessage` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function))** The string, or function returning a string, to be shown if this times out. (optional, default `` `acast-test-helpers#waitUntilChange() timed out since the return value of the following function never changed: ${predicate}` ``)
+
+**Examples**
+
+```javascript
+let foo = 'something';
+waitUntilChange(() => foo);
+andThen(theNewValueOfFoo => {
+  console.log(theNewValueOfFoo); // 'something else'
+});
+setTimeout(() => {
+  foo = 'something else';
+}, 1000);
+```
+
+### setupFakeFetchAsync
+
+Convenience method to set up everything needed to use fake fetch in an async environment.
+Calls [setupAsync](#setupasync), [setupFakeFetch](#setupfakefetch) and [teardownFakeFetch](#teardownfakefetch).
+
+Use this by calling it once on top of the appropriate `describe`.
+
+### waitUntilFetchExists
+
+Waits until a fetch call has been made, and resolves with the same return value as in [fetchRespond](#fetchrespond).
+
+**Parameters**
+
+-   `path` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The fetched path to wait for. Same as in [fetchRespond](#fetchrespond).
+
+### setupFakeFetch
+
+Replaces the global `window.fetch` function with a fake one to intercept any calls to fetch, and enable the
+tools in this module.
+Should be called before each test method that wants to fake fetch.
+
+### teardownFakeFetch
+
+Restores the original `window.fetch` method and tears down what was set up with [setupFakeFetch](#setupfakefetch).
+Should be called after each test method before which [setupFakeFetch](#setupfakefetch) was called.
+
+### fetchRespond
+
+Resolve to a previously intercepted fetch call.
+
+**Parameters**
+
+-   `path` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The path of the previous fetch call to respond to.
+
+**Examples**
+
+```javascript
+fetchRespond('/api/user/1337').resolveWith(200, {
+  id: 1337,
+  name: 'Fire'
+});
+```
+
+Returns **{resolveWith: (function (any?, any?)), rejectWith: (function (any?))}** An object with two methods:
+`resolveWith` and `rejectWith`. Most often you want to use `resolveWith`, since even HTTP errors such as 404 will
+result in a resolved fetch promise. `resolveWith` takes two arguments: the HTTP status, and the JSON return value.
+
 ### startFakingXhr
 
 Replaces the real XMLHttpRequest constructor with a fake one to intercept any subsequent XHR call.

documentation.yml

@@ -1,3 +1,2 @@
 toc:
   - setupAndTeardownApp
-  - scaleWindowWidth

src/async.js

@@ -2,6 +2,11 @@ let testPromise = null;
 
 const POLL_INTERVAL_MILLISECONDS = 100;
 
+/**
+ * Sets up the async test tools by adding the appropriate calls to `beforeEach` and `afterEach`.
+ * Call once in the top of a `describe` that you wish to use the async tools in.
+ * NOTE: When using {@link setupAndTeardownApp}, it is not necessary to call this function separately.
+ */
 export function setupAsync() {
   beforeEach('create test promise', () => {
     if (testPromise) {
@@ -52,6 +57,17 @@ function getErrorMessage() {
   return testPromise.errorMessage;
 }
 
+/**
+ * Triggers a callback after the previous asynchronous tool function resolves.
+ * @param {function} doThis The callback function to call when the previous asynchronous tool function resolves. This
+ * function will receive as argument the resolved result of that previous asynchronous tool function.
+ * @example
+ * waitUntilExists('.some-element');
+ * andThen(someElementAsJqueryObject => {
+ *   // someElementAsJqueryObject is the result of matching '.some-element'.
+ * });
+ *
+ */
 export function andThen(doThis) {
   if (!testPromise) {
     throw new Error(
@@ -79,6 +95,11 @@ function resolveWhenPredicateReturnsTruthy(predicate, resolve, chainedValue) {
   }
 }
 
+/**
+ * Waits until a callback returns any truthy value. It waits by polling the function repeatedly.
+ * @param {function} thisReturnsTruthy The function to poll.
+ * @param {string|function} errorMessage The string, or function returning a string, to be shown if this times out.
+ */
 export function waitUntil(
   thisReturnsTruthy,
   errorMessage = `acast-test-helpers#waitUntil() timed out since the following function never returned a truthy value within the timeout: ${thisReturnsTruthy}`
@@ -96,6 +117,13 @@ export function waitUntil(
   );
 }
 
+/**
+ * Waits a specific number of milliseconds.
+ * NOTE: Using this method is highly discouraged for anything other than temporary
+ * experiments. The reason is that it leads to either very long running or non-deterministic tests,
+ * none of which is desirable.
+ * @param {number} milliseconds The number of milliseconds to wait.
+ */
 export function waitMillis(milliseconds) {
   andThen(
     () =>
@@ -106,6 +134,20 @@ export function waitMillis(milliseconds) {
   );
 }
 
+/**
+ * Waits until a function gives a different return value from one call to the next.
+ * @param {function} predicate The function to be polled.
+ * @param {string|function} errorMessage The string, or function returning a string, to be shown if this times out.
+ * @example
+ * let foo = 'something';
+ * waitUntilChange(() => foo);
+ * andThen(theNewValueOfFoo => {
+ *   console.log(theNewValueOfFoo); // 'something else'
+ * });
+ * setTimeout(() => {
+ *   foo = 'something else';
+ * }, 1000);
+ */
 export function waitUntilChange(
   predicate,
   errorMessage = `acast-test-helpers#waitUntilChange() timed out since the return value of the following function never changed: ${predicate}`

src/fetch-async.js

@@ -1,13 +1,24 @@
 import { setupAsync, waitUntil } from './async';
 import { setupFakeFetch, teardownFakeFetch, fetchRespond } from './fetch';
 
+/**
+ * Convenience method to set up everything needed to use fake fetch in an async environment.
+ * Calls {@link setupAsync}, {@link setupFakeFetch} and {@link teardownFakeFetch}.
+ *
+ * Use this by calling it once on top of the appropriate `describe`.
+ */
 export function setupFakeFetchAsync() {
   setupAsync();
 
   beforeEach(setupFakeFetch);
   afterEach(teardownFakeFetch);
 }
 
+
+/**
+ * Waits until a fetch call has been made, and resolves with the same return value as in {@link fetchRespond}.
+ * @param {string} path The fetched path to wait for. Same as in {@link fetchRespond}.
+ */
 export function waitUntilFetchExists(path) {
   waitUntil(() => fetchRespond(path));
 }

src/fetch.js

@@ -60,18 +60,39 @@ function throwIfPathIsNotAwaitingResolution(path) {
 
 window.fetch = window.fetch; // For some unexplainable reason, PhantomJS doesn't pass the tests without this.
 
+/**
+ * Replaces the global `window.fetch` function with a fake one to intercept any calls to fetch, and enable the
+ * tools in this module.
+ * Should be called before each test method that wants to fake fetch.
+ */
 export function setupFakeFetch() {
   pathToPromisesMap = {};
   originalFetch = window.fetch;
 
   window.fetch = createFakeFetch();
 }
 
+/**
+ * Restores the original `window.fetch` method and tears down what was set up with {@link setupFakeFetch}.
+ * Should be called after each test method before which {@link setupFakeFetch} was called.
+ */
 export function teardownFakeFetch() {
   window.fetch = originalFetch;
   pathToPromisesMap = null;
 }
 
+/**
+ * Resolve to a previously intercepted fetch call.
+ * @param {string} path The path of the previous fetch call to respond to.
+ * @returns {{resolveWith: (function(*=, *=)), rejectWith: (function(*=))}} An object with two methods:
+ * `resolveWith` and `rejectWith`. Most often you want to use `resolveWith`, since even HTTP errors such as 404 will
+ * result in a resolved fetch promise. `resolveWith` takes two arguments: the HTTP status, and the JSON return value.
+ * @example
+ * fetchRespond('/api/user/1337').resolveWith(200, {
+ *   id: 1337,
+ *   name: 'Fire'
+ * });
+ */
 export function fetchRespond(path) {
   throwIfNotSetUp();
   throwIfPathIsNotAwaitingResolution(path);