Mocha: Add new --add-file CLI flag

[hswolff]

Prerequisites

• [x] Checked that your issue isn't already filed by cross referencing issues with the common mistake label
• [x] Checked next-gen ES issues and syntax problems by using the same environment and/or transpiler configuration without Mocha to ensure it isn't just a feature that actually isn't supported in the environment in question or a bug in your code.
• [x] 'Smoke tested' the code to be tested by running it outside the real test suite to get a better sense of whether the problem is in the code under test, your usage of Mocha, or Mocha itself
• [x] Ensured that there is no discrepancy between the locally and globally installed versions of Mocha. You can find them with:
  node node_modules/.bin/mocha --version(Local) and mocha --version(Global). We recommend avoiding the use of globally installed Mocha.

Description

Currently there is a way for mocha to require a file globally via the CLI --require flag. This occurs before the mocha test suite is created and ran. This works and is great.

However there is no way to add a file to the mocha test suite via the CLI. There is a way programmatically via mocha.addFile() and you can simulate it via adding individual files when calling mocha mocha myAddFile1.js myAddFile2.js actualTestFile.js, but there is no official CLI way to always require files within the mocha test suite.

This is useful when setting up shared before and after handlers, or anything else that needs to act on the test suite.

I opened this ticket to explore the desirability of adding a --add-file CLI flag as an interface to the mocha.addFile function.

Additional Information

The desire for this addition came as a result of work I did when trying to integrate jest-runner-mocha into our tests suite.

[Bamieh]

The CLI expects a list of files as arguments, which are added in order.

$ mocha test/hooks.js tests/**/*.test.js --require=babel-register

This will run the hooks.js file then the *.test.js tests.

Can you elaborate if this solves your issue? or if this implementation is missing anything?

[hswolff]

I'm worried I didn't explain the use case well. Maybe @ljharb will be able to?

[ljharb]

The issue is that when a project needs to always run a global beforeEach or afterEach, and doesn’t want to force everyone who runs mocha to remember to specify it in the proper order. By allowing it to be a CLI option, it can also go in mocha.opts, which allows it to be encoded in the project instead of in each invocation.

(I don’t believe positional arguments work in mocha.opts, or else I’d use that)

[boneskull]

A workaround is this:

$ mocha --require init-global-hooks.js test.spec.js

Where init-global-hooks.js is this:

module.parent.require('commander').args.unshift('before-each.js', 'after-each.js');

before-each.js and after-each.js, respectively:

beforeEach(function () {
  console.log('global before each');
});

afterEach(function () {
  console.log('global after each');
});

test.spec.js:

describe('my suite', function () {
  it('should execute both global hooks', function () {
  });
});

$ mocha --require init-global-hooks.js test.spec.js


  my suite
global before each
    ✓ should execute both global hooks
global after each


  1 passing (6ms)

[ljharb]

I mean, thanks, but I hope you agree that that's a pretty atrociously complex workaround :-) (and it relies on module.parent, ick)

[boneskull]

@ljharb yes, I never claimed it was an elegant workaround, but it does accomplish same thing w/o needing to add commander as a dependency.

Using a positional arg in mocha.opts means you can't use any other positional args when invoking mocha, afaict.

I think --file as an alias (of sorts) for a positional argument would be reasonable. I think that's all we're really talking about here, yes? The user is still responsible for the order in which the arguments are given:

$ mocha --file loaded-first.js --file loaded-second.js

Though specifying --file multiple times seems unnecessary in the general sense. Either way, all --file args will be run before positional ones.

[ljharb]

Yes, that sounds like exactly what we'd need here - user-controlled ordering, preferential execution before all positional arguments, and works in mocha.opts without interfering with normal usage of the CLI. Thanks!