🚀 Feature: Normalize non-reporter command-line output

[boneskull]

Any time Mocha prints to the command-line with intention to inform the end-user of something, it should be:

• obvious that it's Mocha doing the writing
• color-coded, where appropriate
• uniform in style, content and convention

This includes:

• "fatal" error messages, which are any errors occurring outside of a test run (including errors which occur during a test run, but are Mocha's fault)
• error messages from incorrect usage of command-line options
• any user feedback in "watch" mode ("waiting for changes...")

This specifically does not include (for the purposes of this issue):

• errors due to incorrect programmatic usage of Mocha, e.g., "internal function x() was called with bad parameters"; these are expected to simply throw/reject and be handled by Node.js' default behavior
• errors which cannot otherwise be triggered outside of CLI usage
• errors which only occur in a browser
• debug messages

Identifier

A standard prefix should be used for all output, e.g., [mocha] or mocha: or something.

Log Levels

Messages may want to all be prefixed with a log level, e.g., ERROR, WARN, INFO, OK etc.

Useful Symbols

I find visual symbols (such as those provided by log-symbols to be helpful. This is not the same as emoji. mocha already depends on log-symbols.

Colors

We need to decide on a color scheme representing various "log levels". There's precedent for this elsewhere, so for example:

• red = error
• yellow = warning
• blue = information
• green = success

It is not necessary (IMO) to display the entire message in one of these colors (as that can be hard to read), but perhaps just the prefix and/or the log level and/or the symbol should be in color.

Structured Output

Output such as lists and tables of information should have a standard formatting.

Stack Traces

In general, a stack trace from actually unexpected errors should be shown. These are uncaught exceptions or unhandled rejections that Mocha does not throw itself (and can be displayed to and end-user on the command-line). All other stack traces from, e.g., misuse of a command-line option, should suppress a stack trace because it is not useful or actionable for an end-user. Such an error message should explain what is wrong (e.g., "--foo expected a string parameter"), and in the case of a misused command-line option, should display the help text above this (as shown via mocha --help). I think this already happens.

STDOUT or STDERR?

Program output should write to STDOUT; anything else should write to STDERR. In nearly all cases, Mocha's output is that of whatever reporter is chosen. These write to STDOUT by default (if they do not explicitly write to a different stream). Error messages should be written to STDERR, maybe including help output which may be printed when an error occurs (might be awkward to force yargs to do this). However, the output of mocha --help should be to STDOUT, as the help output is the program output.

Writing Style

The aim is consistency. If we're printing something after it happened, we need to use past tense. If we're printing it as it happens, we should use present participle tense ("waiting.."). It should be written in third person, e.g., Mocha encountered invalid option _x_. Mocha should be capitalized; it's a proper noun. Mocha is the name of the tool; not MochaJS.

Use of Emoji

Emoji is not supported equally across all popular consoles, so if we do decide to use emoji:

1. we should use it sparingly
2. the rest of the message should make sense w/o the emoji
3. if emoji is unsupported, we should fallback to just not printing it

I don't really have a preference here, but I know Emoji-in-the-terminal bothers some people.

A new abstraction?

We could call console.log and console.error directly, or choose/build an abstraction (such as a 3rd-party logging library) on top of it. It will certainly be easier to manage things like prefixes, colors, and error levels with an abstraction (as well as potentially redirecting the output elsewhere). Mocha already uses debug which suits us pretty well, but a different abstraction may make this library redundant.

To be clear, we can address all of the above without introducing a new abstraction, though it may prove tedious. We may find it is not actually tedious, so we can get away without an abstraction.

Notes

Browser print console.* output as well! How much do we need to worry about this? How much of our non-reporter output is actually shown in the browser this way? I have a feeling most of it does not get bundled...

---

I probably missed something above. This sounds like it's a lot of work, but maybe it won't be so bad. It should be straightforward to find all of our output (grep for console.). Most--if not all--errors generated from Mocha go through lib/errors.js, so those will also be fairly easy to find (grep for /create.+?Error/ should do it).

Anyway, happy to hear thoughts or have a discussion here. If there's some tool that has particularly nice output that you like, please share!