docs: migrate programmatic usage to docs, development content to DEVELOPMENT.md

.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
+
+Retrieve 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/mochajs/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

docs-next/astro.config.ts

@@ -124,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",

docs-next/src/content/docs/explainers/programmatic-usage.mdx

@@ -0,0 +1,74 @@
+---
+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/9a7053349589344236b20301de965030eaabfea9/lib/runner.js#L52) 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/main/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.

docs/api-tutorials/jsdoc.tutorials.json

@@ -8,6 +8,12 @@
   "custom-reporter": {
     "title": "Create a Custom Reporter"
   },
+  "developing-mocha": {
+    "title": "Developing Mocha"
+  },
+  "programmatic-usage": {
+    "title": "Programmatic usage"
+  },
   "related-tools": {
     "title": "Related tools"
   },

docs/api-tutorials/programmatic-usage.md

@@ -0,0 +1,69 @@
+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/9a7053349589344236b20301de965030eaabfea9/lib/runner.js#L52) 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/main/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.