diff --git a/assets/mocha-fixture-wizard.sketch b/assets/mocha-fixture-wizard.sketch new file mode 100644 index 0000000000..6f3ab95757 Binary files /dev/null and b/assets/mocha-fixture-wizard.sketch differ diff --git a/docs/_data/supporters.js b/docs/_data/supporters.js index 19f1fbb37a..e227d423a9 100755 --- a/docs/_data/supporters.js +++ b/docs/_data/supporters.js @@ -99,32 +99,40 @@ const nodeToSupporter = node => ({ categories: node.fromAccount.categories }); -const fetchImage = async supporter => { - try { - const {avatar: url} = supporter; - const {body: imageBuf, headers} = await needle('get', url, {timeout: 2000}); - if (headers['content-type'].startsWith('text/html')) { - throw new TypeError('received html and expected a png; outage likely'); +const fetchImage = process.env.MOCHA_DOCS_SKIP_IMAGE_DOWNLOAD + ? async supporter => { + invalidSupporters.push(supporter); } - debug('fetched %s', url); - const canvasImage = await loadImage(imageBuf); - debug('ok %s', url); - supporter.dimensions = { - width: canvasImage.width, - height: canvasImage.height + : async supporter => { + try { + const {avatar: url} = supporter; + const {body: imageBuf, headers} = await needle('get', url, { + timeout: 2000 + }); + if (headers['content-type'].startsWith('text/html')) { + throw new TypeError( + 'received html and expected a png; outage likely' + ); + } + debug('fetched %s', url); + const canvasImage = await loadImage(imageBuf); + debug('ok %s', url); + supporter.dimensions = { + width: canvasImage.width, + height: canvasImage.height + }; + // debug('dimensions %s %dw %dh', url, canvasImage.width, canvasImage.height); + const filePath = resolve(SUPPORTER_IMAGE_PATH, supporter.id + '.png'); + await writeFile(filePath, imageBuf); + debug('wrote %s', filePath); + } catch (err) { + console.error( + `failed to load ${supporter.avatar}; will discard ${supporter.tier} "${supporter.name} (${supporter.slug}). reason:\n`, + err + ); + invalidSupporters.push(supporter); + } }; - // debug('dimensions %s %dw %dh', url, canvasImage.width, canvasImage.height); - const filePath = resolve(SUPPORTER_IMAGE_PATH, supporter.id + '.png'); - await writeFile(filePath, imageBuf); - debug('wrote %s', filePath); - } catch (err) { - console.error( - `failed to load ${supporter.avatar}; will discard ${supporter.tier} "${supporter.name} (${supporter.slug}). reason:\n`, - err - ); - invalidSupporters.push(supporter); - } -}; /** * Retrieves donation data from OC diff --git a/docs/_includes/fixture-wizard.html b/docs/_includes/fixture-wizard.html new file mode 100644 index 0000000000..97a38f5f45 --- /dev/null +++ b/docs/_includes/fixture-wizard.html @@ -0,0 +1,436 @@ +
+ + Mocha Fixture Wizard + + + + + My tests + need setup! + + + + Setup MUST run + once and only once + + + + + + Setup MUST share + state with tests + + + + + + YES + + + + + + + + Use Root Hooks and + Avoid Parallel Mode + + + + + + + + + + + + Use Global Fixtures + + + + + + Should setup affect + tests across ALL files? + + + + + + + + Use Root Hooks + + + + + + + + Use Plain Hooks + + + + + + + + YES + + + + + + NO + + + + + + NO + + + + + + + + + YES + + + + + + NO + + + + + +
diff --git a/docs/css/style.css b/docs/css/style.css index 3104b4f876..c3e3ce6b8f 100644 --- a/docs/css/style.css +++ b/docs/css/style.css @@ -394,3 +394,7 @@ figure#wallaby-logo figcaption { display: block; } } + +#mocha-fixture-wizard text[font-weight=bold]:hover { + text-decoration: underline; +} diff --git a/docs/index.md b/docs/index.md index ebe5f86ed1..d5024bca9c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1268,7 +1268,11 @@ When Mocha runs in parallel mode, **test files do not share the same process,** Here are a couple suggested workarounds: 1. `require('./setup.js')` or `import './setup.js'` at the top of every test file. Best avoided for those averse to boilerplate. -1. _Recommended_: Define root hooks in a "required" file, using the new (also as of v8.0.0) [Root Hook Plugin](#root-hook-plugins) system. +1. _Recommended_: Define root hooks in a "required" file, using the new (also as + of v8.0.0) [Root Hook Plugin](#root-hook-plugins) system. + +If you need to run some code _once and only once_, use a [global +fixture](#global-fixtures) instead. ### No Browser Support @@ -1364,6 +1368,8 @@ Available root hooks and their behavior: {:.single-column} +> _Tip: If you need to ensure code runs once and only once in any mode, use [global fixtures](#global-fixtures)._ + As with other hooks, `this` refers to to the current context object: ```js @@ -1653,6 +1659,13 @@ describe('my API', function() { Finally, use this command to bring it together: `mocha --require fixtures.mjs test.spec.mjs`. +## Test Fixture Decision-Tree Wizard Thing + +This flowchart will help you decide which of [hooks], [root hook plugins] or +[global fixtures] you should use. + +{% include fixture-wizard.html %} + ## Interfaces Mocha's "interface" system allows developers to choose their style of DSL. Mocha has **BDD**, **TDD**, **Exports**, **QUnit** and **Require**-style interfaces. @@ -2391,3 +2404,4 @@ or the [source](https://github.com/mochajs/mocha/blob/master/lib/mocha.js). [global setup fixtures]: #global-setup-fixtures [global teardown fixtures]: #global-teardown-fixtures [global fixtures]: #global-fixtures +[hooks]: #hooks