Skip to content

fix description for semantics finders#181214

Merged
auto-submit[bot] merged 1 commit intoflutter:masterfrom
navaronbracke:semanticslabel_matcher
Jan 22, 2026
Merged

fix description for semantics finders#181214
auto-submit[bot] merged 1 commit intoflutter:masterfrom
navaronbracke:semanticslabel_matcher

Conversation

@navaronbracke
Copy link
Contributor

@navaronbracke navaronbracke commented Jan 20, 2026

Fixes #181196

This PR fixes the description for the bySemanticsLabel/Identifier matchers, which was missing.

Note: The framework uses byElementPredicate() in a bunch of places in tests, but not all use the description field.
Should we add descriptions to those?

Example:

import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
  testWidgets('bySemanticsLabel', (tester) async {
    await tester.pumpWidget(const MaterialApp(home: Text('hello')));
    await tester.pumpAndSettle();
    expect(find.bySemanticsLabel('goodbye'), findsOneWidget);
  });

  testWidgets('bySemanticsLabel regex', (tester) async {
    await tester.pumpWidget(const MaterialApp(home: Text('hello')));
    await tester.pumpAndSettle();
    expect(find.bySemanticsLabel(RegExp('^foo')), findsOneWidget);
  });

  testWidgets('bySemanticsIdentifier', (tester) async {
    await tester.pumpWidget(const MaterialApp(home: Text('hello')));
    await tester.pumpAndSettle();
    expect(find.bySemanticsIdentifier('goodbye'), findsOneWidget);
  });

  testWidgets('bySemanticsIdentifier regex', (tester) async {
    await tester.pumpWidget(const MaterialApp(home: Text('hello')));
    await tester.pumpAndSettle();
    expect(find.bySemanticsIdentifier(RegExp('^foo')), findsOneWidget);
  });
}

now gives:

══╡ EXCEPTION CAUGHT BY FLUTTER TEST FRAMEWORK ╞════════════════════════════════════════════════════
The following TestFailure was thrown running a test:
Expected: exactly one matching candidate
  Actual: _ElementPredicateWidgetFinder:<Found 0 widgets with a semantics label named "goodbye": []>
   Which: means none were found but one was expected

When the exception was thrown, this was the stack:
#4      main.<anonymous closure> (file:///Users/navaronbracke/Desktop/matchers_test/test/widget_test.dart:8:5)
<asynchronous suspension>
#5      testWidgets.<anonymous closure>.<anonymous closure> (package:flutter_test/src/widget_tester.dart:192:15)
<asynchronous suspension>
#6      TestWidgetsFlutterBinding._runTestBody (package:flutter_test/src/binding.dart:1692:5)
<asynchronous suspension>
<asynchronous suspension>
(elided one frame from package:stack_trace)

This was caught by the test expectation on the following line:
  file:///Users/navaronbracke/Desktop/matchers_test/test/widget_test.dart line 8
The test description was:
  bySemanticsLabel
════════════════════════════════════════════════════════════════════════════════════════════════════
══╡ EXCEPTION CAUGHT BY FLUTTER TEST FRAMEWORK ╞════════════════════════════════════════════════════
The following TestFailure was thrown running a test:
Expected: exactly one matching candidate
  Actual: _ElementPredicateWidgetFinder:<Found 0 widgets with a semantics label matching the pattern
"^foo": []>
   Which: means none were found but one was expected

When the exception was thrown, this was the stack:
#4      main.<anonymous closure> (file:///Users/navaronbracke/Desktop/matchers_test/test/widget_test.dart:14:5)
<asynchronous suspension>
#5      testWidgets.<anonymous closure>.<anonymous closure> (package:flutter_test/src/widget_tester.dart:192:15)
<asynchronous suspension>
#6      TestWidgetsFlutterBinding._runTestBody (package:flutter_test/src/binding.dart:1692:5)
<asynchronous suspension>
<asynchronous suspension>
(elided one frame from package:stack_trace)

This was caught by the test expectation on the following line:
  file:///Users/navaronbracke/Desktop/matchers_test/test/widget_test.dart line 14
The test description was:
  bySemanticsLabel regex
════════════════════════════════════════════════════════════════════════════════════════════════════
══╡ EXCEPTION CAUGHT BY FLUTTER TEST FRAMEWORK ╞════════════════════════════════════════════════════
The following TestFailure was thrown running a test:
Expected: exactly one matching candidate
  Actual: _ElementPredicateWidgetFinder:<Found 0 widgets with a semantics identifier named
