Add support for asynchronous assertions through logging

[Avaq]

The idea

Tests can use channel (value) to produce additional output besides the return value of the expression:

> ( stdout (1)
. , setTimeout (stdout, 1, 2)
. , stderr (3)
. , 4 )
[stdout]: 1
[stderr]: 3
4
[stdout]: 2

Doctest asserts that all output channels produce their output in the expected order, on the expected channel. In the above example, we even assert that [stdout]: 2 was produced asynchronously (after undefined was returned from the expression).

The philosophy is that the code example will contain exactly that which the Node REPL would when run with:

node -i -e 'const channel = x => console.log (`[channel]:`, x)'

TODO

• Finish the run function
• Add logging capabilities to CommonJS
• Add logging capabilities to CoffeeScript
• Document the new feature in the README
• Try this out in Sanctuary to see if compatibility was preserved
• Try this out in Fluture to see if the solution works as intended

Feedback

• Add support for asynchronous assertions through logging #118 (comment) Track output location per unique output
• Add support for asynchronous assertions through logging #118 (comment) Instead of a single logger function taking the channel name as an argument, use multiple logging functions each corresponding to a channel
• Add support for asynchronous assertions through logging #118 (comment) Figure out what to do about the breaking change

Tests

• Logging in all three types of code
• Synchronous logging with and without function output and exception
• Asynchronous logging with and without function output and exception
• Failing due to not enough output
• Failing due to too much output
• Failing due to incorrectly ordered output
• Failing due to incorrect output channel
• Failing due to timing out
• Failing because the --log-function option was not given

[davidchambers]

I think this is our first use of arrow functions. Should we also use () => {} in place of function() {} a few lines above?

[Avaq]

Oh. Perhaps I should use a regular function.

[Avaq]

This if statement actually describes another state in our state machine implicitly. It would not have to be there if we had two separate states for logging: SYNC_LOG and ASYNC_LOG. While the state machine is in SYNC_LOG, it allows transitions to the OUTPUT state, but while it's in ASYNC_LOG it only allows transitions to itself or CLOSED.

It might be nicer to implement it like that.

[Avaq]

The valid state transitions would then be something like:

CLOSED -> CLOSED
CLOSED -> OPEN

OPEN -> INPUT

INPUT -> INPUT
INPUT -> MORE_INPUT
INPUT -> SYNC_LOG
INPUT -> OUTPUT
INPUT -> ASYNC_LOG
INPUT -> CLOSED

MORE_INPUT -> MORE_INPUT
MORE_INPUT -> SYNC_LOG
MORE_INPUT -> OUTPUT
MORE_INPUT -> ASYNC_LOG
MORE_INPUT -> CLOSED

SYNC_LOG -> SYNC_LOG
SYNC_LOG -> MORE_SYNC_LOG
SYNC_LOG -> OUTPUT
SYNC_LOG -> ASYNC_LOG
SYNC_LOG -> INPUT
SYNC_LOG -> CLOSED

MORE_SYNC_LOG -> SYNC_LOG
MORE_SYNC_LOG -> MORE_SYNC_LOG
MORE_SYNC_LOG -> OUTPUT
MORE_SYNC_LOG -> ASYNC_LOG
MORE_SYNC_LOG -> INPUT
MORE_SYNC_LOG -> CLOSED

OUTPUT -> MORE_OUTPUT
OUTPUT -> ASYNC_LOG
OUTPUT -> INPUT
OUTPUT -> CLOSED

MORE_OUTPUT -> MORE_OUTPUT
MORE_OUTPUT -> ASYNC_LOG
MORE_OUTPUT -> INPUT
MORE_OUTPUT -> CLOSED

ASYNC_LOG -> ASYNC_LOG
ASYNC_LOG -> MORE_ASYNC_LOG
ASYNC_LOG -> INPUT
ASYNC_LOG -> CLOSED

MORE_ASYNC_LOG -> ASYNC_LOG
MORE_ASYNC_LOG -> MORE_ASYNC_LOG
MORE_ASYNC_LOG -> INPUT
MORE_ASYNC_LOG -> CLOSED

[Avaq]

That is technically a breaking change.

I just took a shower and regained my sanity. The now blindingly obvious solution is to parse only the words provided on the CLI. It solves the "how should our regex be" issue, and regains our backwards compat: No --log-function arg means no log output parsing.