increase timeout in `mocha.spec.js` "unit" test

- 100% coverage for `lib/serializer.js`
- add a trivial integration test for `--parallel`
- fix typo in integration test helper; output spawned command in a copy/pastable format
- remove some unused code
- rename `deserializeMessage` => `deserialize`
- rename `serializeObject` => `serialize`
- docstrings for `lib/serializer.js`
- rewrite `SerializableEvent.serialize` as a loop instead of recursive function due to possibility of exceeding max stack trace; other refactors
- do not freeze objects returned from various `Runnable`'s `serialize()` method, because `SerializableEvent#serialize` needs to mutate them.

- add more comments/docstrings
- some refactors

Signed-off-by: Christopher Hiller <[email protected]>

Signed-off-by: Christopher Hiller <[email protected]>

- refactor `BufferedRunner#run` to be a void fn
- tweak some "bail" handling

Signed-off-by: Christopher Hiller <[email protected]>

- remove `promise.allsettled` shim as may not be needed
- update `unexpected` to latest, which gives us a new assertion
- tweak a unit test for `Runner` to leverage `unexpected-eventemitter`
- tweak wallaby settings; increase test timeout

- refactoring for `lib/worker.js`
- fixed some docstrings

you can now use "to have passed test count", "to have failed test count" and "to have pending test count" with a `RawRunResult` (the result of calling `helpers.runMocha()`)

Signed-off-by: Christopher Hiller <[email protected]>

this was discovered when testing `--parallel` with retries.

also add some debug statements

- adds `runMochaAsync` and `runMochaJSONAsync` for convenience

- `config.spec.js` was misusing `rewiremock`
- `mocha.spec.js` was loading files it shouldn't

…copy-pasting

`Runnable#isPending()` and `Suite#isPending()` needed by reporters, as was `Test#state`

- more useful debug info
- renamed a couple debug namespaces; doing `DEBUG=mocha:parallel*` now provides good general-purpose info

- add more realistic tests around bail usage
- serializer: rename `failures` to `failureCount` to be more obvious
- warn if a single file is executed with `--parallel`
- update some comments / debug statements

Signed-off-by: Christopher Hiller <[email protected]>

- quote strings because YAML is YAML
- remove comment cruft

- also rename `opts` to `options`for optional param to `BufferedRunner#run`
- tweak warning

using template strings makes them eagerly-loaded, which is not needed

- `tap` reporter must report the plan at the END, which is spec-compliant.
- `progress` reporter is incompatible because we do not know the total number of tests up-front.
- `markdown` reporter _could_ be fixed, but it's too much effort atm.  the reason is we don't have a single root suite; we'd need to build the TOC based on every `EVENT_SUITE_BEGIN` begin where the parameter (a deserialized `Suite`) has a `root` prop of `true`.  `Suite#serialize` would need to recursively call `serialize()` on each item in its `suites` prop.
- added a `SIGINT` handler to the `landing` reporter to restore the cursor and not befoul terminals

- rename `loadAsync` prop of `Mocha` to `lazyLoadFiles`, which is more descriptive of its intent
- refactor a lot of `watch-run.js` to support these changes
- remove unneeded `runOptions` parameter of `Mocha#run`
- add a docstring or two
- refactor `--watch` tests to avoid assigning to the context object

- the major change is that `STDERR` will, by default, display in the terminal.  this can be used to catch problems that may otherwise have been overlooked, e.g., `test/integration/fixtures/uncaught/listeners.fixture.js`
- `DEBUG` is explicitly removed from the env, so we can use it without a bunch of noise, and it will not affect inspection of child process output when `pipe` is used to grab `STDERR` from the child.

When a module loaded by `--require` exports an object property `mochaHooks`, it can contain four properties corresponding to the four different types of hooks.

Each prop can be a function or array of functions.  Here's an example using just functions:

```
// hooks.js
exports.mochaHooks = {
  beforeAll() {
    console.log('beforeAll');
  },
  beforeEach() {
    console.log('beforeEach');
  },
  afterAll() {
    console.log('afterAll');
  },
  afterEach() {
    console.log('afterEach');
  }
};
```

Use:

```
mocha --require hooks.js test/**/*.spec.js
```

`--file` does not work as expected before using `--parallel`, because order is non-deterministic.

The `hooks.js` file (and anything else `--require`'d) will be loaded _once per child process_.

this gets annoying too quickly

Signed-off-by: Christopher Hiller <[email protected]>

this could be fixed (but probably not without breaking changes), but again, `runner.total` is the issue.

- add `SIGINT` handling for clean worker death
- don't sent `SIGTERM` in parallel mode; otherwise it can leave processes hanging around
- make `--jobs=0` or `--jobs=1` cause Mocha to run in serial even if `--parallel` is true
- reorganize some yargs checks
- handle uncaught exceptions from worker processes, recovering where possible
- handle `--allow-uncaught` to the best of our ability
- ensure `uncaught.spec.js` doesn't flirt with max listeners
- make `exit.spec.js` handle `SIGINT` and send `SIGTERM` as fixture should be run in serial, but also with `_mocha` (so there is no global `SIGINT` handler; unsure how the hell this worked before); renamed a misnamed test
- skip ESM tests for `--parallel` in unsupported environments
- fix `DEBUG` handling in integration tests
- fix `bail`-related test for `--parallel`
- adds module `promise.allsettled` as a polyfill, which allows us to recover from exceptions in worker processes
- upgrades `unexpected-eventemitter` to v2.1.0, which allows for making event assertions in async functions

an async function (`async () => {}`) will return `asyncfunction` instead of `function`.
who knew!?

limited to node tests for now.

a module can now do:

`exports.mochaHooks = async () => ({/* mocha hooks obj */})`

in addition to

`exports.mochaHooks = { /* mocha hooks obj */ }`

(the function style can be sync or async)

to do this, we use a `middleware()` function in yargs, which (by default)
runs _after_ the checks, but before the handler, _and_ can be async, which it is.

created `createInvalidPlugin` method in `lib/errors.js`

- issue `SIGKILL` in `exit.spec.js` to avoid a potential exception when quitting
- main mocha executable: use `SIGKILL` instead of unsupported `SIGTERM` on main subprocess in win32.

Signed-off-by: Christopher Hiller <[email protected]>

also allows override of `DEBUG` in environment if we really need it.

- do not force-terminate worker pool when bailing (unnecessary)
- use a finite-state-machine-ish thing to manage state
- "correctly" resend `SIGINT` in cleanup listener
- differentiate between "bailing" and "aborting", which have diff't behaviors:
    - "bailing" is the `bail` flag
    - "aborting" is either an uncaught exception (with `--allow-uncaught`) _or_ a `SIGINT` signal

Signed-off-by: Christopher Hiller <[email protected]>

Signed-off-by: Christopher Hiller <[email protected]>

Signed-off-by: Christopher Hiller <[email protected]>

Signed-off-by: Christopher Hiller <[email protected]>

Signed-off-by: Christopher Hiller <[email protected]>

exposes `getSummary()` from integration test helpers

warnings about too many jobs requested; add test

mainly fiddling with regex's.  `[^]` is apparently deprecated (?), so use `[\s\S]` instead.

Signed-off-by: Christopher Hiller <[email protected]>

markdownlint wants a language or fails, but prism doesn't know what to
do with `text` or `plain`, so let's just forget it.