"goodbye": []>
   Which: means none were found but one was expected

When the exception was thrown, this was the stack:
#4      main.<anonymous closure> (file:///Users/navaronbracke/Desktop/matchers_test/test/widget_test.dart:20:5)
<asynchronous suspension>
#5      testWidgets.<anonymous closure>.<anonymous closure> (package:flutter_test/src/widget_tester.dart:192:15)
<asynchronous suspension>
#6      TestWidgetsFlutterBinding._runTestBody (package:flutter_test/src/binding.dart:1692:5)
<asynchronous suspension>
<asynchronous suspension>
(elided one frame from package:stack_trace)

This was caught by the test expectation on the following line:
  file:///Users/navaronbracke/Desktop/matchers_test/test/widget_test.dart line 20
The test description was:
  bySemanticsIdentifier
════════════════════════════════════════════════════════════════════════════════════════════════════
══╡ EXCEPTION CAUGHT BY FLUTTER TEST FRAMEWORK ╞════════════════════════════════════════════════════
The following TestFailure was thrown running a test:
Expected: exactly one matching candidate
  Actual: _ElementPredicateWidgetFinder:<Found 0 widgets with a semantics identifier matching the
pattern "^foo": []>
   Which: means none were found but one was expected

When the exception was thrown, this was the stack:
#4      main.<anonymous closure> (file:///Users/navaronbracke/Desktop/matchers_test/test/widget_test.dart:26:5)
<asynchronous suspension>
#5      testWidgets.<anonymous closure>.<anonymous closure> (package:flutter_test/src/widget_tester.dart:192:15)
<asynchronous suspension>
#6      TestWidgetsFlutterBinding._runTestBody (package:flutter_test/src/binding.dart:1692:5)
<asynchronous suspension>
<asynchronous suspension>
(elided one frame from package:stack_trace)

This was caught by the test expectation on the following line:
  file:///Users/navaronbracke/Desktop/matchers_test/test/widget_test.dart line 26
The test description was:
  bySemanticsIdentifier regex
════════════════════════════════════════════════════════════════════════════════════════════════════

If you had to change anything in the flutter/tests repo, include a link to the migration guide as per the breaking change policy.

Pre-launch Checklist

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

@github-actions github-actions bot added a: tests "flutter test", flutter_test, or one of our tests framework flutter/packages/flutter repository. See also f: labels. labels Jan 20, 2026
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

The pull request effectively addresses the issue of uninformative error messages for bySemanticsLabel and bySemanticsIdentifier matchers. By introducing descriptive strings based on the provided Pattern (String or RegExp), the error output is significantly improved, enhancing the debugging experience. The changes are well-implemented, and the added tests thoroughly validate the new behavior. The code is clear, concise, and directly solves the problem without introducing new complexities.

'Actual: _ElementPredicateWidgetFinder:<Found 0 widgets with a semantics label matching the pattern "^item-"',
),
);
});
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we also need to test the default case?

Copy link
Contributor Author

@navaronbracke navaronbracke Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also was thinking about this earlier.
Since _bySemanticsProperty() is private and only used by bySemanticsLabel() and bySemanticsIdentifier() and there are no other usages of the private method, I think we are good here?

The public API for the semantics finders only allows String and RegExp, but not arbitrary Patterns,
hence why I omitted the test.

@victorsanni victorsanni requested a review from chunhtai January 21, 2026 02:31
Copy link
Contributor

@chunhtai chunhtai left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@chunhtai chunhtai added the autosubmit Merge PR when tree becomes green via auto submit App label Jan 21, 2026
@auto-submit auto-submit bot added this pull request to the merge queue Jan 21, 2026
Merged via the queue into flutter:master with commit b4a2349 Jan 22, 2026
70 checks passed
@flutter-dashboard flutter-dashboard bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jan 22, 2026
@navaronbracke navaronbracke deleted the semanticslabel_matcher branch January 22, 2026 07:33
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jan 22, 2026
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jan 22, 2026
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jan 22, 2026
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jan 23, 2026
auto-submit bot pushed a commit to flutter/packages that referenced this pull request Jan 23, 2026
Roll Flutter from 48c2475 to bfc9041eb118 (173 revisions)

flutter/flutter@48c2475...bfc9041

