Skip to content

armgit / mocha

Public Imported from GitHub
0

☕️ 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.sketch
new file mode 100644
index 00000000..6f3ab957
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 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 OC
diff --git a/docs/_includes/fixture-wizard.html b/docs/_includes/fixture-wizard.html
new file mode 100644
index 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.css
index 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.md
index 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 %}
+
## Interfaces
Mocha'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