Add support for collapsed error messages#2651
Draft
natebosch wants to merge 1 commit into
Draft
Conversation
PR HealthChangelog Entry ✔️
Changes to files need to be accounted for in their respective changelogs. This check can be disabled by tagging the PR with |
dccf79c to
ccbd58e
Compare
Checks against a subject are commonly nested against some other subject,
for example the check for an exact list length is in practice an
`equals` expectation checked against an integer which is the "has
length" subject, nested under the subject holding the list instance.
Failure messages have a rigid structure that represents this nesting
pattern and always indent the "clauses" (the descriptions of what was
checked in expectations) following the "label" which describes subject.
For very simple conditions the noise of the structure is greater than
the signal of the description output by the specific failing
expectation. For instance a trivial check for an future completing to an
expected value looks like:
```
Expected: a Future<List<int>> that:
completes to a value that:
is not empty
Actual: a Future<List<int>> that:
completes to a value that:
Actual: []
Which: is empty
```
Add support for collapsing this to.
```
Expected: a Future<List<int>> that completes to a non-empty iterable
Actual: a Future<List<int>> that completes to []
Which: is empty
```
Add a `predicateNoun` callback argument to `expect`, `expectAsync`, and
`expectUnawaited`. Extensions must pass a callback which provides the
"clause" representation like "is empty". Now they may also pass a
callback which provides a predicate noun formed by combining the
clause with a noun for the subject like "an empty iterable".
Add a `addPredicate` callback argument to `nest`, and `nestAsync`.
Extensions must pass a callback which provides a label for the value
they are deriving from the original subject like "completes to a value".
Now they may also pass a callback which takes a collapsed form of the
noun as described by nested conditions, and attaches the predicate it
contributes.
Check for possibilities to collapse failure messages down to predicate
nouns when generating failure messages.
Add predicate noun callbacks to existing extensions where sensible.
Tweak some wording where I noticed inconsistencies.
Use of these new arguments is completely optional for extension
implementations and impacts only the failure message formatting which is
not considered a breaking change.
The user impact is that many simple expectation failures will be more
compact and readable, but the position of the failing expectation in
a series of cascaded expectations may cause a significantly different
output for the same checks usage. It has always been the case that
expectations which follow a failure have no impact on the output,
because they are never reached to run. Now when the first expectation in
a series has a collapsible representation it's failure triggers an
overall collapsed format which will read differently to the expanded
format if any condition other than the first fails.
ccbd58e to
bd2f609
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Checks against a subject are commonly nested against some other subject,
for example the check for an exact list length is in practice an
equalsexpectation checked against an integer which is the "haslength" subject, nested under the subject holding the list instance.
Failure messages have a rigid structure that represents this nesting
pattern and always indent the "clauses" (the descriptions of what was
checked in expectations) following the "label" which describes subject.
For very simple conditions the noise of the structure is greater than
the signal of the description output by the specific failing
expectation. For instance a trivial check for an future completing to an
expected value looks like:
Add support for collapsing this to.
Add a
predicateNouncallback argument toexpect,expectAsync, andexpectUnawaited. Extensions must pass a callback which provides the"clause" representation like "is empty". Now they may also pass a
callback which provides a predicate noun formed by combining the
clause with a noun for the subject like "an empty iterable".
Add a
addPredicatecallback argument tonest, andnestAsync.Extensions must pass a callback which provides a label for the value
they are deriving from the original subject like "completes to a value".
Now they may also pass a callback which takes a collapsed form of the
noun as described by nested conditions, and attaches the predicate it
contributes.
Check for possibilities to collapse failure messages down to predicate
nouns when generating failure messages.
Add predicate noun callbacks to existing extensions where sensible.
Tweak some wording where I noticed inconsistencies.
Use of these new arguments is completely optional for extension
implementations and impacts only the failure message formatting which is
not considered a breaking change.
The user impact is that many simple expectation failures will be more
compact and readable, but the position of the failing expectation in
a series of cascaded expectations may cause a significantly different
output for the same checks usage. It has always been the case that
expectations which follow a failure have no impact on the output,
because they are never reached to run. Now when the first expectation in
a series has a collapsible representation it's failure triggers an
overall collapsed format which will read differently to the expanded
format if any condition other than the first fails.