Skip to content

Commit 8c67781

Browse files
authored
Comments around hanging tests via runAsync. (flutter#60136)
1 parent cfc0082 commit 8c67781

File tree

2 files changed

+14
-2
lines changed

2 files changed

+14
-2
lines changed

packages/flutter_test/lib/src/binding.dart

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -362,7 +362,7 @@ abstract class TestWidgetsFlutterBinding extends BindingBase
362362
///
363363
/// If `callback` completes with an error, the error will be caught by the
364364
/// Flutter framework and made available via [takeException], and this method
365-
/// will return a future that completes will `null`.
365+
/// will return a future that completes with `null`.
366366
///
367367
/// Re-entrant calls to this method are not allowed; callers of this method
368368
/// are required to wait for the returned future to complete before calling

packages/flutter_test/lib/src/widget_tester.dart

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -603,12 +603,24 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker
603603
///
604604
/// If [callback] completes with an error, the error will be caught by the
605605
/// Flutter framework and made available via [takeException], and this method
606-
/// will return a future that completes will `null`.
606+
/// will return a future that completes with `null`.
607607
///
608608
/// Re-entrant calls to this method are not allowed; callers of this method
609609
/// are required to wait for the returned future to complete before calling
610610
/// this method again. Attempts to do otherwise will result in a
611611
/// [TestFailure] error being thrown.
612+
///
613+
/// If your widget test hangs and you are using [runAsync], chances are your
614+
/// code depends on the result of a task that did not complete. Fake async
615+
/// environment is unable to resolve a future that was created in [runAsync].
616+
/// If you observe such behavior or flakiness, you have a number of options:
617+
///
618+
/// * Consider restructuring your code so you do not need [runAsync]. This is
619+
/// the optimal solution as widget tests are designed to run in fake async
620+
/// environment.
621+
///
622+
/// * Expose a [Future] in your application code that signals the readiness of
623+
/// your widget tree, then await that future inside [callback].
612624
Future<T> runAsync<T>(
613625
Future<T> callback(), {
614626
Duration additionalTime = const Duration(milliseconds: 1000),

0 commit comments

Comments
 (0)