Skip to content

armgit / mocha

Public Imported from GitHub
0

☕️ 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.ts
index 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.mdx
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.json
index 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.md
index 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 assertions
diff --git a/docs/api-tutorials/stub-stdout.md b/docs/api-tutorials/stub-stdout.md
new file mode 100644
index 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.