benchmarkLive: a new LiveTestWidgetsFlutterBindingFramePolicy for benchmark on device (#61388)

* add benchmarkLive flag and tests

* update handlePointerEventRecord doc

* using e2e 0.6.1

packages/flutter_test/lib/src/binding.dart

@@ -1264,6 +1264,21 @@ enum LiveTestWidgetsFlutterBindingFramePolicy {
   /// on the [SchedulerBinding.hasScheduledFrame] property to determine when the
   /// application has "settled".
   benchmark,
+
+  /// Ignore any request from pump but respect other requests to schedule a
+  /// frame.
+  ///
+  /// This is used for running the test on a device, where scheduling of new
+  /// frames respects what the engine and the device needed.
+  ///
+  /// Compared to `fullyLive` this policy ignores the frame requests from pump
+  /// of the test code so that the frame scheduling respects the situation of
+  /// that for the real environment, and avoids waiting for the new frame beyond
+  /// the expected time.
+  ///
+  /// Compared to `benchmark` this policy can be used for capturing the
+  /// animation frames requested by the framework.
+  benchmarkLive,
 }
 
 /// A variant of [TestWidgetsFlutterBinding] for executing tests in
@@ -1398,6 +1413,7 @@ class LiveTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding {
     assert(_doDrawThisFrame == null);
     if (_expectingFrame ||
         (framePolicy == LiveTestWidgetsFlutterBindingFramePolicy.fullyLive) ||
+        (framePolicy == LiveTestWidgetsFlutterBindingFramePolicy.benchmarkLive) ||
         (framePolicy == LiveTestWidgetsFlutterBindingFramePolicy.benchmark) ||
         (framePolicy == LiveTestWidgetsFlutterBindingFramePolicy.fadePointers && _viewNeedsPaint)) {
       _doDrawThisFrame = true;
@@ -1489,6 +1505,10 @@ class LiveTestWidgetsFlutterBinding extends TestWidgetsFlutterBinding {
     assert(inTest);
     assert(!_expectingFrame);
     assert(_pendingFrame == null);
+    if (framePolicy == LiveTestWidgetsFlutterBindingFramePolicy.benchmarkLive) {
+      // Ignore all pumps and just wait.
+      return delayed(duration ?? Duration.zero);
+    }
     return TestAsyncUtils.guard<void>(() {
       if (duration != null) {
         Timer(duration, () {

packages/flutter_test/lib/src/controller.dart

@@ -406,9 +406,17 @@ abstract class WidgetController {
   /// The [PointerEventRecord.timeDelay] is used as the time delay of the events
   /// injection relative to the starting point of the method call.
   ///
-  /// Returns a list of the difference between [PointerEventRecord.timeDelay]
-  /// and the real delay time when the [PointerEventRecord.events] are processed.
-  /// The closer these values are to zero the more faithful it is to the
+  /// Returns a list of the difference between the real delay time when the
+  /// [PointerEventRecord.events] are processed and
+  /// [PointerEventRecord.timeDelay].
+  /// - For [AutomatedTestWidgetsFlutterBinding] where the clock is fake, the
+  ///   return value should be exact zeros.
+  /// - For [LiveTestWidgetsFlutterBinding], the values are typically small
+  /// positives, meaning the event happens a little later than the set time,
+  /// but a very small portion may have a tiny negatvie value for about tens of
+  /// microseconds. This is due to the nature of [Future.delayed].
+  ///
+  /// The closer the return values are to zero the more faithful it is to the
   /// `records`.
   ///
   /// See [PointerEventRecord].

packages/flutter_test/lib/src/widget_tester.dart

@@ -480,7 +480,7 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker
         final Duration timeDiff = record.timeDelay - now.difference(startTime);
         if (timeDiff.isNegative) {
           // Flush all past events
-          handleTimeStampDiff.add(timeDiff);
+          handleTimeStampDiff.add(-timeDiff);
           for (final PointerEvent event in record.events) {
             _handlePointerEvent(event, hitTestHistory);
           }
@@ -490,7 +490,7 @@ class WidgetTester extends WidgetController implements HitTestDispatcher, Ticker
           await binding.pump();
           await binding.delayed(timeDiff);
           handleTimeStampDiff.add(
-            record.timeDelay - binding.clock.now().difference(startTime),
+            binding.clock.now().difference(startTime) - record.timeDelay,
           );
           for (final PointerEvent event in record.events) {
             _handlePointerEvent(event, hitTestHistory);