☕️ Classic, reliable, trusted test framework for Node.js and the browser
add "fixture flowchart" to docs (#4440)
Christopher Hiller478ca6ac3d05
diff --git a/assets/mocha-fixture-wizard.sketch b/assets/mocha-fixture-wizard.sketchnew file mode 100644index 00000000..6f3ab957Binary files /dev/null and b/assets/mocha-fixture-wizard.sketch differdiff --git a/docs/_data/supporters.js b/docs/_data/supporters.jsindex 19f1fbb3..e227d423 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 OCdiff --git a/docs/_includes/fixture-wizard.html b/docs/_includes/fixture-wizard.htmlnew file mode 100644index 00000000..97a38f5f--- /dev/null+++ b/docs/_includes/fixture-wizard.html@@ -0,0 +1,436 @@+<div>+ <svg+ width="100%"+ height="100%"+ viewBox="0 0 854 665"+ version="1.1"+ id="mocha-fixture-wizard"+ >+ <title>Mocha Fixture Wizard</title>+ <g+ id="Page-1"+ stroke="none"+ stroke-width="1"+ fill="none"+ fill-rule="evenodd"+ >+ <g+ id="mocha-fixture-wizard-diagram"+ transform="translate(2.000000, 3.000000)"+ >+ <rect+ id="Rectangle"+ stroke="#8D6748"+ stroke-width="5"+ fill="#FFFFFF"+ fill-rule="nonzero"+ x="360"+ y="0"+ width="120"+ height="60"+ rx="9"+ ></rect>+ <text+ id="My-tests-need-setup!"+ fill="#000000"+ fill-rule="nonzero"+ font-family="HelveticaNeue, Helvetica Neue"+ font-size="16"+ font-weight="normal"+ >+ <tspan x="388.972" y="27">My tests</tspan>+ <tspan x="377.412" y="45">need setup!</tspan>+ </text>+ <polygon+ id="Path"+ stroke="#CCCCCC"+ stroke-width="4"+ transform="translate(420.000000, 200.000000) rotate(-90.000000) translate(-420.000000, -200.000000) "+ points="420 100 520 200 420 300 320 200"+ ></polygon>+ <text+ id="Setup-MUST-run-once"+ fill="#000000"+ fill-rule="nonzero"+ font-family="HelveticaNeue, Helvetica Neue"+ font-size="16"+ font-weight="normal"+ >+ <tspan x="360.28" y="196.5">Setup MUST run</tspan>+ <tspan x="349.76" y="214.5">once and only once</tspan>+ </text>+ <line+ x1="420"+ y1="60"+ x2="420"+ y2="89.76"+ id="Path"+ stroke="#444444"+ stroke-width="2"+ ></line>+ <polygon+ id="Path"+ stroke="#444444"+ stroke-width="2"+ fill="#444444"+ fill-rule="nonzero"+ points="420 97.76 416 89.76 424 89.76"+ ></polygon>+ <polygon+ id="Path"+ stroke="#CCCCCC"+ stroke-width="4"+ points="200 285 300 385 200 485 100 385"+ ></polygon>+ <text+ id="Setup-MUST-share-sta"+ fill="#000000"+ fill-rule="nonzero"+ font-family="HelveticaNeue, Helvetica Neue"+ font-size="16"+ font-weight="normal"+ >+ <tspan x="132.28" y="381">Setup MUST share</tspan>+ <tspan x="145.776" y="399">state with tests</tspan>+ </text>+ <line+ x1="370"+ y1="250"+ x2="256.72"+ y2="330.24"+ id="Path"+ stroke="#444444"+ stroke-width="2"+ ></line>+ <g id="Group" transform="translate(280.000000, 274.000000)">+ <rect+ id="Rectangle"+ fill="#FFFFFF"+ x="0"+ y="0"+ width="58"+ height="36"+ ></rect>+ <text+ id="YES"+ fill-rule="nonzero"+ font-family="HelveticaNeue, Helvetica Neue"+ font-size="16"+ font-weight="normal"+ fill="#000000"+ >+ <tspan x="14.244" y="23.5">YES</tspan>+ </text>+ </g>+ <polygon+ id="Path"+ stroke="#444444"+ stroke-width="2"+ fill="#444444"+ fill-rule="nonzero"+ points="251.82 333.71 256.04 325.82 256.72+ 330.24 260.66 332.35"+ ></polygon>+ <a href="#root-hook-plugins">+ <g id="Group-3" transform="translate(0.000000, 580.000000)">+ <rect+ id="Rectangle"+ stroke="#8D6748"+ stroke-width="4"+ x="0"+ y="0"+ width="180"+ height="80"+ rx="12"+ ></rect>+ <text+ id="Use-Root-Hooks-and-A"+ fill="#000000"+ fill-rule="nonzero"+ font-family="HelveticaNeue-Bold, Helvetica Neue"+ font-size="16"+ font-weight="bold"+ >+ <tspan x="11.828" y="37">Use Root Hooks and</tspan>+ <tspan x="14.676" y="56">Avoid Parallel Mode</tspan>+ </text>+ </g>+ </a>+ <line+ x1="150"+ y1="435"+ x2="93.15"+ y2="572.39"+ id="Path"+ stroke="#444444"+ stroke-width="2"+ ></line>+ <polygon+ id="Path"+ stroke="#444444"+ stroke-width="2"+ fill="#444444"+ fill-rule="nonzero"+ points="90.85 577.93 90.22 569.01 93.15 572.39 97.61 572.07"+ ></polygon>+ <line+ x1="250"+ y1="435"+ x2="306.85"+ y2="572.39"+ id="Path"+ stroke="#444444"+ stroke-width="2"+ ></line>+ <polygon+ id="Path"+ stroke="#444444"+ stroke-width="2"+ fill="#444444"+ fill-rule="nonzero"+ points="309.15 577.93 302.39 572.07 306.85 572.39 309.78 569.01"+ ></polygon>+ <a href="#global-fixtures">+ <g id="Group-4" transform="translate(220.000000, 580.000000)">+ <rect+ id="Rectangle"+ stroke="#8D6748"+ stroke-width="4"+ x="0"+ y="0"+ width="180"+ height="80"+ rx="12"+ ></rect>+ <text+ id="Use-Global-Fixtures"+ fill="#000000"+ fill-rule="nonzero"+ font-family="HelveticaNeue-Bold, Helvetica Neue"+ font-size="16"+ font-weight="bold"+ >+ <tspan x="15.648" y="45">Use Global Fixtures</tspan>+ </text>+ </g>+ </a>+ <polygon+ id="Path"+ stroke="#CCCCCC"+ stroke-width="4"+ points="650 285 750 385 650 485 550 385"+ ></polygon>+ <text+ id="Should-setup-affect"+ fill="#000000"+ fill-rule="nonzero"+ font-family="HelveticaNeue, Helvetica Neue"+ font-size="16"+ font-weight="normal"+ >+ <tspan x="580.352" y="381">Should setup affect</tspan>+ <tspan x="569.544" y="399">tests across ALL files?</tspan>+ </text>+ <line+ x1="470"+ y1="250"+ x2="593.11"+ y2="330.49"+ id="Path"+ stroke="#444444"+ stroke-width="2"+ ></line>+ <polygon+ id="Path"+ stroke="#444444"+ stroke-width="2"+ fill="#444444"+ fill-rule="nonzero"+ points="598.13 333.78 589.24 332.75 593.11 330.49 593.62 326.05"+ ></polygon>+ <a href="#root-hook-plugins">+ <g id="Group-5" transform="translate(444.000000, 580.000000)">+ <rect+ id="Rectangle"+ stroke="#8D6748"+ stroke-width="4"+ x="0"+ y="0"+ width="180"+ height="80"+ rx="12"+ ></rect>+ <text+ id="Use-Root-Hooks"+ fill="#000000"+ fill-rule="nonzero"+ font-family="HelveticaNeue-Bold, Helvetica Neue"+ font-size="16"+ font-weight="bold"+ >+ <tspan x="26.776" y="45">Use Root Hooks</tspan>+ </text>+ </g>+ </a>+ <a href="#hooks">+ <g id="Group-6" transform="translate(670.000000, 580.000000)">+ <rect+ id="Rectangle"+ stroke="#8D6748"+ stroke-width="4"+ x="0"+ y="0"+ width="180"+ height="80"+ rx="12"+ ></rect>+ <text+ id="Use-Plain-Hooks"+ fill="#000000"+ fill-rule="nonzero"+ font-family="HelveticaNeue-Bold, Helvetica Neue"+ font-size="16"+ font-weight="bold"+ >+ <tspan x="27.344" y="45">Use Plain Hooks</tspan>+ </text>+ </g>+ </a>+ <line+ x1="600"+ y1="435"+ x2="537.41"+ y2="572.5"+ id="Path"+ stroke="#444444"+ stroke-width="2"+ ></line>+ <g id="Group" transform="translate(91.000000, 486.000000)">+ <rect+ id="Rectangle"+ fill="#FFFFFF"+ x="0"+ y="0"+ width="58"+ height="36"+ ></rect>+ <text+ id="YES"+ fill-rule="nonzero"+ font-family="HelveticaNeue, Helvetica Neue"+ font-size="16"+ font-weight="normal"+ fill="#000000"+ >+ <tspan x="14.244" y="23.5">YES</tspan>+ </text>+ </g>+ <g id="Group" transform="translate(506.000000, 272.000000)">+ <rect+ id="Rectangle"+ fill="#FFFFFF"+ x="0"+ y="0"+ width="58"+ height="36"+ ></rect>+ <text+ id="NO"+ fill-rule="nonzero"+ font-family="HelveticaNeue, Helvetica Neue"+ font-size="16"+ font-weight="normal"+ fill="#000000"+ >+ <tspan x="17.144" y="24">NO</tspan>+ </text>+ </g>+ <g id="Group" transform="translate(252.000000, 485.000000)">+ <rect+ id="Rectangle"+ fill="#FFFFFF"+ x="0"+ y="0"+ width="58"+ height="36"+ ></rect>+ <text+ id="NO"+ fill-rule="nonzero"+ font-family="HelveticaNeue, Helvetica Neue"+ font-size="16"+ font-weight="normal"+ fill="#000000"+ >+ <tspan x="17.144" y="24">NO</tspan>+ </text>+ </g>+ <polygon+ id="Path"+ stroke="#444444"+ stroke-width="2"+ fill="#444444"+ fill-rule="nonzero"+ points="534.93 577.96 534.6 569.03 537.41 572.5 541.88 572.34"+ ></polygon>+ <line+ x1="700"+ y1="435"+ x2="756.85"+ y2="572.39"+ id="Path"+ stroke="#444444"+ stroke-width="2"+ ></line>+ <polygon+ id="Path"+ stroke="#444444"+ stroke-width="2"+ fill="#444444"+ fill-rule="nonzero"+ points="759.15 577.93 752.39 572.07 756.85 572.39 759.78 569.01"+ ></polygon>+ <g id="Group" transform="translate(540.000000, 485.000000)">+ <rect+ id="Rectangle"+ fill="#FFFFFF"+ x="0"+ y="0"+ width="58"+ height="36"+ ></rect>+ <text+ id="YES"+ fill-rule="nonzero"+ font-family="HelveticaNeue, Helvetica Neue"+ font-size="16"+ font-weight="normal"+ fill="#000000"+ >+ <tspan x="14.244" y="23.5">YES</tspan>+ </text>+ </g>+ <g id="Group" transform="translate(699.000000, 489.000000)">+ <rect+ id="Rectangle"+ fill="#FFFFFF"+ x="0"+ y="0"+ width="58"+ height="36"+ ></rect>+ <text+ id="NO"+ fill-rule="nonzero"+ font-family="HelveticaNeue, Helvetica Neue"+ font-size="16"+ font-weight="normal"+ fill="#000000"+ >+ <tspan x="17.144" y="24">NO</tspan>+ </text>+ </g>+ </g>+ </g>+ </svg>+</div>diff --git a/docs/css/style.css b/docs/css/style.cssindex 3104b4f8..c3e3ce6b 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.mdindex 834e59e1..982f8796 100644--- a/docs/index.md+++ b/docs/index.md@@ -1272,7 +1272,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@@ -1368,6 +1372,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@@ -1657,6 +1663,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 %}+## InterfacesMocha's "interface" system allows developers to choose their style of DSL. Mocha has **BDD**, **TDD**, **Exports**, **QUnit** and **Require**-style interfaces.@@ -2395,3 +2408,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