☕️ Classic, reliable, trusted test framework for Node.js and the browser
docs: migrate how-to wiki pages to main documentation (#5463)
Kelechi Ebirib85aec6e4307
diff --git a/docs-next/astro.config.ts b/docs-next/astro.config.tsindex b6c74106..8ee91b54 100644--- a/docs-next/astro.config.ts+++ b/docs-next/astro.config.ts@@ -104,10 +104,6 @@ export default defineConfig({{collapsed: true,items: [- {- label: "Detecting multiple calls to done()",- slug: "explainers/detecting-multiple-calls-to-done",- },{label: "Compilers deprecation",slug: "explainers/compilers-deprecation",@@ -116,10 +112,22 @@ export default defineConfig({label: "Counting assertions",slug: "explainers/count-assertions",},+ {+ label: "Detecting multiple calls to done()",+ slug: "explainers/detecting-multiple-calls-to-done",+ },+ {+ label: "Environment variables",+ slug: "explainers/environment-variables",+ },{label: "Find global leaks",slug: "explainers/find-global-leaks",},+ {+ label: "Global variables",+ slug: "explainers/global-variables",+ },{label: "Node.js native ESM support",slug: "explainers/nodejs-native-esm-support",@@ -144,6 +152,10 @@ export default defineConfig({label: "Spies",slug: "explainers/spies",},+ {+ label: "Stub stdout",+ slug: "explainers/stub-stdout",+ },{label: "Tagging with --grep",slug: "explainers/tagging",diff --git a/docs-next/src/content/docs/explainers/count-assertions.mdx b/docs-next/src/content/docs/explainers/count-assertions.mdxindex 8ceaa6d5..db92325d 100644--- a/docs-next/src/content/docs/explainers/count-assertions.mdx+++ b/docs-next/src/content/docs/explainers/count-assertions.mdx@@ -1,6 +1,6 @@---description: How to count assertions.-title: Count assertions+title: Counting assertions---While Mocha itself does not provide an assertion layer and cannot provide assertion counting, it's relatively easy to integrate this behavior using hooks. The following is a simplified version of an assertion counter:diff --git a/docs-next/src/content/docs/explainers/environment-variables.mdx b/docs-next/src/content/docs/explainers/environment-variables.mdxnew file mode 100644index 00000000..90a0c305--- /dev/null+++ b/docs-next/src/content/docs/explainers/environment-variables.mdx@@ -0,0 +1,41 @@+---+description: Learn how to use environment variables in Mocha tests+title: "Environment variables"+---++Sometimes you might want your test to make use of variables set on an environment level. Common reasons for this include:++- Flagging a run as CI+- Setting the domain of an application+- Pointing to a test database+- Setting a key which you want to remain secure++The best way to do this is to use NodeJS's native environment variables.++## Example++In your `package.json` or directly in a terminal set your variable name and value.++```bash+env CI=STAGE mocha+```++Then in your test or code reference it via `process.env.CI`. e.g.++```javascript+if (process.env.CI === "STAGE") // do something+```++The value is available from anywhere in a spec file allowing you to set values from it before the tests run. e.g.++```javascript+import { equal } from "assert";+import { loadPage } from "your-code";+const URL = `${process.env.APP_HOST}/${process.env.APP_URI}`;+describe('Test the page loads', () {+ it('goes to URL', () => {+ const page = loadPage(URL);+ equal(page.url, URL);+ });+});+```diff --git a/docs-next/src/content/docs/explainers/global-variables.mdx b/docs-next/src/content/docs/explainers/global-variables.mdxnew file mode 100644index 00000000..cb1b255a--- /dev/null+++ b/docs-next/src/content/docs/explainers/global-variables.mdx@@ -0,0 +1,60 @@+---+description: How to work with global variables in Mocha tests+title: "Global variables"+---++Related issue [#1582](https://github.com/mochajs/mocha/issues/1582)++If your test manipulates global variables, a reasonable expectation is that you will clean up after yourself. This includes commonly called methods such as `process.stdout.write()` or `console.log()`.++```js+var expect = require("chai").expect;++describe("my nice test", function () {+ var write,+ log,+ output = "";++ // restore process.stdout.write() and console.log() to their previous glory+ var cleanup = function () {+ process.stdout.write = write;+ console.log = log;+ output = "";+ };++ beforeEach(function () {+ // store these functions to restore later because we are messing with them+ write = process.stdout.write;+ log = console.log;++ // our stub will concatenate any output to a string+ process.stdout.write = console.log = function (s) {+ output += s;+ };+ });++ // restore after each test+ afterEach(cleanup);++ it("should suppress all output if a non-AssertionError was thrown", function () {+ process.stdout.write("foo");+ console.log("bar");+ // uncomment below line to suppress output, which is bad+ // expect(output).to.equal(foobar);+ expect(output).to.equal("foobar");+ });++ it("should not suppress any output", function () {+ try {+ process.stdout.write("foo");+ console.log("bar");+ // uncomment below line to just throw an AssertionError+ // expect(output).to.equal('barfoo');+ expect(output).to.equal(foobar); // ReferenceError+ } catch (e) {+ cleanup();+ throw e;+ }+ });+});+```diff --git a/docs-next/src/content/docs/explainers/stub-stdout.mdx b/docs-next/src/content/docs/explainers/stub-stdout.mdxnew file mode 100644index 00000000..cfa9a2a1--- /dev/null+++ b/docs-next/src/content/docs/explainers/stub-stdout.mdx@@ -0,0 +1,34 @@+---+description: Learn how to properly stub stdout for testing console output+title: "Stubbing stdout"+---++If you want to stub `stdout` inside your own code (via `process.stdout.write` or `console.log`) there is a potential to hinder Mocha's reporter output. This is because they rely on the same mechanisms to print results of the tests.++i.e.++```javascript+it('should do, but it do not', function() {+ // user wants to hide output generated by console.log calls in fn 'foo'+ console.log = function() {};+ foo();++ expect(...)+});+```++This will result in a faulty reporter output.++The correct way to handle this is to stub before and restore after the function call.++```javascript+it('will do', function() {+ var consoleLogStub = sinon.stub(console, 'log');+ foo();+ consoleLogStub.restore();++ expect(...)+});+```++Now the reporters can run and print the assertion without any interference, while stubbing `stdout` inside your function.diff --git a/docs/api-tutorials/environment-variables.md b/docs/api-tutorials/environment-variables.mdnew file mode 100644index 00000000..847433d4--- /dev/null+++ b/docs/api-tutorials/environment-variables.md@@ -0,0 +1,36 @@+Sometimes you might want your test to make use of variables set on an environment level. Common reasons for this include:++- Flagging a run as CI+- Setting the domain of an application+- Pointing to a test database+- Setting a key which you want to remain secure++The best way to do this is to use NodeJS's native environment variables.++## Example++In your `package.json` or directly in a terminal set your variable name and value.++```bash+env CI=STAGE mocha+```++Then in your test or code reference it via `process.env.CI`. e.g.++```javascript+if (process.env.CI === "STAGE") // do something+```++The value is available from anywhere in a spec file allowing you to set values from it before the tests run. e.g.++```javascript+import { equal } from "assert";+import { loadPage } from "your-code";+const URL = `${process.env.APP_HOST}/${process.env.APP_URI}`;+describe('Test the page loads', () {+ it('goes to URL', () => {+ const page = loadPage(URL);+ equal(page.url, URL);+ });+});+```diff --git a/docs/api-tutorials/global-variables.md b/docs/api-tutorials/global-variables.mdnew file mode 100644index 00000000..00d03b84--- /dev/null+++ b/docs/api-tutorials/global-variables.md@@ -0,0 +1,55 @@+Related issue [#1582](https://github.com/mochajs/mocha/issues/1582)++If your test manipulates global variables, a reasonable expectation is that you will clean up after yourself. This includes commonly called methods such as `process.stdout.write()` or `console.log()`.++```js+var expect = require("chai").expect;++describe("my nice test", function () {+ var write,+ log,+ output = "";++ // restore process.stdout.write() and console.log() to their previous glory+ var cleanup = function () {+ process.stdout.write = write;+ console.log = log;+ output = "";+ };++ beforeEach(function () {+ // store these functions to restore later because we are messing with them+ write = process.stdout.write;+ log = console.log;++ // our stub will concatenate any output to a string+ process.stdout.write = console.log = function (s) {+ output += s;+ };+ });++ // restore after each test+ afterEach(cleanup);++ it("should suppress all output if a non-AssertionError was thrown", function () {+ process.stdout.write("foo");+ console.log("bar");+ // uncomment below line to suppress output, which is bad+ // expect(output).to.equal(foobar);+ expect(output).to.equal("foobar");+ });++ it("should not suppress any output", function () {+ try {+ process.stdout.write("foo");+ console.log("bar");+ // uncomment below line to just throw an AssertionError+ // expect(output).to.equal('barfoo');+ expect(output).to.equal(foobar); // ReferenceError+ } catch (e) {+ cleanup();+ throw e;+ }+ });+});+```diff --git a/docs/api-tutorials/jsdoc.tutorials.json b/docs/api-tutorials/jsdoc.tutorials.jsonindex 0b530e93..ec665e61 100644--- a/docs/api-tutorials/jsdoc.tutorials.json+++ b/docs/api-tutorials/jsdoc.tutorials.json@@ -8,8 +8,14 @@"custom-reporter": {"title": "Create a Custom Reporter"},- "developing-mocha": {- "title": "Developing Mocha"+ "environment-variables": {+ "title": "Environment variables"+ },+ "find-global-leaks": {+ "title": "Find global leaks"+ },+ "global-variables": {+ "title": "Global variables"},"programmatic-usage": {"title": "Programmatic usage"@@ -23,6 +29,9 @@"spies": {"title": "Spies"},+ "stub-stdout": {+ "title": "Stub stdout"+ },"tagging": {"title": "Tagging with --grep"},diff --git a/docs/api-tutorials/related-tools.md b/docs/api-tutorials/related-tools.mdindex dfbffd99..c678287e 100644--- a/docs/api-tutorials/related-tools.md+++ b/docs/api-tutorials/related-tools.md@@ -1,5 +1,3 @@-# Related Tools-## Assertion Libraries- [chai](http://chaijs.com/) (recommended): expect(), assert(), and should style assertionsdiff --git a/docs/api-tutorials/stub-stdout.md b/docs/api-tutorials/stub-stdout.mdnew file mode 100644index 00000000..244275d2--- /dev/null+++ b/docs/api-tutorials/stub-stdout.md@@ -0,0 +1,29 @@+If you want to stub `stdout` inside your own code (via `process.stdout.write` or `console.log`) there is a potential to hinder Mocha's reporter output. This is because they rely on the same mechanisms to print results of the tests.++i.e.++```javascript+it('should do, but it do not', function() {+ // user wants to hide output generated by console.log calls in fn 'foo'+ console.log = function() {};+ foo();++ expect(...)+});+```++This will result in a faulty reporter output.++The correct way to handle this is to stub before and restore after the function call.++```javascript+it('will do', function() {+ var consoleLogStub = sinon.stub(console, 'log');+ foo();+ consoleLogStub.restore();++ expect(...)+});+```++Now the reporters can run and print the assertion without any interference, while stubbing `stdout` inside your function.