From c84b218d7af4562c02082eb4ea2682e3155f37ac Mon Sep 17 00:00:00 2001 From: Mikael Brandt Date: Fri, 9 Jun 2017 10:39:11 +0200 Subject: [PATCH] Add the last inline documentation. --- README.md | 123 +++++++++++++++++++++++++++++++++++++++++++++ documentation.yml | 1 - src/async.js | 42 ++++++++++++++++ src/fetch-async.js | 11 ++++ src/fetch.js | 21 ++++++++ 5 files changed, 197 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a2113d4..6433e81 100644 --- a/README.md +++ b/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. diff --git a/documentation.yml b/documentation.yml index ece9d7c..879d9a5 100644 --- a/documentation.yml +++ b/documentation.yml @@ -1,3 +1,2 @@ toc: - setupAndTeardownApp - - scaleWindowWidth diff --git a/src/async.js b/src/async.js index f76eaca..5aed040 100644 --- a/src/async.js +++ b/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}` diff --git a/src/fetch-async.js b/src/fetch-async.js index 1f9dd20..467aa3d 100644 --- a/src/fetch-async.js +++ b/src/fetch-async.js @@ -1,6 +1,12 @@ 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(); @@ -8,6 +14,11 @@ export function setupFakeFetchAsync() { 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)); } diff --git a/src/fetch.js b/src/fetch.js index cb71347..03ca7a3 100644 --- a/src/fetch.js +++ b/src/fetch.js @@ -60,6 +60,11 @@ 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; @@ -67,11 +72,27 @@ export function setupFakeFetch() { 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);