Add find.backButton finder and StandardComponentType enum to find components in tests. (#149349)

## Description

This adds `find.backButton()` in the Common Finders to allow finding different types of standard UI elements. It works by attaching a key made from an enum value in a new enum called `StandardComponentType` to all of the standard widgets that perform the associated function.

I also substituted the finder in several places where it is useful in tests.

This allows writing tests that want to find the "back" button without having to know exactly which icon the back button uses under what circumstances.  To do it correctly is actually quite complicated, since there are several adaptations that occur (based on platform, and whether it is web or not).

## Tests
 - Added tests.

Author: gspencergoog

dev/integration_tests/new_gallery/lib/studies/fortnightly/shared.dart

@@ -305,6 +305,7 @@ class NavigationMenu extends StatelessWidget {
           Row(
             children: <Widget>[
               IconButton(
+                key: StandardComponentType.closeButton.key,
                 icon: const Icon(Icons.close),
                 tooltip: MaterialLocalizations.of(context).closeButtonTooltip,
                 onPressed: () => Navigator.pop(context),

packages/flutter/lib/src/cupertino/nav_bar.dart

@@ -1669,7 +1669,10 @@ class _BackChevron extends StatelessWidget {
         break;
     }
 
-    return iconWidget;
+    return KeyedSubtree(
+      key: StandardComponentType.backButton.key,
+      child: iconWidget,
+    );
   }
 }
 

packages/flutter/lib/src/material/action_buttons.dart

@@ -28,6 +28,7 @@ abstract class _ActionButton extends StatelessWidget {
     this.color,
     required this.icon,
     required this.onPressed,
+    this.standardComponent,
     this.style,
   });
 
@@ -56,6 +57,10 @@ abstract class _ActionButton extends StatelessWidget {
   /// Null by default.
   final ButtonStyle? style;
 
+  /// An enum value to use to identify this button as a type of
+  /// [StandardComponentType].
+  final StandardComponentType? standardComponent;
+
   /// This returns the appropriate tooltip text for this action button.
   String _getTooltip(BuildContext context);
 
@@ -67,6 +72,7 @@ abstract class _ActionButton extends StatelessWidget {
   Widget build(BuildContext context) {
     assert(debugCheckHasMaterialLocalizations(context));
     return IconButton(
+      key: standardComponent?.key,
       icon: icon,
       style: style,
       color: color,
@@ -212,7 +218,10 @@ class BackButton extends _ActionButton {
     super.color,
     super.style,
     super.onPressed,
-  }) : super(icon: const BackButtonIcon());
+  }) : super(
+    icon: const BackButtonIcon(),
+    standardComponent: StandardComponentType.backButton,
+  );
 
   @override
   void _onPressedCallback(BuildContext context) => Navigator.maybePop(context);
@@ -281,7 +290,10 @@ class CloseButtonIcon extends StatelessWidget {
 class CloseButton extends _ActionButton {
   /// Creates a Material Design close icon button.
   const CloseButton({ super.key, super.color, super.onPressed, super.style })
-      : super(icon: const CloseButtonIcon());
+      : super(
+          icon: const CloseButtonIcon(),
+          standardComponent: StandardComponentType.closeButton,
+        );
 
   @override
   void _onPressedCallback(BuildContext context) => Navigator.maybePop(context);
@@ -347,7 +359,10 @@ class DrawerButton extends _ActionButton {
     super.color,
     super.style,
     super.onPressed,
-  }) : super(icon: const DrawerButtonIcon());
+  }) : super(
+        icon: const DrawerButtonIcon(),
+        standardComponent: StandardComponentType.drawerButton,
+      );
 
   @override
   void _onPressedCallback(BuildContext context) => Scaffold.of(context).openDrawer();

packages/flutter/lib/src/material/popup_menu.dart

@@ -1548,6 +1548,7 @@ class PopupMenuButtonState<T> extends State<PopupMenuButton<T>> {
     }
 
     return IconButton(
+      key: StandardComponentType.moreButton.key,
       icon: widget.icon ?? Icon(Icons.adaptive.more),
       padding: widget.padding,
       splashRadius: widget.splashRadius,

packages/flutter/lib/src/material/search_anchor.dart

@@ -8,6 +8,7 @@ import 'dart:ui';
 
 import 'package:flutter/widgets.dart';
 
+import 'back_button.dart';
 import 'button_style.dart';
 import 'color_scheme.dart';
 import 'colors.dart';
@@ -865,11 +866,9 @@ class _ViewContentState extends State<_ViewContent> {
 
   @override
   Widget build(BuildContext context) {
-    final Widget defaultLeading = IconButton(
-      icon: const Icon(Icons.arrow_back),
-      tooltip: MaterialLocalizations.of(context).backButtonTooltip,
-      onPressed: () { Navigator.of(context).pop(); },
+    final Widget defaultLeading = BackButton(
       style: const ButtonStyle(tapTargetSize: MaterialTapTargetSize.shrinkWrap),
+      onPressed: () { Navigator.of(context).pop(); },
     );
 
     final List<Widget> defaultTrailing = <Widget>[

packages/flutter/lib/src/material/snack_bar.dart

@@ -678,6 +678,7 @@ class _SnackBarState extends State<SnackBar> {
 
     final IconButton? iconButton = showCloseIcon
         ? IconButton(
+            key: StandardComponentType.closeButton.key,
             icon: const Icon(Icons.close),
             iconSize: 24.0,
             color: widget.closeIconColor ?? snackBarTheme.closeIconColor ?? defaults.closeIconColor,

packages/flutter/lib/src/material/text_selection_toolbar.dart

@@ -220,6 +220,7 @@ class _TextSelectionToolbarOverflowableState extends State<_TextSelectionToolbar
             // The navButton that shows and hides the overflow menu is the
             // first child.
             _TextSelectionToolbarOverflowButton(
+              key: _overflowOpen ? StandardComponentType.backButton.key : StandardComponentType.moreButton.key,
               icon: Icon(_overflowOpen ? Icons.arrow_back : Icons.more_vert),
               onPressed: () {
                 setState(() {
@@ -731,6 +732,7 @@ class _TextSelectionToolbarContainer extends StatelessWidget {
 // forward and back controls.
 class _TextSelectionToolbarOverflowButton extends StatelessWidget {
   const _TextSelectionToolbarOverflowButton({
+    super.key,
     required this.icon,
     this.onPressed,
     this.tooltip,

packages/flutter/lib/src/widgets/standard_component_type.dart

@@ -0,0 +1,54 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/foundation.dart';
+
+/// An enum identifying standard UI components.
+///
+/// This enum is used to attach a key to a widget identifying it as a standard
+/// UI component for testing and discovery purposes.
+///
+/// It is used by the testing infrastructure (e.g. the `find` object in the
+/// Flutter test framework) to positively identify and/or activate specific
+/// widgets as representing standard UI components, since many of these
+/// components vary slightly in the icons or tooltips that they use, and making
+/// an effective test matcher for them is fragile and error prone.
+///
+/// The keys don't have any effect on the functioning of the UI elements, they
+/// are just a means of identifying them. A widget won't be treated specially if
+/// it has this key, other than to be found by the testing infrastructure. If
+/// tests are not searching for them, then adding them to a widget serves no
+/// purpose.
+///
+/// Any widget with the [key] from a value here applied to it will be considered
+/// to be that type of standard UI component in tests.
+///
+/// Types included here are generally only those for which it can be difficult
+/// or fragile to create a reliable test matcher for. It is not (nor should it
+/// become) an exhaustive list of standard UI components.
+///
+/// These are typically used in tests via `find.backButton()` or
+/// `find.closeButton()`.
+enum StandardComponentType {
+  /// Indicates the associated widget is a standard back button, typically used
+  /// to navigate back to the previous screen.
+  backButton,
+
+  /// Indicates the associated widget is a close button, typically used to
+  /// dismiss a dialog or modal sheet.
+  closeButton,
+
+  /// Indicates the associated widget is a "more" button, typically used to
+  /// display a menu of additional options.
+  moreButton,
+
+  /// Indicates the associated widget is a drawer button, typically used to open
+  /// a drawer.
+  drawerButton;
+
+  /// Returns a [ValueKey] for this [StandardComponentType].
+  ///
+  /// Attach this key to a widget to indicate it is a standard UI component.
+  ValueKey<StandardComponentType> get key => ValueKey<StandardComponentType>(this);
+}

packages/flutter/lib/widgets.dart

@@ -145,6 +145,7 @@ export 'src/widgets/slotted_render_object_widget.dart';
 export 'src/widgets/snapshot_widget.dart';
 export 'src/widgets/spacer.dart';
 export 'src/widgets/spell_check.dart';
+export 'src/widgets/standard_component_type.dart';
 export 'src/widgets/status_transitions.dart';
 export 'src/widgets/system_context_menu.dart';
 export 'src/widgets/table.dart';

packages/flutter/test/cupertino/nav_bar_transition_test.dart

@@ -463,7 +463,7 @@ void main() {
     expect(
       flying(
         tester,
-        find.byWidgetPredicate((Widget widget) => widget.key != null),
+        find.byWidgetPredicate((Widget widget) => widget.key != null && widget.key is GlobalKey),
       ),
       findsNothing,
     );