Use case

It is important for app accessibility that semantic elements are ordered in a logical way¹. At present, there does not seem to be a way to verify SemanticsNode ordering. matchesSemantics has a children argument which seems like it might solve this problem, but I can find no documentation on this parameter and have not been able to use it in any meaningful way on the button counter app generated by flutter create.

Proposal

There are multiple ways this might be accomplished. One (originally proposed by @goderbauer) is to add an isOrderedBefore matcher that could be used like:

expect(find.byKey(question), isOrderedBefore(find.byKey(answer))

Another option would allow the developer to specify multiple matchers. If we wanted to verify the order of the semantic elements in the default flutter create app, it might look something like:

await tester.pumpWidget(const MyApp());
expect(
  tester.getSemantics(find.byType(MyHomePage)),
  hasSemanticsElements([
    SemanticsElement(label: 'Flutter Demo Home Page'),
    SemanticsElement(label: 'You have pushed the button this many times:'),
    SemanticsElement(label: '0'),
    SemanticsElement(label: 'Increment'),
  ]),
);

There are some open questions here, including:

1. What type does isOrderedBefore/hasSemanticsElements expect? I'm intentionally being somewhat handwavy about the SemanticsElement type. I'm not sure if it makes sense to have a full semantics matcher here (see the next point).
2. Should we allow for full semantics matching or just ordering? Allowing full semantics matching would be richer, but would also be a lot more verbose and would be mixing responsibilities (validating element order vs validating properties on the elements). Addressing Allow matchesSemantics to only match certain properties #107859 might make this less of an issue.