Merge branch 'main' into feat/esm-config

Author: mark-wiemer

.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

.github/workflows/npm-script.yml

@@ -62,7 +62,7 @@ jobs:
       - uses: actions/checkout@v5
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v5
+      - uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node_version }}
           cache: "npm"

.github/workflows/release-please.yml

@@ -36,7 +36,7 @@ jobs:
       - uses: actions/checkout@v5
         with:
           show-progress: false
-      - uses: actions/setup-node@v5
+      - uses: actions/setup-node@v6
         with:
           # The 22.11.0 is instead of lts per https://github.com/mochajs/mocha/issues/5278
           node-version: "22.11.0"

MAINTAINERS.md

@@ -90,9 +90,8 @@ Your public behavior, whether in the physical or virtual world, reflects upon th
 > If you don't understand the code of conduct, or why it exists, it is _your responsibility_ to educate yourself.
 > This does not imply the CoC is immutable.
 
-Furthermore, a maintainer is a contributor who **contributes regularly**, or expresses a _desire to do so._ That could be every day--but it might be once a week, or even once a month.
-Your boss doesn't work here; contribute as often as you wish.
-We are all people with Real Lives, and for many of us, contributing to OSS is just a hobby!
+Furthermore, a maintainer is a contributor who **contributes regularly**. That can be daily, weekly, or even just a few times a month -- as long as it's regular.
+We are all people with Real Lives, and for many of us, contributing to OSS is just an occasional hobby!
 
 Finally, a maintainer must help define what makes Mocha "Mocha".
 At minimum, a maintainer must _understand_ the current definition (if a maintainer is not interested in decision-making).
@@ -108,7 +107,7 @@ As maintainers, _we work together_ to learn about the nature of these questions.
 
 A maintainer _must_ also have 2FA enabled on their GitHub account.
 
-> If you think that you aren't familiar with mocha's internals enough to contribute, please watch [This walkthrough video!](https://youtu.be/zLayCLcIno0)
+> If you think that you aren't familiar with mocha's internals enough to contribute, please watch [this walkthrough video](https://youtu.be/zLayCLcIno0)!
 
 #### The Rights of a Maintainer
 
@@ -127,6 +126,28 @@ You may choose to do zero or more of these _at their discretion_:
 > For example, a spelling correction in `CHANGELOG.md` may not require a pull request.
 > A change to a reporter's output most certainly would! Maintainers are trusted to use their best judgement; if unsure, err on the side of caution.
 
+#### Expected Activity Levels
+
+We generally expect maintainers to average at least:
+
+- Multiple contributions of any kind in a week
+- One meaningful, non-trivial contribution per month
+
+These are rough averages, not strict minimums!
+It's totally fine to skip a week or two here and there, as long as you do a little more before or after.
+Meaningful, non-trivial contributions can be a well-thought-out comment, sending a non-straightforward pull request, or anything else that adds real value to the project.
+
+If you have to step away longer than a couple of weeks, that's totally fine too.
+Just let the other maintainers know ahead of time.
+
+- If you need to step away for up to a month or two, don't sweat it.
+- If we don't hear from you for a month without prior notice, we'll check in with you to see if you want to remain a maintainer.
+- After three months of inactivity, or two without prior notice, we'll likely remove you as a maintainer.
+
+Again, don't stress about this if you can't always be available.
+Your boss doesn't work here; contribute as often as you reasonably can.
+Even if you step down or are removed, if you can come back and be regularly active we'll happily reinstate you.
+
 #### About "Owners"
 
 Some maintainers will have full admin rights to the [mochajs org](https://github.com/mochajs) and/or will have access to publish to npm.
@@ -142,6 +163,7 @@ If that fails, we decide by a simple vote.
 
 Active maintainers will make an effort to solicit feedback from others before making important or potentially controversial decisions.
 Given the varying geographical distribution and availability of the maintenance team, we resolve to do the best we can to solicit feedback.
+We will wait at least two weeks for consensus votes in most cases, and a month for especially important decisions.
 
 In other words, to have your opinion heard, participate regularly.
 The rest of the team won't wait on feedback that isn't necessarily forthcoming!

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,14 +112,30 @@ 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",
             },
+            {
+              label: "Programmatic usage",
+              slug: "explainers/programmatic-usage",
+            },
             {
               label: "Related tools",
               slug: "explainers/related-tools",
@@ -140,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",

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:

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);
+  });
+});
+```

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;
+    }
+  });
+});
+```

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-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.