Repository navigation
Add an example for every checks expectation, and fix the bugs they exposed - #2756
Conversation
…posed
Adds a runnable example under `pkgs/checks/example/` for each of the 79
public members of the expectation extensions in
`pkgs/checks/lib/src/extensions/`, and links each one from its member's
dartdoc with `{@example /example/<source>/<subject>/<member>.dart}`.
Every example is a `package:test` test file with at least one check that
passes and at least one that fails, and the failure that a failing check
produces is recorded verbatim in a comment immediately following it. Members
with a single failing case use one test for both the passing and the failing
check; members with more than one failing case use a test per case, including
for the passing checks. The examples are therefore expected to fail when run
directly, which is how the failure messages stay visible. The two deprecated
members, `IterableChecks.containsInOrder` and
`IterableChecks.pairwiseComparesTo`, are skipped.
Examples are written as tests rather than plain scripts because asynchronous
expectations call `TestHandle.current` and throw `OutsideTestException`
outside a running test. Examples that would otherwise report a stack trace
construct their errors with `Future.error`, `Stream.error`, or
`Error.throwWithStackTrace(..., StackTrace.empty)` so that the recorded output
does not contain machine specific paths.
`test/example_test.dart` checks that the failures each example produces equal
the output recorded in its comments, so the documented failure messages cannot
drift from the real ones. All of the examples are run together in a single
`dart test` invocation with the JSON reporter, which associates each failure
with the suite it came from. Running them one invocation apiece instead costs
about 2.5s each, since every invocation pays the runner startup and spawns a
new `frontend_server` process initialized from
`.dart_tool/test/incremental_kernel.*`; batching them lets the runner compile
all suites incrementally against one live `frontend_server` instance and run
them concurrently, which takes the suite from 3m25s to 9s.
Recording the real output instead of the plausible output exposed five defects
in the failure messages. Each is fixed here, along with its test expectations
and the recorded output of the affected examples.
`MapChecks.isNotEmpty` described the wrong condition. Rejecting an empty map
reported `Which: is not empty`, which repeats the expectation's own wording
instead of saying what was wrong with the value. `IterableChecks.isNotEmpty`
and `StringChecks.isNotEmpty` both correctly say `is empty`. Two existing
tests asserted the incorrect string rather than catching it.
`not` emitted a trailing space. The clause was built as `'is a value that: '`,
while the matching clause for the expectation is `'is not a value that:'` with
no trailing space. Besides being inconsistent, trailing whitespace is stripped
by `dart format`, so the message could not be recorded in an example comment.
`pairwiseMatches` did not indent its nested detail. The `Actual element at
index N:` and `Which:` lines were emitted at the same level as the `does not
have an element at index N that:` line that introduces them, so they read as
unrelated top level clauses instead of as the detail of the element that
failed. `every` already indents the equivalent lines.
`equalsIgnoringWhitespace` reported offsets that did not line up with the
value it displayed. The difference is computed between the two strings after
their whitespace is collapsed, so the reported offset and the caret are
positions in the collapsed value, but the message showed the original value on
the `Actual:` line. For `check('hello wide world')` against `'hello world'`
the message pointed at offset 7, which is a different character in the
original than in the collapsed string. The difference is now reported beneath
a line naming the collapsed value it was computed from, so the offset and
caret can be matched up with the string they refer to.
`isA`, `IterableChecks.any`, `MapChecks.containsKeyThat`, and
`MapChecks.containsValueThat` began their `Which:` clause with a capital
letter, unlike every other rejection in the package. They are now lower case.
The `a int` versus `an int` article bug in the subject label is left alone; it
is already tracked by a TODO in `lib/src/checks.dart`.
TAG=agy
CONV=adddbf0c-f10a-4c66-914a-9f0caa5eeafe
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 |
jonasfj
left a comment
There was a problem hiding this comment.
I skimmed a lot of these examples.
But with the testing in place, it's not even "load bearing" whether or not the examples are perfectly reasonable.
Because we know all the examples will run as Expected: 🚀
| - Fix the failure message for `MapChecks.isNotEmpty` to say that the map | ||
| `is empty`, instead of incorrectly repeating `is not empty`. | ||
| - Fix the failure message for `pairwiseMatches` to indent the nested detail | ||
| about the element that failed, so that it is visibly part of the clause it | ||
| describes. | ||
| - Fix the failure message for `equalsIgnoringWhitespace` to report the value | ||
| with its whitespace collapsed. The reported offset and difference always | ||
| referred to the collapsed value, but the message showed the original, so the | ||
| two did not line up. | ||
| - Use a consistent lower case first word for the `Which:` clause of | ||
| `isA`, `IterableChecks.any`, `MapChecks.containsKeyThat`, and | ||
| `MapChecks.containsValueThat`. | ||
| - Remove a stray trailing space from the failure message for `not`. |
There was a problem hiding this comment.
Wow, this is a really good set of bug fixes just from writing examples!
| test('equalsIgnoringWhitespace', () { | ||
| // This check succeeds. | ||
| check(' hello world ').equalsIgnoringWhitespace('hello world'); | ||
|
|
There was a problem hiding this comment.
| // This check succeeds | |
| check(''' | |
| newlines are whitespace | |
| tabs\ttoo! | |
| ''').equalsIgnoringWhitespace('newlines are whitespace tabs too!'); |
There was a problem hiding this comment.
Added newline and tab characters in the passing example
kevmoo
left a comment
There was a problem hiding this comment.
Nice cleanup and test setup (test/example_test.dart). Left two quick notes on stale inline code snippets directly above the new {@example} directives and one minor typo.
| /// If this expectation succeeds, consumes as many events from the source | ||
| /// stream as are consumed by all the conditions. | ||
| /// | ||
| /// {@example /example/async/stream_queue/in_order.dart} |
There was a problem hiding this comment.
The inline code block a few lines above (lines 296–301) still uses the old closure-based Condition syntax ((s) => s.emits((e) => e.equals(0))), which no longer compiles. Might be worth either updating those lines to .it()..emits(.it()..equals(0)) (so IDE hover, which strips {@example}, shows valid code) or removing the inline snippet in favor of {@example}.
There was a problem hiding this comment.
Dropped extra inline code sample from the doc, the example should be sufficient.
| /// | ||
| /// Values, will be compared with the equality operator. | ||
| /// | ||
| /// {@example /example/iterable/iterable/contains_equal_in_order.dart} |
There was a problem hiding this comment.
Similarly, the inline code block right above this (line 225) calls the deprecated .containsInOrder([1, 2, 3]) instead of .containsEqualInOrder([1, 2, 3]).
There was a problem hiding this comment.
Dropped extra inline code block.
Adds a runnable example under `pkgs/matcher/example/` for each of the 93
public matchers and expect layer helpers, and links each one from its member's
dartdoc with `{@example /example/<group>/<member>.dart}`. This mirrors the
examples added for `package:checks` in #2756.
Every example is a `package:test` test file with at least one expectation that
passes, and the failure that a failing expectation produces is recorded
verbatim in a comment immediately following it. Members with a single failing
case use one test for both the passing and the failing expectation; members
with more than one failing case use a test per case. The examples are
therefore expected to fail when run directly, which is how the failure
messages stay visible. The exception is `anything`, which matches every value
and so has no failing case; its example shows the placeholder use it is
actually for. Deprecated members are skipped.
`test/example_test.dart` checks that the failures each example produces equal
the output recorded in its comments, so the documented failure messages cannot
drift from the real ones. All of the examples are run together in a single
`dart test` invocation with the JSON reporter, which associates each failure
with the suite it came from, and the whole suite takes about nine seconds.
Unlike the `package:checks` messages, not every matcher failure begins with
`Expected:`. `fail`, `neverCalled` and the future matchers report a bare
message. A recorded failure is therefore identified by its position - the run
of comment lines that ends a test body - rather than by its first line.
The examples for the `throws` matchers demonstrate the failure where the
function returns instead of throwing. The failure for a function that throws
the wrong type embeds a stack trace whose line numbers refer to the example
itself, so recording it would invalidate the recording on every edit. That
message also contains a whitespace only line, which `dart format` strips from
a comment and which therefore cannot be recorded at all.
Recorded output cannot be reflowed, and some messages are longer than 80
characters at the indentation a test body requires, so `example/` carries an
analysis options file that turns off `lines_longer_than_80_chars` for the
examples only. The rest of the package keeps the rule. The repository root
already disables it, but `pkgs/matcher/analysis_options.yaml` includes
`dart_flutter_team_lints` directly rather than the root options, so the rule is
on for this package.
Writing the examples also surfaced that the documentation for
`stringContainsInOrder` was separated from its declaration by a blank line, so
it was a plain comment rather than a doc comment and did not appear in the
generated documentation. The blank line is removed.
Where a doc comment already carried a hand written code block that the new
example now covers, the block is removed and the surrounding prose is kept:
`predicate`, `CustomMatcher`, `neverCalled`, `equalsIgnoringWhitespace`,
`throwsA`, `isA` and `TypeMatcher.having`. Unlike these snippets, the examples
are compiled and run, and several of the snippets had drifted - the
`CustomMatcher` one referenced a `Widget` type that does not exist. Where a
snippet said something the example did not, the example was extended first:
`example/type/having.dart` now also covers `having` on a top level `isX`
matcher, `example/throws/throws_a.dart` covers the future and the function
returning a future forms, `example/string/equals_ignoring_whitespace.dart`
covers leading and trailing whitespace and a missing space,
`example/core/predicate.dart` passes an explicit type argument, and
`example/string/string_contains_in_order.dart` uses non adjacent substrings so
that it demonstrates ordering rather than concatenation.
TAG=agy
CONV=adddbf0c-f10a-4c66-914a-9f0caa5eeafe
Adds a runnable example under `pkgs/matcher/example/` for each of the 93
public matchers and expect layer helpers, and links each one from its member's
dartdoc with `{@example /example/<group>/<member>.dart}`. This mirrors the
examples added for `package:checks` in #2756.
Every example is a `package:test` test file with at least one expectation that
passes, and the failure that a failing expectation produces is recorded
verbatim in a comment immediately following it. Members with a single failing
case use one test for both the passing and the failing expectation; members
with more than one failing case use a test per case. The examples are
therefore expected to fail when run directly, which is how the failure
messages stay visible. The exception is `anything`, which matches every value
and so has no failing case; its example shows the placeholder use it is
actually for. Deprecated members are skipped.
`test/example_test.dart` checks that the failures each example produces equal
the output recorded in its comments, so the documented failure messages cannot
drift from the real ones. All of the examples are run together in a single
`dart test` invocation with the JSON reporter, which associates each failure
with the suite it came from, and the whole suite takes about nine seconds.
Unlike the `package:checks` messages, not every matcher failure begins with
`Expected:`. `fail`, `neverCalled` and the future matchers report a bare
message. A recorded failure is therefore identified by its position - the run
of comment lines that ends a test body - rather than by its first line.
The examples for the `throws` matchers demonstrate the failure where the
function returns instead of throwing. The failure for a function that throws
the wrong type embeds a stack trace whose line numbers refer to the example
itself, so recording it would invalidate the recording on every edit. That
message also contains a whitespace only line, which `dart format` strips from
a comment and which therefore cannot be recorded at all.
Recorded output cannot be reflowed, and some messages are longer than 80
characters at the indentation a test body requires, so `example/` carries an
analysis options file that turns off `lines_longer_than_80_chars` for the
examples only. The rest of the package keeps the rule. The repository root
already disables it, but `pkgs/matcher/analysis_options.yaml` includes
`dart_flutter_team_lints` directly rather than the root options, so the rule is
on for this package.
Writing the examples also surfaced that the documentation for
`stringContainsInOrder` was separated from its declaration by a blank line, so
it was a plain comment rather than a doc comment and did not appear in the
generated documentation. The blank line is removed.
Where a doc comment already carried a hand written code block that the new
example now covers, the block is removed and the surrounding prose is kept:
`predicate`, `CustomMatcher`, `neverCalled`, `equalsIgnoringWhitespace`,
`throwsA`, `isA` and `TypeMatcher.having`. Unlike these snippets, the examples
are compiled and run, and several of the snippets had drifted - the
`CustomMatcher` one referenced a `Widget` type that does not exist. Where a
snippet said something the example did not, the example was extended first:
`example/type/having.dart` now also covers `having` on a top level `isX`
matcher, `example/throws/throws_a.dart` covers the future and the function
returning a future forms, `example/string/equals_ignoring_whitespace.dart`
covers leading and trailing whitespace, tabs and newlines, and a missing space,
`example/core/predicate.dart` passes an explicit type argument, and
`example/string/string_contains_in_order.dart` uses non adjacent substrings so
that it demonstrates ordering rather than concatenation.
TAG=agy
CONV=adddbf0c-f10a-4c66-914a-9f0caa5eeafe
Adds a runnable example under `pkgs/matcher/example/` for each of the 93
public matchers and expect layer helpers, and links each one from its member's
dartdoc with `{@example /example/<group>/<member>.dart}`. This mirrors the
examples added for `package:checks` in #2756.
Every example is a `package:test` test file with at least one expectation that
passes, and the failure that a failing expectation produces is recorded
verbatim in a comment immediately following it. Members with a single failing
case use one test for both the passing and the failing expectation; members
with more than one failing case use a test per case. The examples are
therefore expected to fail when run directly, which is how the failure
messages stay visible. The exception is `anything`, which matches every value
and so has no failing case; its example shows the placeholder use it is
actually for. Deprecated members are skipped.
`test/example_test.dart` checks that the failures each example produces equal
the output recorded in its comments, so the documented failure messages cannot
drift from the real ones. All of the examples are run together in a single
`dart test` invocation with the JSON reporter, which associates each failure
with the suite it came from, and the whole suite takes about nine seconds.
Unlike the `package:checks` messages, not every matcher failure begins with
`Expected:`. `fail`, `neverCalled` and the future matchers report a bare
message. A recorded failure is therefore identified by its position - the run
of comment lines that ends a test body - rather than by its first line.
The examples for the `throws` matchers demonstrate the failure where the
function returns instead of throwing. The failure for a function that throws
the wrong type embeds a stack trace whose line numbers refer to the example
itself, so recording it would invalidate the recording on every edit. That
message also contains a whitespace only line, which `dart format` strips from
a comment and which therefore cannot be recorded at all.
Recorded output cannot be reflowed, and some messages are longer than 80
characters at the indentation a test body requires, so `example/` carries an
analysis options file that turns off `lines_longer_than_80_chars` for the
examples only. The rest of the package keeps the rule. The repository root
already disables it, but `pkgs/matcher/analysis_options.yaml` includes
`dart_flutter_team_lints` directly rather than the root options, so the rule is
on for this package.
Writing the examples also surfaced that the documentation for
`stringContainsInOrder` was separated from its declaration by a blank line, so
it was a plain comment rather than a doc comment and did not appear in the
generated documentation. The blank line is removed.
Revisions updated by `dart tools/rev_sdk_deps.dart`. dartdoc (https://github.com/dart-lang/dartdoc/compare/df2f2cd..c68debc): c68debcb Mon Sep 21 11:07:33 2026 +0200 Sarah Zakarias Adapt the {@example} code fence to the example content (dart-lang/dartdoc#4285) ecosystem (https://github.com/dart-lang/ecosystem/compare/1bdafd8..16dca7a): 16dca7a Mon Sep 21 08:04:10 2026 -0700 Kevin Moore fix(firehose): keep dart_apitool crash details in logs and sanitize breaking table row (dart-lang/ecosystem#461) http (https://github.com/dart-lang/http/compare/35769ba..d8e8e9c): d8e8e9c Mon Sep 21 18:26:27 2026 +0900 DubaiChewyCookie fix(http2): bound peer-controlled streams and headers (dart-lang/http#1958) 286037b Thu Sep 17 17:12:02 2026 -0700 Brian Quinlan chore(http2): prepare to release 3.1.0 (dart-lang/http#1987) a067c94 Wed Sep 16 15:57:52 2026 -0700 Brian Quinlan fix(cupertino_http): possible URLRequest memory leaks (dart-lang/http#1989) 0d15438 Thu Sep 17 00:43:43 2026 +0300 Ellet chore(ok_http): Built-in Kotlin and resolve AGP 9 warnings (dart-lang/http#1973) native (https://github.com/dart-lang/native/compare/a88aaaf..f628b26): f628b26f0 Mon Sep 21 23:21:05 2026 +0200 Daco Harkes [hooks] Add unit tests for `ProtocolExtension` defaults and `build`/`link` error paths (dart-lang/native#3668) 474a93f39 Mon Sep 21 08:01:13 2026 +0500 Muhammad Anas Naveed [jni][jnigen] Update Groovy Gradle property assignments (dart-lang/native#3678) 4434b7f3c Mon Sep 21 10:31:09 2026 +1000 Liam Appelbe [jni] Ignore coverage of generated files (dart-lang/native#3665) b66dfdeae Mon Sep 21 10:27:27 2026 +1000 Liam Appelbe [objective_c] Use `objc_retainAutoreleasedReturnValue` (dart-lang/native#3664) 541121b4b Fri Sep 18 17:30:03 2026 +0200 Daco Harkes [record_use] Add status and coverage badges to `README.md` (dart-lang/native#3675) b97663824 Fri Sep 18 17:25:10 2026 +0200 Daco Harkes [hooks] Prepare `prebuilt_assets_example` v0.1.2 for release (dart-lang/native#3672) 876145f0c Fri Sep 18 15:23:34 2026 +0200 Daco Harkes [hooks] Use `prebuilt/` instead of `assets/` in `prebuilt_assets_example` (dart-lang/native#3671) 73bd0b7b3 Fri Sep 18 12:58:36 2026 +0200 Daco Harkes [hooks] Prepare `prebuilt_assets_example` v0.1.1 for release (dart-lang/native#3669) 4e0f1983f Fri Sep 18 11:40:30 2026 +0200 Daco Harkes [hooks] Add example for bundling prebuilt assets in `pub publish` (dart-lang/native#3637) 22d7cf8da Fri Sep 18 09:28:25 2026 +0200 Daco Harkes [native_test_helpers] Add unit tests for `yamlToJson` and `findPackageRoot` (dart-lang/native#3662) 74e631a8b Fri Sep 18 09:28:25 2026 +0200 Daco Harkes [hooks] Add unit tests for `link` API and `MetadataAsset` (dart-lang/native#3661) 3428cb968 Fri Sep 18 09:28:24 2026 +0200 Daco Harkes [data_assets] Add unit tests for `LinkOutput` data asset extensions (dart-lang/native#3660) 0e4eea612 Fri Sep 18 09:28:24 2026 +0200 Daco Harkes [code_assets] Add unit tests for `testCodeBuildHook` and `CCompilerConfig` (dart-lang/native#3659) dc44c5383 Fri Sep 18 09:28:24 2026 +0200 Daco Harkes [ffi] Add unit tests for `Arena` error handling and `malloc.free` (dart-lang/native#3658) 1e1e2fb8a Fri Sep 18 09:28:23 2026 +0200 Daco Harkes [native_toolchain_c] Default `linkerOptions` in `CLinker.run` and add `CLibrary` tests (dart-lang/native#3657) f3c066006 Fri Sep 18 09:28:23 2026 +0200 Daco Harkes [data_assets] [hooks] [hooks_runner] [record_use] Add coverage ignore comments for debug methods (dart-lang/native#3656) 59cd44422 Fri Sep 18 09:28:22 2026 +0200 Daco Harkes [infra] Clean coverage directory and enable `--check-ignore` in `tool/ci.dart` (dart-lang/native#3655) b859d5fa8 Fri Sep 18 09:35:46 2026 +0500 Muhammad Anas Naveed [ffigen] Default compiler options for C++ (dart-lang/native#3645) eb6ea1e56 Thu Sep 17 09:28:38 2026 +1000 Liam Appelbe [ffigen][jnigen] More docs (dart-lang/native#3649) da786131c Thu Sep 17 09:06:20 2026 +1000 Liam Appelbe [ffigen][jnigen] YAML migration skills (dart-lang/native#3648) fc0491997 Wed Sep 16 15:37:19 2026 -0700 Brian Quinlan [objective_c] don't use autorelease for `toNSDate` (dart-lang/native#3650) f7f9a4556 Wed Sep 16 17:32:47 2026 +0200 Daco Harkes [code_assets] [hooks_runner] [native_toolchain_c] Prepare for release (dart-lang/native#3642) 1c60c437c Wed Sep 16 13:40:31 2026 +0200 Daco Harkes [hooks_runner] Restore non-breaking `KernelAssetPath.toJson` and add `toJsonForTarget` (dart-lang/native#3643) 7667162b3 Wed Sep 16 11:46:18 2026 +0200 Daco Harkes [infra] Use `dependency_validator` in `tool/ci.dart` (dart-lang/native#3646) f6d153d01 Tue Sep 15 19:32:08 2026 -0700 Brian Quinlan [objective_c] Fix potential leaks in converts (dart-lang/native#3647) cb2c62331 Wed Sep 16 11:32:42 2026 +1000 Liam Appelbe [ffigen] Remove YAML from readmes (dart-lang/native#3633) 22e835728 Wed Sep 16 09:49:02 2026 +1000 Liam Appelbe [jnigen] Remove yaml from readme (dart-lang/native#3634) eb444eee2 Wed Sep 16 09:48:04 2026 +1000 Liam Appelbe [infra] Add and fix `unawaited_futures` and `discarded_futures` lints (dart-lang/native#3639) 0f419f0d2 Wed Sep 16 09:47:44 2026 +1000 Liam Appelbe [infra] Switch from coveralls to codecov (dart-lang/native#3626) shelf (https://github.com/dart-lang/shelf/compare/f36dd68..e5c8dc6): e5c8dc6 Tue Sep 15 18:15:41 2026 -0700 Kevin Moore fix(shelf_static): ignore suffix ranges selecting zero bytes (dart-lang/shelf#541) test (https://github.com/dart-lang/test/compare/c80d53d..9946c95): 9946c955 Mon Sep 21 12:31:54 2026 -0700 Nate Bosch Fix a race in the frontend server client fake (dart-lang/test#2762) 48c3fdf6 Fri Sep 18 18:52:52 2026 -0700 Nate Bosch Fix race conditions during test load (dart-lang/test#2761) 5d74864b Fri Sep 18 16:25:57 2026 -0700 Nate Bosch Remove mentions of Travis (dart-lang/test#2760) 5c4d9b25 Fri Sep 18 12:49:00 2026 -0700 Nate Bosch Use consistent *Checks naming for prints (dart-lang/test#2759) f927df26 Fri Sep 18 12:15:49 2026 -0700 Kevin Moore feat(checks): add prints expectations (`#2742`) (dart-lang/test#2743) 347a5af2 Fri Sep 18 12:09:15 2026 -0700 Nate Bosch Add an example for every matcher (dart-lang/test#2757) 6358dbb3 Thu Sep 17 15:10:08 2026 -0700 Nate Bosch Add an example for every checks expectation, and fix the bugs they exposed (dart-lang/test#2756) 88202adc Thu Sep 17 14:13:30 2026 +0200 Sigurd Meldgaard New flag --shard-by-suite tools (https://github.com/dart-lang/tools/compare/1b0c3bb..3614ce0): 3614ce06 Fri Sep 18 10:07:20 2026 -0700 Kevin Moore chore(unified_analytics): remove dart:mirrors usage in test/event_test.dart (dart-lang/tools#2602) 7550ce13 Fri Sep 18 07:56:44 2026 -0700 Kevin Moore chore(markdown): remove dart:mirrors usage in tool/stats_lib.dart (dart-lang/tools#2600) [email protected] Change-Id: Ide262779269adab780d314d80c9f82b97a79391f Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/552741 Commit-Queue: Nate Bosch <[email protected]> Reviewed-by: Brian Quinlan <[email protected]>
Adds a runnable example under
pkgs/checks/example/for each of the 79public members of the expectation extensions in
pkgs/checks/lib/src/extensions/, and links each one from its member'sdartdoc with
{@example /example/<source>/<subject>/<member>.dart}.Every example is a
package:testtest file with at least one check thatpasses and at least one that fails, and the failure that a failing check
produces is recorded verbatim in a comment immediately following it. Members
with a single failing case use one test for both the passing and the failing
check; members with more than one failing case use a test per case, including
for the passing checks. The examples are therefore expected to fail when run
directly, which is how the failure messages stay visible. The two deprecated
members,
IterableChecks.containsInOrderandIterableChecks.pairwiseComparesTo, are skipped.Examples are written as tests rather than plain scripts because asynchronous
expectations call
TestHandle.currentand throwOutsideTestExceptionoutside a running test. Examples that would otherwise report a stack trace
construct their errors with
Future.error,Stream.error, orError.throwWithStackTrace(..., StackTrace.empty)so that the recorded outputdoes not contain machine specific paths.
test/example_test.dartchecks that the failures each example produces equalthe output recorded in its comments, so the documented failure messages cannot
drift from the real ones. All of the examples are run together in a single
dart testinvocation with the JSON reporter, which associates each failurewith the suite it came from. Running them one invocation apiece instead costs
about 2.5s each, since every invocation pays the runner startup and spawns a
new
frontend_serverprocess initialized from.dart_tool/test/incremental_kernel.*; batching them lets the runner compileall suites incrementally against one live
frontend_serverinstance and runthem concurrently, which takes the suite from 3m25s to 9s.
Recording the real output instead of the plausible output exposed five defects
in the failure messages. Each is fixed here, along with its test expectations
and the recorded output of the affected examples.
MapChecks.isNotEmptydescribed the wrong condition. Rejecting an empty mapreported
Which: is not empty, which repeats the expectation's own wordinginstead of saying what was wrong with the value.
IterableChecks.isNotEmptyand
StringChecks.isNotEmptyboth correctly sayis empty. Two existingtests asserted the incorrect string rather than catching it.
notemitted a trailing space. The clause was built as'is a value that: ',while the matching clause for the expectation is
'is not a value that:'withno trailing space. Besides being inconsistent, trailing whitespace is stripped
by
dart format, so the message could not be recorded in an example comment.pairwiseMatchesdid not indent its nested detail. TheActual element at index N:andWhich:lines were emitted at the same level as thedoes not have an element at index N that:line that introduces them, so they read asunrelated top level clauses instead of as the detail of the element that
failed.
everyalready indents the equivalent lines.equalsIgnoringWhitespacereported offsets that did not line up with thevalue it displayed. The difference is computed between the two strings after
their whitespace is collapsed, so the reported offset and the caret are
positions in the collapsed value, but the message showed the original value on
the
Actual:line. Forcheck('hello wide world')against'hello world'the message pointed at offset 7, which is a different character in the
original than in the collapsed string. The difference is now reported beneath
a line naming the collapsed value it was computed from, so the offset and
caret can be matched up with the string they refer to.
isA,IterableChecks.any,MapChecks.containsKeyThat, andMapChecks.containsValueThatbegan theirWhich:clause with a capitalletter, unlike every other rejection in the package. They are now lower case.
The
a intversusan intarticle bug in the subject label is left alone; itis already tracked by a TODO in
lib/src/checks.dart.TAG=agy
CONV=adddbf0c-f10a-4c66-914a-9f0caa5eeafe