2026-01-23 [email protected] No longer exiting the application when the RegularWindow is destroyed + resolving the window created promise after runWidget (flutter/flutter#181339)
2026-01-23 [email protected] Remove unnecessary Material import from dialog_test.dart (flutter/flutter#181249)
2026-01-23 [email protected] Roll Skia from 8e516fe6828f to db10db8bd55f (1 revision) (flutter/flutter#181379)
2026-01-23 [email protected] Reset TextFormField to initial value after state change (flutter/flutter#181199)
2026-01-23 [email protected] Roll Dart SDK from 980b2b41d36e to e82d7ad1855e (1 revision) (flutter/flutter#181375)
2026-01-23 [email protected] Roll Skia from 3e86f377d300 to 8e516fe6828f (4 revisions) (flutter/flutter#181370)
2026-01-23 [email protected] Remove unnecessary Material import from sliver_visibility_test (flutter/flutter#181248)
2026-01-23 [email protected] Add bottom navigation bar item semantics label (flutter/flutter#180577)
2026-01-23 [email protected] Make topGap not required for CupertinoSheetTransition (flutter/flutter#181269)
2026-01-23 [email protected] Roll Fuchsia Linux SDK from b4cLyhuxciUC-4zCJ... to n7NohL9DPpEuPjNt9... (flutter/flutter#181365)
2026-01-23 [email protected] Roll Dart SDK from 806f04638561 to 980b2b41d36e (1 revision) (flutter/flutter#181364)
2026-01-23 [email protected] Reland hybrid views test (flutter/flutter#181336)
2026-01-23 [email protected] Revert DropdownMenu non-nullable breaking change (flutter/flutter#181074)
2026-01-23 [email protected] Fix leaks in `flutter_test` tests (flutter/flutter#180879)
2026-01-23 [email protected] Re-enable fragment_shader_tests.dart 'Shader Compiler appropriately pads vec3 uniform arrays' test on Vulkan (flutter/flutter#181292)
2026-01-23 [email protected] [ Tool ] Fix `update-packages` failing due to mismatched dependencies between flutter_tools and the framework (flutter/flutter#181335)
2026-01-23 [email protected] [Impeller] Make dynamically created shader metadata for runtime effects consistent with metadata for built-in shaders (flutter/flutter#181201)
2026-01-23 [email protected] Broaden the applicability of `Color` fix_data rules from flutter/painting.dart (flutter/flutter#181093)
2026-01-23 [email protected] Fixes macOS App.framework not being codesigned or find framework (flutter/flutter#181348)
2026-01-22 [email protected] Roll Fuchsia GN SDK from NAEC5tfgSl8g94nwp... to JLBh4Z9PKsjIJcqDU... (flutter/flutter#181139)
2026-01-22 [email protected] Roll Dart SDK from ab4640ea82e9 to 806f04638561 (2 revisions) (flutter/flutter#181347)
2026-01-22 [email protected] Add ExpansibleController.toggle method. (flutter/flutter#181320)
2026-01-22 [email protected] Fixes Typo in codebase (flutter/flutter#181256)
2026-01-22 [email protected] Roll Skia from 4766615bcc96 to 3e86f377d300 (3 revisions) (flutter/flutter#181346)
2026-01-22 [email protected] Make sure that a Hero doesn't crash in 0x0 environment (flutter/flutter#180954)
2026-01-22 [email protected] Reland "Fix capitalization of the path to FlutterWindowControllerTest.mm in the macOS platform build script" (flutter/flutter#181200)
2026-01-22 [email protected] Roll Skia from 6e9746be8c4a to 4766615bcc96 (3 revisions) (flutter/flutter#181331)
2026-01-22 [email protected] Fix remove material import textfield (flutter/flutter#181254)
2026-01-22 [email protected] Add FlutterFramework as an Xcode SwiftPM local package override (flutter/flutter#179512)
2026-01-22 [email protected] Roll Dart SDK from 7bd4c68b625c to ab4640ea82e9 (1 revision) (flutter/flutter#181324)
2026-01-22 [email protected] Roll Packages from d80c60e to 9010299 (9 revisions) (flutter/flutter#181323)
2026-01-22 [email protected] Roll Dart SDK from 2d53a77adc5d to 7bd4c68b625c (2 revisions) (flutter/flutter#181316)
2026-01-22 [email protected] Roll Skia from 3f6949bc5780 to 6e9746be8c4a (2 revisions) (flutter/flutter#181311)
2026-01-22 [email protected] Roll Skia from ef6efc358b4a to 3f6949bc5780 (2 revisions) (flutter/flutter#181307)
2026-01-22 [email protected] Roll Dart SDK from 5d7c8faf2e41 to 2d53a77adc5d (1 revision) (flutter/flutter#181305)
2026-01-22 [email protected] [Material] update hourFormat to use Dart 3 switch expression (flutter/flutter#181041)
2026-01-22 [email protected] Use null-aware elements in cupertino/nav_bar.dart (flutter/flutter#181237)
2026-01-22 [email protected] Roll Fuchsia Linux SDK from b2KIEXVAlEqImQ9VO... to b4cLyhuxciUC-4zCJ... (flutter/flutter#181297)
2026-01-22 [email protected] Roll pub packages (flutter/flutter#181295)
2026-01-22 [email protected] Enables fragment shader test for impeller (fixes mat2 on vulkan) (flutter/flutter#181013)
2026-01-21 [email protected] Roll Dart SDK from 366200db1aa1 to 5d7c8faf2e41 (4 revisions) (flutter/flutter#181290)
2026-01-21 [email protected] Roll Skia from b5ec89e31f59 to ef6efc358b4a (19 revisions) (flutter/flutter#181289)
2026-01-21 [email protected] fix description for semantics finders (flutter/flutter#181214)
2026-01-21 [email protected] Make sure that an Icon doesn't crash in 0x0 environment (flutter/flutter#181021)
2026-01-21 [email protected] Make sure that a GridPaper doesn't crash in 0x0 environment (flutter/flutter#180906)
2026-01-21 [email protected] Bring Linux coverage out of bringup (flutter/flutter#181280)
...
flutter-zl pushed a commit to flutter-zl/flutter that referenced this pull request Feb 10, 2026
Fixes flutter#181196

This PR fixes the description for the bySemanticsLabel/Identifier
matchers, which was missing.

Note: The framework uses `byElementPredicate()` in a bunch of places in
tests, but not all use the `description` field.
Should we add descriptions to those?

Example:

```dart
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
  testWidgets('bySemanticsLabel', (tester) async {
    await tester.pumpWidget(const MaterialApp(home: Text('hello')));
    await tester.pumpAndSettle();
    expect(find.bySemanticsLabel('goodbye'), findsOneWidget);
  });

  testWidgets('bySemanticsLabel regex', (tester) async {
    await tester.pumpWidget(const MaterialApp(home: Text('hello')));
    await tester.pumpAndSettle();
    expect(find.bySemanticsLabel(RegExp('^foo')), findsOneWidget);
  });

  testWidgets('bySemanticsIdentifier', (tester) async {
    await tester.pumpWidget(const MaterialApp(home: Text('hello')));
    await tester.pumpAndSettle();
    expect(find.bySemanticsIdentifier('goodbye'), findsOneWidget);
  });

  testWidgets('bySemanticsIdentifier regex', (tester) async {
    await tester.pumpWidget(const MaterialApp(home: Text('hello')));
    await tester.pumpAndSettle();
    expect(find.bySemanticsIdentifier(RegExp('^foo')), findsOneWidget);
  });
}
```

now gives:

```dart
══╡ EXCEPTION CAUGHT BY FLUTTER TEST FRAMEWORK ╞════════════════════════════════════════════════════
The following TestFailure was thrown running a test:
Expected: exactly one matching candidate
  Actual: _ElementPredicateWidgetFinder:<Found 0 widgets with a semantics label named "goodbye": []>
   Which: means none were found but one was expected

When the exception was thrown, this was the stack:
flutter#4      main.<anonymous closure> (file:///Users/navaronbracke/Desktop/matchers_test/test/widget_test.dart:8:5)
<asynchronous suspension>
flutter#5      testWidgets.<anonymous closure>.<anonymous closure> (package:flutter_test/src/widget_tester.dart:192:15)
<asynchronous suspension>
flutter#6      TestWidgetsFlutterBinding._runTestBody (package:flutter_test/src/binding.dart:1692:5)
<asynchronous suspension>
<asynchronous suspension>
(elided one frame from package:stack_trace)

This was caught by the test expectation on the following line:
  file:///Users/navaronbracke/Desktop/matchers_test/test/widget_test.dart line 8
The test description was:
  bySemanticsLabel
════════════════════════════════════════════════════════════════════════════════════════════════════
══╡ EXCEPTION CAUGHT BY FLUTTER TEST FRAMEWORK ╞════════════════════════════════════════════════════
The following TestFailure was thrown running a test:
Expected: exactly one matching candidate
  Actual: _ElementPredicateWidgetFinder:<Found 0 widgets with a semantics label matching the pattern
"^foo": []>
   Which: means none were found but one was expected

When the exception was thrown, this was the stack:
flutter#4      main.<anonymous closure> (file:///Users/navaronbracke/Desktop/matchers_test/test/widget_test.dart:14:5)
<asynchronous suspension>
flutter#5      testWidgets.<anonymous closure>.<anonymous closure> (package:flutter_test/src/widget_tester.dart:192:15)
<asynchronous suspension>
flutter#6      TestWidgetsFlutterBinding._runTestBody (package:flutter_test/src/binding.dart:1692:5)
<asynchronous suspension>
<asynchronous suspension>
(elided one frame from package:stack_trace)

This was caught by the test expectation on the following line:
  file:///Users/navaronbracke/Desktop/matchers_test/test/widget_test.dart line 14
The test description was:
  bySemanticsLabel regex
════════════════════════════════════════════════════════════════════════════════════════════════════
══╡ EXCEPTION CAUGHT BY FLUTTER TEST FRAMEWORK ╞════════════════════════════════════════════════════
The following TestFailure was thrown running a test:
Expected: exactly one matching candidate
  Actual: _ElementPredicateWidgetFinder:<Found 0 widgets with a semantics identifier named
"goodbye": []>
   Which: means none were found but one was expected

When the exception was thrown, this was the stack:
flutter#4      main.<anonymous closure> (file:///Users/navaronbracke/Desktop/matchers_test/test/widget_test.dart:20:5)
<asynchronous suspension>
flutter#5      testWidgets.<anonymous closure>.<anonymous closure> (package:flutter_test/src/widget_tester.dart:192:15)
<asynchronous suspension>
flutter#6      TestWidgetsFlutterBinding._runTestBody (package:flutter_test/src/binding.dart:1692:5)
<asynchronous suspension>
<asynchronous suspension>
(elided one frame from package:stack_trace)

This was caught by the test expectation on the following line:
  file:///Users/navaronbracke/Desktop/matchers_test/test/widget_test.dart line 20
The test description was:
  bySemanticsIdentifier
════════════════════════════════════════════════════════════════════════════════════════════════════
══╡ EXCEPTION CAUGHT BY FLUTTER TEST FRAMEWORK ╞════════════════════════════════════════════════════
The following TestFailure was thrown running a test:
Expected: exactly one matching candidate
  Actual: _ElementPredicateWidgetFinder:<Found 0 widgets with a semantics identifier matching the
pattern "^foo": []>
   Which: means none were found but one was expected

When the exception was thrown, this was the stack:
flutter#4      main.<anonymous closure> (file:///Users/navaronbracke/Desktop/matchers_test/test/widget_test.dart:26:5)
<asynchronous suspension>
flutter#5      testWidgets.<anonymous closure>.<anonymous closure> (package:flutter_test/src/widget_tester.dart:192:15)
<asynchronous suspension>
flutter#6      TestWidgetsFlutterBinding._runTestBody (package:flutter_test/src/binding.dart:1692:5)
<asynchronous suspension>
<asynchronous suspension>
(elided one frame from package:stack_trace)

This was caught by the test expectation on the following line:
  file:///Users/navaronbracke/Desktop/matchers_test/test/widget_test.dart line 26
The test description was:
  bySemanticsIdentifier regex
════════════════════════════════════════════════════════════════════════════════════════════════════

```

*If you had to change anything in the [flutter/tests] repo, include a
link to the migration guide as per the [breaking change policy].*

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [ ] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

**Note**: The Flutter team is currently trialing the use of [Gemini Code
Assist for
GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code).
Comments from the `gemini-code-assist` bot should not be taken as
authoritative feedback from the Flutter team. If you find its comments
useful you can update your code accordingly, but if you are unsure or
disagree with the feedback, please feel free to wait for a Flutter team
member's review for guidance on which automated comments should be
addressed.

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

a: tests "flutter test", flutter_test, or one of our tests framework flutter/packages/flutter repository. See also f: labels.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Flutter test's bySemanticsLabel() finder has unhelpful description

3 participants