Move away from TestSemantics and towards fine grained semantics testing #184367

Background

TestSemantics is used to quickly check that dumping a semantics tree produces some exact string. This is easy to set up, but is often a cause of unhelpful failures. For example, you may have made a small change to the widgets returned from a build method only to be greeted by a large wall of text about how the semantics no longer matches.

How to test semantics instead

Instead, find the exact semantics node that is relevant to the given test using tester.semantics.find. Then use isSemantics to verify only the semantics properties that are relevant to your test. Proceed down the semantics tree as far as is relevant using the children parameter of isSemantics with a list of further calls to isSemantics.

Here is an example, or see the example PRs linked below.

expect(
  tester.semantics.find(find.bySemanticsLabel('Alert'))
  isSemantics(
    label: 'Alert',
    role: SemanticsRole.dialog,
    namesRoute: true,
    scopesRoute: true,
    children: <Matcher>[
      isSemantics(
        hasImplicitScrolling: true,
        children: <Matcher>[
          isSemantics(label: 'The title'),
          isSemantics(label: 'The message'),
        ],
      ),
    ],
  ),
);

Migrating

This came up in #183790 (comment), where it was decided that we would duplicate TestSemantics in the new material_ui package instead of exposing it publicly in flutter_test, in order to avoid encouraging other people to use it. We should migrate all usages across flutter/flutter and material_ui to use the recommendation above, and then remove both instances of TestSemantics.

Resources

• Example: [cupertino_ui] Re-enable action_sheet_test.dart packages#12055
• Example: [cupertino_ui] Re-enable dialog_test.dart packages#12057

List of locations to migrate

rg -l TestSemantics