Add Exception.cause to schema

[davidjgoss]

Problem

We recently-ish added the Exception object so that messages like test step failures can express an exception in a structured way.

One pattern this doesn't allow for is nested exceptions. It's fairly common for an exception to wrap another exception, and is standardised as "cause" in at least Java and JavaScript.

Formatters should ideally be able to surface structured nested exceptions - users don't want to lose that important information, or have to parse it out of a big stack trace. Since formatters should now be implemented in terms of messages, that means adding it to the schema.

Proposal

Add an optional cause field to the Exception object, the value of which is another Exception. This should be a non-breaking change for consumers.

Considerations

The obvious concern here is circularity. Implementers should be urged to avoid this in a similar way to the JSON.stringify algorithm, where on seeing the same exception a second time in the same tree we set it to null and break. We should also consider a limit on the level of nesting e.g. 10 as a hard circuit breaker.

[mpkorstanje]

This is a fractal of complexity.

• Java for example also has suppressed exceptions. Exceptions that were in the process of being handled when another exception was thrown.
• The string representation of the Java stacktrace already includes the message, cause and any suppressed exceptions.
• A lot of Java projects use AssertionFailedError which contains an actual and expected value. People might want to access these too. And there might be other dedicated exceptions too.

So we'll never obtain parity with an actual programming language.

A few options:

1. Render the cause as part of the stacktrace in JS. This at-least provides complete information.
2. Update messages to include the actual exception instead of the serialized representation and write the serialized representation only when serializing to json. This means some information will be lost on serialization, but in process consumers will have full access to the exception.
3. Take the pragmatic approach and include things like actual and expected based on actual demand.

[mpkorstanje]

Looking at cucumber/cucumber-js#2515 I think that rendering the cause as part of the stacktrace in JS is the best solution. It matches, what happens in Java and the only "need" seems to be to have a complete stacktrace.

So I think that instead of providing the stackframes, it would make sense to provide the complete stacktrace, including any causes, supressed exceptions, ect. With that in mind, I think it would also make sense to duplicate the <exception.type>: <exception.message> at the start of the exception.stacktrace.

[davidjgoss]

Yeah, on reflection this is the right move. Happy to close this.

[mpkorstanje]

Cheers. I'll write up a replacement issue. There are some complications from #317 that need to be done together.

[mpkorstanje]

I'll close when that's done.