Repository navigation
Add an example for every matcher - #2757
Merged
Merged
Conversation
PR Health |
natebosch
force-pushed
the
matcher-examples
branch
from
September 18, 2026 00:34
f79e467 to
b6f0f25
Compare
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
natebosch
force-pushed
the
matcher-examples
branch
from
September 18, 2026 00:37
b6f0f25 to
b375d41
Compare
natebosch
marked this pull request as ready for review
September 18, 2026 00:38
jonasfj
approved these changes
Sep 18, 2026
copybara-service Bot
pushed a commit
to dart-lang/sdk
that referenced
this pull request
Sep 22, 2026
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]>
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.
Adds a runnable example under
pkgs/matcher/example/for each of the 93public matchers and expect layer helpers, and links each one from its member's
dartdoc with
{@example /example/<group>/<member>.dart}. This mirrors theexamples added for
package:checksin #2756.Every example is a
package:testtest file with at least one expectation thatpasses, 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 valueand so has no failing case; its example shows the placeholder use it is
actually for. Deprecated members are skipped.
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, and the whole suite takes about nine seconds.
Unlike the
package:checksmessages, not every matcher failure begins withExpected:.fail,neverCalledand the future matchers report a baremessage. 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
throwsmatchers demonstrate the failure where thefunction 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 formatstrips froma 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 ananalysis options file that turns off
lines_longer_than_80_charsfor theexamples only. The rest of the package keeps the rule. The repository root
already disables it, but
pkgs/matcher/analysis_options.yamlincludesdart_flutter_team_lintsdirectly rather than the root options, so the rule ison for this package.
Writing the examples also surfaced that the documentation for
stringContainsInOrderwas separated from its declaration by a blank line, soit was a plain comment rather than a doc comment and did not appear in the
generated documentation. The blank line is removed.
TAG=agy
CONV=adddbf0c-f10a-4c66-914a-9f0caa5eeafe