cucumber / cucumber/messages

Add Exception.cause to schema

Open
#302 5 comments 0 reactions 0 assignees View on GitHub
Dominant language
C#
Stars
41
Forks
24
Avg merge
2d 4h
Merged PRs (30d)
6

Description

## Problem

We recently-ish added the [Exception](https://github.com/cucumber/messages/blob/main/jsonschema/Exception.json) 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](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/Exception.html#%3Cinit%3E(java.lang.String,java.lang.Throwable)) and [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause).

Formatters should ideally be able to surface structured nested exceptions - users don't want to [lose that important information](https://github.com/cucumber/cucumber-js/issues/2515), 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.

Contributor guide

Open the contributing guide

Research direction

Start with jsonschema/Exception.json and inspect how recursive or optional fields are represented in the schema. Confirm the proposed optional cause field refers to another Exception and check the repository's schema validation or generation process; done means the schema accepts nested exceptions without breaking existing consumers.

Written by the indexing model from the issue text.

Assessment

Tech stack
json
Domain
api
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
50/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.