Unverified Commit 87dbfa83 authored by Ming Lyu (CareF)'s avatar Ming Lyu (CareF) Committed by GitHub

Update framePolicy docs (#61773)

parent 39551013
...@@ -1242,17 +1242,40 @@ class AutomatedTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding { ...@@ -1242,17 +1242,40 @@ class AutomatedTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding {
/// frames. /// frames.
/// ///
/// These values are set on the binding's /// These values are set on the binding's
/// [LiveTestWidgetsFlutterBinding.framePolicy] property. The default is /// [LiveTestWidgetsFlutterBinding.framePolicy] property.
/// [fadePointers]. ///
/// {@template flutter.flutter_test.frame_policy}
/// The default is [fadePointers]. Setting this to anything other than
/// [onlyPumps] results in pumping extra frames, which might involve calling
/// builders more, or calling paint callbacks more, etc, and might interfere
/// with the test. If you know that your test won't be affected by this, you can
/// set the policy to [fullyLive] or [benchmarkLive] in that particular file.
///
/// To set a value while still allowing the test file to work as a normal test,
/// add the following code to your test file at the top of your
/// `void main() { }` function, before calls to [testWidgets]:
///
/// ```dart
/// TestWidgetsFlutterBinding binding = TestWidgetsFlutterBinding.ensureInitialized();
/// if (binding is LiveTestWidgetsFlutterBinding) {
/// binding.framePolicy = LiveTestWidgetsFlutterBindingFramePolicy.[thePolicy];
/// }
/// ```
/// {@endtemplate}
enum LiveTestWidgetsFlutterBindingFramePolicy { enum LiveTestWidgetsFlutterBindingFramePolicy {
/// Strictly show only frames that are explicitly pumped. This most closely /// Strictly show only frames that are explicitly pumped.
/// matches the behavior of tests when run under `flutter test`. ///
/// This most closely matches the [AutomatedTestWidgetsFlutterBinding]
/// (the defualt binding for `flutter test`) behavior.
onlyPumps, onlyPumps,
/// Show pumped frames, and additionally schedule and run frames to fade /// Show pumped frames, and additionally schedule and run frames to fade
/// out the pointer crosshairs and other debugging information shown by /// out the pointer crosshairs and other debugging information shown by
/// the binding. /// the binding.
/// ///
/// This will schedule frames when pumped or when there has been some
/// activity with [TestPointer]s.
///
/// This can result in additional frames being pumped beyond those that /// This can result in additional frames being pumped beyond those that
/// the test itself requests, which can cause differences in behavior. /// the test itself requests, which can cause differences in behavior.
fadePointers, fadePointers,
...@@ -1260,6 +1283,9 @@ enum LiveTestWidgetsFlutterBindingFramePolicy { ...@@ -1260,6 +1283,9 @@ enum LiveTestWidgetsFlutterBindingFramePolicy {
/// Show every frame that the framework requests, even if the frames are not /// Show every frame that the framework requests, even if the frames are not
/// explicitly pumped. /// explicitly pumped.
/// ///
/// The major difference between [fullyLive] and [benchmarkLive] is the latter
/// ignores frame requests by [pump].
///
/// This can help with orienting the developer when looking at /// This can help with orienting the developer when looking at
/// heavily-animated situations, and will almost certainly result in /// heavily-animated situations, and will almost certainly result in
/// additional frames being pumped beyond those that the test itself requests, /// additional frames being pumped beyond those that the test itself requests,
...@@ -1274,6 +1300,12 @@ enum LiveTestWidgetsFlutterBindingFramePolicy { ...@@ -1274,6 +1300,12 @@ enum LiveTestWidgetsFlutterBindingFramePolicy {
/// directly to run (either by using [WidgetTester.pumpBenchmark] or invoking /// directly to run (either by using [WidgetTester.pumpBenchmark] or invoking
/// [Window.onBeginFrame] and [Window.onDrawFrame]). /// [Window.onBeginFrame] and [Window.onDrawFrame]).
/// ///
/// This allows all frame requests from the engine to be serviced, and allows
/// all frame requests that are artificially triggered to be serviced, but
/// ignores [scheduleFrame] requests from the framework.
/// Therefore animation won't run for this mode because the framework
/// generates an animation by requesting new frames.
///
/// The [SchedulerBinding.hasScheduledFrame] property will never be true in /// The [SchedulerBinding.hasScheduledFrame] property will never be true in
/// this mode. This can cause unexpected effects. For instance, /// this mode. This can cause unexpected effects. For instance,
/// [WidgetTester.pumpAndSettle] does not function in this mode, as it relies /// [WidgetTester.pumpAndSettle] does not function in this mode, as it relies
...@@ -1287,12 +1319,13 @@ enum LiveTestWidgetsFlutterBindingFramePolicy { ...@@ -1287,12 +1319,13 @@ enum LiveTestWidgetsFlutterBindingFramePolicy {
/// This is used for running the test on a device, where scheduling of new /// This is used for running the test on a device, where scheduling of new
/// frames respects what the engine and the device needed. /// frames respects what the engine and the device needed.
/// ///
/// Compared to `fullyLive` this policy ignores the frame requests from pump /// Compared to [fullyLive] this policy ignores the frame requests from [pump]
/// of the test code so that the frame scheduling respects the situation of /// so that frame scheduling mimics that of the real environment, and avoids
/// that for the real environment, and avoids waiting for the new frame beyond /// waiting for an artificially [pump]ed frame. (For example, when driving the
/// the expected time. /// test in methods like [WidgetTester.handlePointerEventRecord] or
/// [WidgetTester.fling].)
/// ///
/// Compared to `benchmark` this policy can be used for capturing the /// This policy differs from [benchmark] in that it can be used for capturing
/// animation frames requested by the framework. /// animation frames requested by the framework.
benchmarkLive, benchmarkLive,
} }
...@@ -1348,53 +1381,17 @@ class LiveTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding { ...@@ -1348,53 +1381,17 @@ class LiveTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding {
bool _viewNeedsPaint = false; bool _viewNeedsPaint = false;
bool _runningAsyncTasks = false; bool _runningAsyncTasks = false;
/// Whether to have [pump] with a duration only pump a single frame /// The strategy for [pump]ing and requesting new frames.
///
/// The policy decides whether [pump] (with a duration) pumps a single frame
/// (as would happen in a normal test environment using /// (as would happen in a normal test environment using
/// [AutomatedTestWidgetsFlutterBinding]), or whether to instead /// [AutomatedTestWidgetsFlutterBinding]), or pumps every frame that the
/// pump every frame that the system requests during any /// system requests during an asynchronous pause (as would normally happen
/// asynchronous pause in the test (as would normally happen when /// when running an application with [WidgetsFlutterBinding]).
/// running an application with [WidgetsFlutterBinding]). ///
/// /// {@macro flutter.flutter_test.frame_policy}
/// * [LiveTestWidgetsFlutterBindingFramePolicy.fadePointers] is the default ///
/// behavior, which is to only pump once, except when there has been some /// See [LiveTestWidgetsFlutterBindingFramePolicy].
/// activity with [TestPointer]s, in which case those are shown and may pump
/// additional frames.
///
/// * [LiveTestWidgetsFlutterBindingFramePolicy.onlyPumps] is the strictest
/// behavior, which is to only pump once. This most closely matches the
/// [AutomatedTestWidgetsFlutterBinding] (`flutter test`) behavior.
///
/// * [LiveTestWidgetsFlutterBindingFramePolicy.fullyLive] allows all frame
/// requests from the engine to be serviced, even those the test did not
/// explicitly pump.
///
/// * [LiveTestWidgetsFlutterBindingFramePolicy.benchmark] allows all frame
/// requests from the engine to be serviced, and allows all frame requests
/// that are artificially triggered to be serviced, but prevents the
/// framework from requesting any frames from the engine itself. The
/// [SchedulerBinding.hasScheduledFrame] property will never be true in this
/// mode. This can cause unexpected effects. For instance,
/// [WidgetTester.pumpAndSettle] does not function in this mode, as it
/// relies on the [SchedulerBinding.hasScheduledFrame] property to determine
/// when the application has "settled".
///
/// Setting this to anything other than
/// [LiveTestWidgetsFlutterBindingFramePolicy.onlyPumps] means pumping extra
/// frames, which might involve calling builders more, or calling paint
/// callbacks more, etc, which might interfere with the test. If you know your
/// test file wouldn't be affected by this, you can set it to
/// [LiveTestWidgetsFlutterBindingFramePolicy.fullyLive] persistently in that
/// particular test file. To set this to
/// [LiveTestWidgetsFlutterBindingFramePolicy.fullyLive] while still allowing
/// the test file to work as a normal test, add the following code to your
/// test file at the top of your `void main() { }` function, before calls to
/// [testWidgets]:
///
/// ```dart
/// TestWidgetsFlutterBinding binding = TestWidgetsFlutterBinding.ensureInitialized();
/// if (binding is LiveTestWidgetsFlutterBinding)
/// binding.framePolicy = LiveTestWidgetsFlutterBindingFramePolicy.fullyLive;
/// ```
LiveTestWidgetsFlutterBindingFramePolicy framePolicy = LiveTestWidgetsFlutterBindingFramePolicy.fadePointers; LiveTestWidgetsFlutterBindingFramePolicy framePolicy = LiveTestWidgetsFlutterBindingFramePolicy.fadePointers;
@override @override
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment