From 89f7c0dcf8c6f979b9de2f678dc47bc99ef52e60 Mon Sep 17 00:00:00 2001 From: Kelechi Ebiri Date: Fri, 12 Sep 2025 22:57:59 +0100 Subject: [PATCH 1/2] docs: migrate developer-focused wiki pages to main documentation Migrate 2 developer-focused wiki pages to both docs systems: - Using Mocha programmatically - Developing mocha Part of #5248 wiki migration effort. Signed-off-by: Kelechi Ebiri --- docs-next/astro.config.ts | 8 ++ .../docs/explainers/developing-mocha.mdx | 36 +++++++++ .../docs/explainers/programmatic-usage.mdx | 75 +++++++++++++++++++ docs/api-tutorials/developing-mocha.md | 32 ++++++++ docs/api-tutorials/jsdoc.tutorials.json | 6 ++ docs/api-tutorials/programmatic-usage.md | 72 ++++++++++++++++++ 6 files changed, 229 insertions(+) create mode 100644 docs-next/src/content/docs/explainers/developing-mocha.mdx create mode 100644 docs-next/src/content/docs/explainers/programmatic-usage.mdx create mode 100644 docs/api-tutorials/developing-mocha.md create mode 100644 docs/api-tutorials/programmatic-usage.md diff --git a/docs-next/astro.config.ts b/docs-next/astro.config.ts index eb4f2bb994..47a2e9d014 100644 --- a/docs-next/astro.config.ts +++ b/docs-next/astro.config.ts @@ -112,6 +112,10 @@ export default defineConfig({ label: "Counting assertions", slug: "explainers/count-assertions", }, + { + label: "Developing Mocha", + slug: "explainers/developing-mocha", + }, { label: "Find global leaks", slug: "explainers/find-global-leaks", @@ -120,6 +124,10 @@ export default defineConfig({ label: "Node.js native ESM support", slug: "explainers/nodejs-native-esm-support", }, + { + label: "Programmatic usage", + slug: "explainers/programmatic-usage", + }, { label: "Related tools", slug: "explainers/related-tools", diff --git a/docs-next/src/content/docs/explainers/developing-mocha.mdx b/docs-next/src/content/docs/explainers/developing-mocha.mdx new file mode 100644 index 0000000000..3680dd7986 --- /dev/null +++ b/docs-next/src/content/docs/explainers/developing-mocha.mdx @@ -0,0 +1,36 @@ +--- +description: Developing Mocha". +title: Developing Mocha +--- + +This page contains info on developing Mocha itself. + +## Environment setup + +When you contribute to mocha itself, you will probably want to try to run your changes on the test suite of another project. You can (and should) run the test suite of mocha itself before committing, but also confirming that your changes give the expected result on another project can be useful. + +For example, [WebSocket.io](https://github.com/LearnBoost/websocket.io/): + + $ git clone https://github.com/LearnBoost/websocket.io.git + +Retreive websocket.io's dependencies, which will include the stable version of mocha: + + $ cd websocket.io/ + $ npm install + +Replace the mocha dependency by the current git repository: + + $ cd node_modules/ + $ mv mocha/ mocha.save + $ git clone https://github.com/visionmedia/mocha.git + +Install mocha's dependencies for the development version: + + $ cd mocha + $ npm install + +Run websocket.io's test suite using the development version you just installed: + + $ cd ../.. + $ ./node_modules/.bin/mocha + diff --git a/docs-next/src/content/docs/explainers/programmatic-usage.mdx b/docs-next/src/content/docs/explainers/programmatic-usage.mdx new file mode 100644 index 0000000000..041484d5dd --- /dev/null +++ b/docs-next/src/content/docs/explainers/programmatic-usage.mdx @@ -0,0 +1,75 @@ +--- +description: Using Mocha programmatically +title: Programmatic usage +--- + +There are a lot of reasons why you might want to automate running the tests using Mocha. Using the command-line can run into some problems if you want to load specific files, for example. + +Here is an example of using Mocha programmatically: + +```javascript +var Mocha = require('mocha'), + fs = require('fs'), + path = require('path'); + +// Instantiate a Mocha instance. +var mocha = new Mocha(); + +var testDir = 'some/dir/test' + +// Add each .js file to the mocha instance +fs.readdirSync(testDir).filter(function(file) { + // Only keep the .js files + return file.substr(-3) === '.js'; + +}).forEach(function(file) { + mocha.addFile( + path.join(testDir, file) + ); +}); + +// Run the tests. +mocha.run(function(failures) { + process.exitCode = failures ? 1 : 0; // exit with non-zero status if there were failures +}); +``` + +`mocha.run()` returns a `Runner` instance which emits many [events](https://github.com/mochajs/mocha/blob/8cae7a34f0b6eafeb16567beb8852b827cc5956b/lib/runner.js#L47-L57) of interest. + +Note that `run` (via `loadFiles`, which it calls) relies on Node's `require` to execute the test interface functions. Thus, files loaded by Mocha will be stored in Node's `require` cache and therefore tests in these files will not be re-run if `mocha.run()` is called again. If you want to run tests multiple times, you may need to clear Node's `require` cache before subsequent calls in whichever manner best suits your needs. The upcoming Mocha-6.0 release will provide `Mocha#unloadFiles`, which will remove all files loaded by `Mocha#loadFiles`. + +Unfortunately, event listeners in multiple places are not yet configured for restartability; for now, we recommend recreating the `mocha` instance before rerunning to _ensure_ everything gets reset properly. + +Find a fully [working example here](https://github.com/mochajs/mocha-examples/tree/master/packages/programmatic-usage). + +## Set options + +There are two ways to set the options to run the tests. + +Firstly, you can set these options in the constructor object: + +```javascript +var mocha = new Mocha({ + ui: 'tdd', + reporter: 'list' +}); +``` + +Please check our [API documentation](https://mochajs.org/api/mocha) for a complete list of these options. + +Secondly, on the `mocha` object, there are some chainable methods allowing you to change some more options. + +Here is an example: + +```javascript +// Change the reporter to "list" before running the tests +mocha.reporter('list').run(); + +// Change the UI to "tdd" before running the tests +mocha.ui('tdd').run(); + +// Or do both changes before running the tests +mocha.reporter('list').ui('tdd').run(); +``` + +Please check our [API documentation](https://mochajs.org/api/mocha) for more information. diff --git a/docs/api-tutorials/developing-mocha.md b/docs/api-tutorials/developing-mocha.md new file mode 100644 index 0000000000..cc37b6bc1c --- /dev/null +++ b/docs/api-tutorials/developing-mocha.md @@ -0,0 +1,32 @@ +# Developing Mocha + +This page contains info on developing Mocha itself. + +## Environment setup + +When you contribute to mocha itself, you will probably want to try to run your changes on the test suite of another project. You can (and should) run the test suite of mocha itself before committing, but also confirming that your changes give the expected result on another project can be useful. + +For example, [WebSocket.io](https://github.com/LearnBoost/websocket.io/): + + $ git clone https://github.com/LearnBoost/websocket.io.git + +Retreive websocket.io's dependencies, which will include the stable version of mocha: + + $ cd websocket.io/ + $ npm install + +Replace the mocha dependency by the current git repository: + + $ cd node_modules/ + $ mv mocha/ mocha.save + $ git clone https://github.com/visionmedia/mocha.git + +Install mocha's dependencies for the development version: + + $ cd mocha + $ npm install + +Run websocket.io's test suite using the development version you just installed: + + $ cd ../.. + $ ./node_modules/.bin/mocha diff --git a/docs/api-tutorials/jsdoc.tutorials.json b/docs/api-tutorials/jsdoc.tutorials.json index ba7390a3a0..4464cf1c93 100644 --- a/docs/api-tutorials/jsdoc.tutorials.json +++ b/docs/api-tutorials/jsdoc.tutorials.json @@ -5,6 +5,12 @@ "custom-reporter": { "title": "Create a Custom Reporter" }, + "developing-mocha": { + "title": "Developing Mocha" + }, + "programmatic-usage": { + "title": "Programmatic usage" + }, "related-tools": { "title": "Related tools" }, diff --git a/docs/api-tutorials/programmatic-usage.md b/docs/api-tutorials/programmatic-usage.md new file mode 100644 index 0000000000..511ccf2d5f --- /dev/null +++ b/docs/api-tutorials/programmatic-usage.md @@ -0,0 +1,72 @@ +# using Mocha programmatically + +There are a lot of reasons why you might want to automate running the tests using Mocha. Using the command-line can run into some problems if you want to load specific files, for example. + +Here is an example of using Mocha programmatically: + +```javascript +var Mocha = require('mocha'), + fs = require('fs'), + path = require('path'); + +// Instantiate a Mocha instance. +var mocha = new Mocha(); + +var testDir = 'some/dir/test' + +// Add each .js file to the mocha instance +fs.readdirSync(testDir).filter(function(file) { + // Only keep the .js files + return file.substr(-3) === '.js'; + +}).forEach(function(file) { + mocha.addFile( + path.join(testDir, file) + ); +}); + +// Run the tests. +mocha.run(function(failures) { + process.exitCode = failures ? 1 : 0; // exit with non-zero status if there were failures +}); +``` + +`mocha.run()` returns a `Runner` instance which emits many [events](https://github.com/mochajs/mocha/blob/8cae7a34f0b6eafeb16567beb8852b827cc5956b/lib/runner.js#L47-L57) of interest. + +Note that `run` (via `loadFiles`, which it calls) relies on Node's `require` to execute the test interface functions. Thus, files loaded by Mocha will be stored in Node's `require` cache and therefore tests in these files will not be re-run if `mocha.run()` is called again. If you want to run tests multiple times, you may need to clear Node's `require` cache before subsequent calls in whichever manner best suits your needs. The upcoming Mocha-6.0 release will provide `Mocha#unloadFiles`, which will remove all files loaded by `Mocha#loadFiles`. + +Unfortunately, event listeners in multiple places are not yet configured for restartability; for now, we recommend recreating the `mocha` instance before rerunning to _ensure_ everything gets reset properly. + +Find a fully [working example here](https://github.com/mochajs/mocha-examples/tree/master/packages/programmatic-usage). + +## Set options + +There are two ways to set the options to run the tests. + +Firstly, you can set these options in the constructor object: + +```javascript +var mocha = new Mocha({ + ui: 'tdd', + reporter: 'list' +}); +``` + +Please check our [API documentation](https://mochajs.org/api/mocha) for a complete list of these options. + +Secondly, on the `mocha` object, there are some chainable methods allowing you to change some more options. + +Here is an example: + +```javascript +// Change the reporter to "list" before running the tests +mocha.reporter('list').run(); + +// Change the UI to "tdd" before running the tests +mocha.ui('tdd').run(); + +// Or do both changes before running the tests +mocha.reporter('list').ui('tdd').run(); +``` + +Please check our [API documentation](https://mochajs.org/api/mocha) for more information. From 9efcd3e7943bab94b4f1b1232adb55af26f3a269 Mon Sep 17 00:00:00 2001 From: Kelechi Ebiri Date: Mon, 3 Nov 2025 01:46:27 +0100 Subject: [PATCH 2/2] docs: split wiki content appropriately - Move 'Developing mocha' wiki content to .github/DEVELOPMENT.md - Keep 'Using Mocha programmatically' in public docs --- .github/DEVELOPMENT.md | 29 +++++++++++++++ .../docs/explainers/developing-mocha.mdx | 36 ------------------- docs/api-tutorials/developing-mocha.md | 32 ----------------- 3 files changed, 29 insertions(+), 68 deletions(-) delete mode 100644 docs-next/src/content/docs/explainers/developing-mocha.mdx delete mode 100644 docs/api-tutorials/developing-mocha.md diff --git a/.github/DEVELOPMENT.md b/.github/DEVELOPMENT.md index 6969670779..c5661171db 100644 --- a/.github/DEVELOPMENT.md +++ b/.github/DEVELOPMENT.md @@ -16,3 +16,32 @@ If you are having trouble, don't be afraid to [ask for help](./CONTRIBUTING.md# - Do not use `yarn install` or `pnpm install`. - Some optional dependencies may fail; you can safely ignore these unless you are trying to build the documentation. - If you're sick of seeing the failures, run `npm install --ignore-scripts`. + +## Developing Mocha + +When you contribute to mocha, you will probably want to try to run your changes on the test suite of another project. You can (and should) run the test suite of mocha itself before committing, but also confirming that your changes give the expected result on another project. + +For example, [WebSocket.io](https://github.com/LearnBoost/websocket.io/): + + $ git clone https://github.com/LearnBoost/websocket.io.git + +Retreive websocket.io's dependencies, which will include the stable version of mocha: + + $ cd websocket.io/ + $ npm install + +Replace the mocha dependency by the current git repository: + + $ cd node_modules/ + $ mv mocha/ mocha.save + $ git clone https://github.com/visionmedia/mocha.git + +Install mocha's dependencies for the development version: + + $ cd mocha + $ npm install + +Run websocket.io's test suite using the development version you just installed: + + $ cd ../.. + $ ./node_modules/.bin/mocha diff --git a/docs-next/src/content/docs/explainers/developing-mocha.mdx b/docs-next/src/content/docs/explainers/developing-mocha.mdx deleted file mode 100644 index 3680dd7986..0000000000 --- a/docs-next/src/content/docs/explainers/developing-mocha.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -description: Developing Mocha". -title: Developing Mocha ---- - -This page contains info on developing Mocha itself. - -## Environment setup - -When you contribute to mocha itself, you will probably want to try to run your changes on the test suite of another project. You can (and should) run the test suite of mocha itself before committing, but also confirming that your changes give the expected result on another project can be useful. - -For example, [WebSocket.io](https://github.com/LearnBoost/websocket.io/): - - $ git clone https://github.com/LearnBoost/websocket.io.git - -Retreive websocket.io's dependencies, which will include the stable version of mocha: - - $ cd websocket.io/ - $ npm install - -Replace the mocha dependency by the current git repository: - - $ cd node_modules/ - $ mv mocha/ mocha.save - $ git clone https://github.com/visionmedia/mocha.git - -Install mocha's dependencies for the development version: - - $ cd mocha - $ npm install - -Run websocket.io's test suite using the development version you just installed: - - $ cd ../.. - $ ./node_modules/.bin/mocha - diff --git a/docs/api-tutorials/developing-mocha.md b/docs/api-tutorials/developing-mocha.md deleted file mode 100644 index cc37b6bc1c..0000000000 --- a/docs/api-tutorials/developing-mocha.md +++ /dev/null @@ -1,32 +0,0 @@ -# Developing Mocha - -This page contains info on developing Mocha itself. - -## Environment setup - -When you contribute to mocha itself, you will probably want to try to run your changes on the test suite of another project. You can (and should) run the test suite of mocha itself before committing, but also confirming that your changes give the expected result on another project can be useful. - -For example, [WebSocket.io](https://github.com/LearnBoost/websocket.io/): - - $ git clone https://github.com/LearnBoost/websocket.io.git - -Retreive websocket.io's dependencies, which will include the stable version of mocha: - - $ cd websocket.io/ - $ npm install - -Replace the mocha dependency by the current git repository: - - $ cd node_modules/ - $ mv mocha/ mocha.save - $ git clone https://github.com/visionmedia/mocha.git - -Install mocha's dependencies for the development version: - - $ cd mocha - $ npm install - -Run websocket.io's test suite using the development version you just installed: - - $ cd ../.. - $ ./node_modules/.bin/mocha