fix #19175 How should addTime be used from a test? (#25202)

examples/flutter_gallery/test/accessibility_test.dart

@@ -488,8 +488,7 @@ void main() {
       final String themeName = themeNames[themeIndex];
 
       testWidgets('backdrop_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: BackdropDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -497,8 +496,7 @@ void main() {
       });
 
       testWidgets('bottom_app_bar_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: BottomAppBarDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -506,8 +504,7 @@ void main() {
       });
 
       testWidgets('bottom_navigation_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: BottomNavigationDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -515,8 +512,7 @@ void main() {
       });
 
       testWidgets('buttons_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: ButtonsDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -524,8 +520,7 @@ void main() {
       });
 
       testWidgets('cards_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: CardsDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -533,8 +528,7 @@ void main() {
       });
 
       testWidgets('chip_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: ChipDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -542,8 +536,7 @@ void main() {
       }, skip: true); // https://github.com/flutter/flutter/issues/21647
 
       testWidgets('data_table_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: DataTableDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -551,8 +544,7 @@ void main() {
       }, skip: true); // https://github.com/flutter/flutter/issues/21647
 
       testWidgets('date_and_time_picker_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: DateAndTimePickerDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -560,8 +552,7 @@ void main() {
       }, skip: true); // https://github.com/flutter/flutter/issues/21647
 
       testWidgets('dialog_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: DialogDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -569,8 +560,7 @@ void main() {
       });
 
       testWidgets('drawer_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: DrawerDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -578,8 +568,7 @@ void main() {
       });
 
       testWidgets('elevation_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: ElevationDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -587,8 +576,7 @@ void main() {
       });
 
       testWidgets('expansion_panels_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: ExpansionPanelsDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -596,8 +584,7 @@ void main() {
       });
 
       testWidgets('grid_list_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: const GridListDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -605,8 +592,7 @@ void main() {
       });
 
       testWidgets('icons_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: IconsDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -614,8 +600,7 @@ void main() {
       }, skip: true); // https://github.com/flutter/flutter/issues/21647
 
       testWidgets('leave_behind_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: const LeaveBehindDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -623,8 +608,7 @@ void main() {
       });
 
       testWidgets('list_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: const ListDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -632,8 +616,7 @@ void main() {
       });
 
       testWidgets('menu_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: const MenuDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -641,8 +624,7 @@ void main() {
       });
 
       testWidgets('modal_bottom_sheet_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: ModalBottomSheetDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -650,8 +632,7 @@ void main() {
       });
 
     testWidgets('overscroll_demo', (WidgetTester tester) async {
-      final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-      binding.addTime(const Duration(seconds: 3));
+      tester.binding.addTime(const Duration(seconds: 3));
       final SemanticsHandle handle = tester.ensureSemantics();
       await tester.pumpWidget(const MaterialApp(home: OverscrollDemo()));
       await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -659,8 +640,7 @@ void main() {
     });
 
       testWidgets('page_selector_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: PageSelectorDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -668,8 +648,7 @@ void main() {
       });
 
       testWidgets('persistent_bottom_sheet_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: PersistentBottomSheetDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -677,8 +656,7 @@ void main() {
       });
 
       testWidgets('progress_indicator_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: ProgressIndicatorDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -686,8 +664,7 @@ void main() {
       });
 
       testWidgets('reorderable_list_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: const ReorderableListDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -695,8 +672,7 @@ void main() {
       });
 
       testWidgets('scrollable_tabs_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: ScrollableTabsDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -704,8 +680,7 @@ void main() {
       });
 
       testWidgets('search_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: SearchDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -713,8 +688,7 @@ void main() {
       }, skip: true); // https://github.com/flutter/flutter/issues/21651
 
       testWidgets('selection_controls_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: SelectionControlsDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -722,8 +696,7 @@ void main() {
       });
 
       testWidgets('slider_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: SliderDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -731,8 +704,7 @@ void main() {
       });
 
       testWidgets('snack_bar_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: const SnackBarDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -740,8 +712,7 @@ void main() {
       });
 
       testWidgets('tabs_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: TabsDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -749,8 +720,7 @@ void main() {
       });
 
       testWidgets('tabs_fab_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: TabsFabDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -758,8 +728,7 @@ void main() {
       });
 
       testWidgets('text_form_field_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: const TextFormFieldDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -767,8 +736,7 @@ void main() {
       });
 
       testWidgets('tooltip_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: TooltipDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));
@@ -776,8 +744,7 @@ void main() {
       });
 
       testWidgets('expansion_tile_list_demo $themeName', (WidgetTester tester) async {
-        final AutomatedTestWidgetsFlutterBinding binding = tester.binding;
-        binding.addTime(const Duration(seconds: 3));
+        tester.binding.addTime(const Duration(seconds: 3));
         final SemanticsHandle handle = tester.ensureSemantics();
         await tester.pumpWidget(MaterialApp(theme: theme, home: ExpansionTileListDemo()));
         await expectLater(tester, meetsGuideline(textContrastGuideline));

packages/flutter_test/lib/src/binding.dart

@@ -125,6 +125,11 @@ abstract class TestWidgetsFlutterBinding extends BindingBase
   @protected
   bool get disableShadows => false;
 
+  /// Increase the timeout for the current test by the given duration.
+  void addTime(Duration duration) {
+    // Noop, see [AutomatedTestWidgetsFlutterBinding. addTime] for an actual implementation.
+  }
+
   /// The value to set [debugCheckIntrinsicSizes] to while tests are running.
   ///
   /// This can be used to enable additional checks. For example,
@@ -843,7 +848,7 @@ class AutomatedTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding {
       _timeoutCompleter.completeError(
         TimeoutException(
           'The test exceeded the timeout. It may have hung.\n'
-          'Consider using "addTime" to increase the timeout before expensive operations.',
+          'Consider using "tester.binding.addTime" to increase the timeout before expensive operations.',
           _timeout,
         ),
       );
@@ -873,6 +878,7 @@ class AutomatedTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding {
   ///
   ///  * [defaultTestTimeout], the maximum that the timeout can reach.
   ///    (That timeout is implemented by the test package.)
+  @override
   void addTime(Duration duration) {
     assert(_timeout != null, 'addTime can only be called during a test.');
     _timeout += duration;

packages/flutter_test/lib/src/widget_tester.dart

@@ -49,6 +49,14 @@ typedef WidgetTesterCallback = Future<void> Function(WidgetTester widgetTester);
 ///
 /// The callback can be asynchronous (using `async`/`await` or
 /// using explicit [Future]s).
+/// Tests using the [AutomatedTestWidgetsFlutterBinding]
+/// have a default time out of two seconds,
+/// which is automatically increased for some expensive operations,
+/// and can also be manually increased by calling
+/// [AutomatedTestWidgetsFlutterBinding.addTime].
+/// The maximum that this timeout can reach (automatically or manually increased)
+/// is defined by the timeout property,
+/// which defaults to [TestWidgetsFlutterBinding.defaultTestTimeout].
 ///
 /// This function uses the [test] function in the test package to
 /// register the given callback as a test. The callback, when run,
@@ -56,6 +64,11 @@ typedef WidgetTesterCallback = Future<void> Function(WidgetTester widgetTester);
 /// provides convenient widget [Finder]s for use with the
 /// [WidgetTester].
 ///
+/// See also:
+///
+///  * [AutomatedTestWidgetsFlutterBinding.addTime] to learn more about
+/// timeout and how to manually increase timeouts.
+///
 /// ## Sample code
 ///
 /// ```dart