controller.dart 44.1 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5 6
import 'dart:async';

7
import 'package:clock/clock.dart';
8 9
import 'package:flutter/gestures.dart';
import 'package:flutter/rendering.dart';
10
import 'package:flutter/services.dart';
11 12 13
import 'package:flutter/widgets.dart';

import 'all_elements.dart';
14
import 'event_simulation.dart';
15 16 17
import 'finders.dart';
import 'test_async_utils.dart';
import 'test_pointer.dart';
18

19 20 21 22 23 24
/// The default drag touch slop used to break up a large drag into multiple
/// smaller moves.
///
/// This value must be greater than [kTouchSlop].
const double kDragSlopDefault = 20.0;

25 26
/// Class that programmatically interacts with widgets.
///
27 28 29 30 31 32
/// For a variant of this class suited specifically for unit tests, see
/// [WidgetTester]. For one suitable for live tests on a device, consider
/// [LiveWidgetController].
///
/// Concrete subclasses must implement the [pump] method.
abstract class WidgetController {
33
  /// Creates a widget controller that uses the given binding.
34 35
  WidgetController(this.binding);

36
  /// A reference to the current instance of the binding.
37 38 39 40 41 42 43 44
  final WidgetsBinding binding;

  // FINDER API

  // TODO(ianh): verify that the return values are of type T and throw
  // a good message otherwise, in all the generic methods below

  /// Checks if `finder` exists in the tree.
45 46 47 48
  bool any(Finder finder) {
    TestAsyncUtils.guardSync();
    return finder.evaluate().isNotEmpty;
  }
49 50 51 52 53 54

  /// All widgets currently in the widget tree (lazy pre-order traversal).
  ///
  /// Can contain duplicates, since widgets can be used in multiple
  /// places in the widget tree.
  Iterable<Widget> get allWidgets {
55
    TestAsyncUtils.guardSync();
56
    return allElements.map<Widget>((Element element) => element.widget);
57 58 59 60 61 62
  }

  /// The matching widget in the widget tree.
  ///
  /// Throws a [StateError] if `finder` is empty or matches more than
  /// one widget.
63 64 65
  ///
  /// * Use [firstWidget] if you expect to match several widgets but only want the first.
  /// * Use [widgetList] if you expect to match several widgets and want all of them.
66
  T widget<T extends Widget>(Finder finder) {
67
    TestAsyncUtils.guardSync();
68
    return finder.evaluate().single.widget as T;
69 70 71 72 73 74
  }

  /// The first matching widget according to a depth-first pre-order
  /// traversal of the widget tree.
  ///
  /// Throws a [StateError] if `finder` is empty.
75 76
  ///
  /// * Use [widget] if you only expect to match one widget.
77
  T firstWidget<T extends Widget>(Finder finder) {
78
    TestAsyncUtils.guardSync();
79
    return finder.evaluate().first.widget as T;
80 81
  }

82 83 84 85
  /// The matching widgets in the widget tree.
  ///
  /// * Use [widget] if you only expect to match one widget.
  /// * Use [firstWidget] if you expect to match several but only want the first.
86
  Iterable<T> widgetList<T extends Widget>(Finder finder) {
87
    TestAsyncUtils.guardSync();
88
    return finder.evaluate().map<T>((Element element) {
89
      final T result = element.widget as T;
90 91
      return result;
    });
92 93
  }

94 95 96 97 98 99
  /// All elements currently in the widget tree (lazy pre-order traversal).
  ///
  /// The returned iterable is lazy. It does not walk the entire widget tree
  /// immediately, but rather a chunk at a time as the iteration progresses
  /// using [Iterator.moveNext].
  Iterable<Element> get allElements {
100
    TestAsyncUtils.guardSync();
101
    return collectAllElementsFrom(binding.renderViewElement, skipOffstage: false);
102 103 104 105 106 107
  }

  /// The matching element in the widget tree.
  ///
  /// Throws a [StateError] if `finder` is empty or matches more than
  /// one element.
108 109 110
  ///
  /// * Use [firstElement] if you expect to match several elements but only want the first.
  /// * Use [elementList] if you expect to match several elements and want all of them.
111
  T element<T extends Element>(Finder finder) {
112
    TestAsyncUtils.guardSync();
113
    return finder.evaluate().single as T;
114 115 116 117 118 119
  }

  /// The first matching element according to a depth-first pre-order
  /// traversal of the widget tree.
  ///
  /// Throws a [StateError] if `finder` is empty.
120 121
  ///
  /// * Use [element] if you only expect to match one element.
122
  T firstElement<T extends Element>(Finder finder) {
123
    TestAsyncUtils.guardSync();
124
    return finder.evaluate().first as T;
125 126
  }

127 128 129 130
  /// The matching elements in the widget tree.
  ///
  /// * Use [element] if you only expect to match one element.
  /// * Use [firstElement] if you expect to match several but only want the first.
131
  Iterable<T> elementList<T extends Element>(Finder finder) {
132
    TestAsyncUtils.guardSync();
133
    return finder.evaluate().cast<T>();
134 135
  }

136 137 138 139 140 141
  /// All states currently in the widget tree (lazy pre-order traversal).
  ///
  /// The returned iterable is lazy. It does not walk the entire widget tree
  /// immediately, but rather a chunk at a time as the iteration progresses
  /// using [Iterator.moveNext].
  Iterable<State> get allStates {
142
    TestAsyncUtils.guardSync();
143
    return allElements.whereType<StatefulElement>().map<State>((StatefulElement element) => element.state);
144 145 146 147 148 149
  }

  /// The matching state in the widget tree.
  ///
  /// Throws a [StateError] if `finder` is empty, matches more than
  /// one state, or matches a widget that has no state.
150 151 152
  ///
  /// * Use [firstState] if you expect to match several states but only want the first.
  /// * Use [stateList] if you expect to match several states and want all of them.
153
  T state<T extends State>(Finder finder) {
154
    TestAsyncUtils.guardSync();
155
    return _stateOf<T>(finder.evaluate().single, finder);
156 157 158 159 160 161 162
  }

  /// The first matching state according to a depth-first pre-order
  /// traversal of the widget tree.
  ///
  /// Throws a [StateError] if `finder` is empty or if the first
  /// matching widget has no state.
163 164
  ///
  /// * Use [state] if you only expect to match one state.
165
  T firstState<T extends State>(Finder finder) {
166
    TestAsyncUtils.guardSync();
167
    return _stateOf<T>(finder.evaluate().first, finder);
168 169
  }

170 171 172 173 174 175 176
  /// The matching states in the widget tree.
  ///
  /// Throws a [StateError] if any of the elements in `finder` match a widget
  /// that has no state.
  ///
  /// * Use [state] if you only expect to match one state.
  /// * Use [firstState] if you expect to match several but only want the first.
177
  Iterable<T> stateList<T extends State>(Finder finder) {
178
    TestAsyncUtils.guardSync();
179
    return finder.evaluate().map<T>((Element element) => _stateOf<T>(element, finder));
180 181
  }

182
  T _stateOf<T extends State>(Element element, Finder finder) {
183
    TestAsyncUtils.guardSync();
184
    if (element is StatefulElement)
185
      return element.state as T;
186
    throw StateError('Widget of type ${element.widget.runtimeType}, with ${finder.description}, is not a StatefulWidget.');
187 188 189 190 191 192 193 194 195 196
  }

  /// Render objects of all the widgets currently in the widget tree
  /// (lazy pre-order traversal).
  ///
  /// This will almost certainly include many duplicates since the
  /// render object of a [StatelessWidget] or [StatefulWidget] is the
  /// render object of its child; only [RenderObjectWidget]s have
  /// their own render object.
  Iterable<RenderObject> get allRenderObjects {
197
    TestAsyncUtils.guardSync();
198
    return allElements.map<RenderObject>((Element element) => element.renderObject);
199 200 201 202 203 204
  }

  /// The render object of the matching widget in the widget tree.
  ///
  /// Throws a [StateError] if `finder` is empty or matches more than
  /// one widget (even if they all have the same render object).
205 206 207
  ///
  /// * Use [firstRenderObject] if you expect to match several render objects but only want the first.
  /// * Use [renderObjectList] if you expect to match several render objects and want all of them.
208
  T renderObject<T extends RenderObject>(Finder finder) {
209
    TestAsyncUtils.guardSync();
210
    return finder.evaluate().single.renderObject as T;
211 212 213 214 215 216
  }

  /// The render object of the first matching widget according to a
  /// depth-first pre-order traversal of the widget tree.
  ///
  /// Throws a [StateError] if `finder` is empty.
217 218
  ///
  /// * Use [renderObject] if you only expect to match one render object.
219
  T firstRenderObject<T extends RenderObject>(Finder finder) {
220
    TestAsyncUtils.guardSync();
221
    return finder.evaluate().first.renderObject as T;
222 223
  }

224 225 226 227
  /// The render objects of the matching widgets in the widget tree.
  ///
  /// * Use [renderObject] if you only expect to match one render object.
  /// * Use [firstRenderObject] if you expect to match several but only want the first.
228
  Iterable<T> renderObjectList<T extends RenderObject>(Finder finder) {
229
    TestAsyncUtils.guardSync();
230
    return finder.evaluate().map<T>((Element element) {
231
      final T result = element.renderObject as T;
232 233
      return result;
    });
234 235
  }

236
  /// Returns a list of all the [Layer] objects in the rendering.
237
  List<Layer> get layers => _walkLayers(binding.renderView.debugLayer).toList();
238
  Iterable<Layer> _walkLayers(Layer layer) sync* {
239
    TestAsyncUtils.guardSync();
240 241
    yield layer;
    if (layer is ContainerLayer) {
242
      final ContainerLayer root = layer;
243 244 245 246 247 248 249 250 251 252 253
      Layer child = root.firstChild;
      while (child != null) {
        yield* _walkLayers(child);
        child = child.nextSibling;
      }
    }
  }

  // INTERACTION

  /// Dispatch a pointer down / pointer up sequence at the center of
254 255 256 257
  /// the given widget, assuming it is exposed.
  ///
  /// If the center of the widget is not exposed, this might send events to
  /// another object.
258 259
  Future<void> tap(Finder finder, {int pointer, int buttons = kPrimaryButton}) {
    return tapAt(getCenter(finder), pointer: pointer, buttons: buttons);
260 261
  }

262
  /// Dispatch a pointer down / pointer up sequence at the given location.
263
  Future<void> tapAt(Offset location, {int pointer, int buttons = kPrimaryButton}) {
264
    return TestAsyncUtils.guard<void>(() async {
265
      final TestGesture gesture = await startGesture(location, pointer: pointer, buttons: buttons);
266 267
      await gesture.up();
    });
268 269
  }

270 271 272 273 274
  /// Dispatch a pointer down at the center of the given widget, assuming it is
  /// exposed.
  ///
  /// If the center of the widget is not exposed, this might send events to
  /// another object.
275
  Future<TestGesture> press(Finder finder, {int pointer, int buttons = kPrimaryButton}) {
276
    return TestAsyncUtils.guard<TestGesture>(() {
277
      return startGesture(getCenter(finder), pointer: pointer, buttons: buttons);
278 279 280
    });
  }

281 282
  /// Dispatch a pointer down / pointer up sequence (with a delay of
  /// [kLongPressTimeout] + [kPressTimeout] between the two events) at the
283 284 285 286
  /// center of the given widget, assuming it is exposed.
  ///
  /// If the center of the widget is not exposed, this might send events to
  /// another object.
287 288
  Future<void> longPress(Finder finder, {int pointer, int buttons = kPrimaryButton}) {
    return longPressAt(getCenter(finder), pointer: pointer, buttons: buttons);
289 290 291 292
  }

  /// Dispatch a pointer down / pointer up sequence at the given location with
  /// a delay of [kLongPressTimeout] + [kPressTimeout] between the two events.
293
  Future<void> longPressAt(Offset location, {int pointer, int buttons = kPrimaryButton}) {
294
    return TestAsyncUtils.guard<void>(() async {
295
      final TestGesture gesture = await startGesture(location, pointer: pointer, buttons: buttons);
296 297 298 299 300
      await pump(kLongPressTimeout + kPressTimeout);
      await gesture.up();
    });
  }

301
  /// Attempts a fling gesture starting from the center of the given
302
  /// widget, moving the given distance, reaching the given speed.
303 304 305
  ///
  /// If the middle of the widget is not exposed, this might send
  /// events to another object.
306
  ///
307 308 309 310
  /// {@template flutter.flutter_test.fling}
  /// This can pump frames.
  ///
  /// Exactly 50 pointer events are synthesized.
311 312 313
  ///
  /// The `speed` is in pixels per second in the direction given by `offset`.
  ///
314 315 316 317 318 319 320 321 322 323 324 325 326
  /// The `offset` and `speed` control the interval between each pointer event.
  /// For example, if the `offset` is 200 pixels down, and the `speed` is 800
  /// pixels per second, the pointer events will be sent for each increment
  /// of 4 pixels (200/50), over 250ms (200/800), meaning events will be sent
  /// every 1.25ms (250/200).
  ///
  /// To make tests more realistic, frames may be pumped during this time (using
  /// calls to [pump]). If the total duration is longer than `frameInterval`,
  /// then one frame is pumped each time that amount of time elapses while
  /// sending events, or each time an event is synthesized, whichever is rarer.
  ///
  /// See [LiveTestWidgetsFlutterBindingFramePolicy.benchmarkLive] if the method
  /// is used in a live environment and accurate time control is important.
Ian Hickson's avatar
Ian Hickson committed
327 328 329 330 331 332 333
  ///
  /// The `initialOffset` argument, if non-zero, causes the pointer to first
  /// apply that offset, then pump a delay of `initialOffsetDelay`. This can be
  /// used to simulate a drag followed by a fling, including dragging in the
  /// opposite direction of the fling (e.g. dragging 200 pixels to the right,
  /// then fling to the left over 200 pixels, ending at the exact point that the
  /// drag started).
334 335 336 337
  /// {@endtemplate}
  ///
  /// A fling is essentially a drag that ends at a particular speed. If you
  /// just want to drag and end without a fling, use [drag].
338 339 340 341
  Future<void> fling(
    Finder finder,
    Offset offset,
    double speed, {
342
    int pointer,
343
    int buttons = kPrimaryButton,
344 345 346
    Duration frameInterval = const Duration(milliseconds: 16),
    Offset initialOffset = Offset.zero,
    Duration initialOffsetDelay = const Duration(seconds: 1),
347
  }) {
Ian Hickson's avatar
Ian Hickson committed
348 349 350 351 352
    return flingFrom(
      getCenter(finder),
      offset,
      speed,
      pointer: pointer,
353
      buttons: buttons,
Ian Hickson's avatar
Ian Hickson committed
354 355 356 357
      frameInterval: frameInterval,
      initialOffset: initialOffset,
      initialOffsetDelay: initialOffsetDelay,
    );
358 359
  }

360 361
  /// Attempts a fling gesture starting from the given location, moving the
  /// given distance, reaching the given speed.
362
  ///
363
  /// {@macro flutter.flutter_test.fling}
364 365 366
  ///
  /// A fling is essentially a drag that ends at a particular speed. If you
  /// just want to drag and end without a fling, use [dragFrom].
367 368 369 370
  Future<void> flingFrom(
    Offset startLocation,
    Offset offset,
    double speed, {
Ian Hickson's avatar
Ian Hickson committed
371
    int pointer,
372
    int buttons = kPrimaryButton,
373 374 375
    Duration frameInterval = const Duration(milliseconds: 16),
    Offset initialOffset = Offset.zero,
    Duration initialOffsetDelay = const Duration(seconds: 1),
Ian Hickson's avatar
Ian Hickson committed
376
  }) {
377
    assert(offset.distance > 0.0);
378
    assert(speed > 0.0); // speed is pixels/second
379
    return TestAsyncUtils.guard<void>(() async {
380
      final TestPointer testPointer = TestPointer(pointer ?? _getNextPointer(), PointerDeviceKind.touch, null, buttons);
381
      final HitTestResult result = hitTestOnBinding(startLocation);
382
      const int kMoveCount = 50; // Needs to be >= kHistorySize, see _LeastSquaresVelocityTrackerStrategy
383
      final double timeStampDelta = 1000000.0 * offset.distance / (kMoveCount * speed);
384
      double timeStamp = 0.0;
385
      double lastTimeStamp = timeStamp;
386
      await sendEventToBinding(testPointer.down(startLocation, timeStamp: Duration(microseconds: timeStamp.round())), result);
Ian Hickson's avatar
Ian Hickson committed
387
      if (initialOffset.distance > 0.0) {
388 389
        await sendEventToBinding(testPointer.move(startLocation + initialOffset, timeStamp: Duration(microseconds: timeStamp.round())), result);
        timeStamp += initialOffsetDelay.inMicroseconds;
Ian Hickson's avatar
Ian Hickson committed
390 391
        await pump(initialOffsetDelay);
      }
392
      for (int i = 0; i <= kMoveCount; i += 1) {
Ian Hickson's avatar
Ian Hickson committed
393
        final Offset location = startLocation + initialOffset + Offset.lerp(Offset.zero, offset, i / kMoveCount);
394
        await sendEventToBinding(testPointer.move(location, timeStamp: Duration(microseconds: timeStamp.round())), result);
395
        timeStamp += timeStampDelta;
396 397
        if (timeStamp - lastTimeStamp > frameInterval.inMicroseconds) {
          await pump(Duration(microseconds: (timeStamp - lastTimeStamp).truncate()));
398 399
          lastTimeStamp = timeStamp;
        }
400
      }
401
      await sendEventToBinding(testPointer.up(timeStamp: Duration(microseconds: timeStamp.round())), result);
402
    });
403 404
  }

405 406 407 408 409 410
  /// A simulator of how the framework handles a series of [PointerEvent]s
  /// received from the Flutter engine.
  ///
  /// The [PointerEventRecord.timeDelay] is used as the time delay of the events
  /// injection relative to the starting point of the method call.
  ///
411 412 413 414 415 416 417
  /// 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,
418
  /// but a very small portion may have a tiny negative value for about tens of
419 420 421
  /// 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
422 423 424 425 426
  /// `records`.
  ///
  /// See [PointerEventRecord].
  Future<List<Duration>> handlePointerEventRecord(List<PointerEventRecord> records);

427 428 429 430 431
  /// Called to indicate that there should be a new frame after an optional
  /// delay.
  ///
  /// The frame is pumped after a delay of [duration] if [duration] is not null,
  /// or immediately otherwise.
432 433 434 435
  ///
  /// This is invoked by [flingFrom], for instance, so that the sequence of
  /// pointer events occurs over time.
  ///
436
  /// The [WidgetTester] subclass implements this by deferring to the [binding].
437 438 439
  ///
  /// See also [SchedulerBinding.endOfFrame], which returns a future that could
  /// be appropriate to return in the implementation of this method.
440
  Future<void> pump([Duration duration]);
441

442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469
  /// Repeatedly calls [pump] with the given `duration` until there are no
  /// longer any frames scheduled. This will call [pump] at least once, even if
  /// no frames are scheduled when the function is called, to flush any pending
  /// microtasks which may themselves schedule a frame.
  ///
  /// This essentially waits for all animations to have completed.
  ///
  /// If it takes longer that the given `timeout` to settle, then the test will
  /// fail (this method will throw an exception). In particular, this means that
  /// if there is an infinite animation in progress (for example, if there is an
  /// indeterminate progress indicator spinning), this method will throw.
  ///
  /// The default timeout is ten minutes, which is longer than most reasonable
  /// finite animations would last.
  ///
  /// If the function returns, it returns the number of pumps that it performed.
  ///
  /// In general, it is better practice to figure out exactly why each frame is
  /// needed, and then to [pump] exactly as many frames as necessary. This will
  /// help catch regressions where, for instance, an animation is being started
  /// one frame later than it should.
  ///
  /// Alternatively, one can check that the return value from this function
  /// matches the expected number of pumps.
  Future<int> pumpAndSettle([
    Duration duration = const Duration(milliseconds: 100),
  ]);

470 471 472 473 474
  /// Attempts to drag the given widget by the given offset, by
  /// starting a drag in the middle of the widget.
  ///
  /// If the middle of the widget is not exposed, this might send
  /// events to another object.
475 476 477
  ///
  /// If you want the drag to end with a speed so that the gesture recognition
  /// system identifies the gesture as a fling, consider using [fling] instead.
478
  ///
479 480 481
  /// The operation happens at once. If you want the drag to last for a period
  /// of time, consider using [timedDrag].
  ///
482
  /// {@template flutter.flutter_test.drag}
483 484 485 486 487 488
  /// By default, if the x or y component of offset is greater than
  /// [kDragSlopDefault], the gesture is broken up into two separate moves
  /// calls. Changing `touchSlopX` or `touchSlopY` will change the minimum
  /// amount of movement in the respective axis before the drag will be broken
  /// into multiple calls. To always send the drag with just a single call to
  /// [TestGesture.moveBy], `touchSlopX` and `touchSlopY` should be set to 0.
489 490 491 492 493 494
  ///
  /// Breaking the drag into multiple moves is necessary for accurate execution
  /// of drag update calls with a [DragStartBehavior] variable set to
  /// [DragStartBehavior.start]. Without such a change, the dragUpdate callback
  /// from a drag recognizer will never be invoked.
  ///
495 496
  /// To force this function to a send a single move event, the `touchSlopX` and
  /// `touchSlopY` variables should be set to 0. However, generally, these values
497
  /// should be left to their default values.
498
  /// {@endtemplate}
499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514
  Future<void> drag(
    Finder finder,
    Offset offset, {
    int pointer,
    int buttons = kPrimaryButton,
    double touchSlopX = kDragSlopDefault,
    double touchSlopY = kDragSlopDefault,
  }) {
    return dragFrom(
      getCenter(finder),
      offset,
      pointer: pointer,
      buttons: buttons,
      touchSlopX: touchSlopX,
      touchSlopY: touchSlopY,
    );
515 516 517 518
  }

  /// Attempts a drag gesture consisting of a pointer down, a move by
  /// the given offset, and a pointer up.
519 520 521 522
  ///
  /// If you want the drag to end with a speed so that the gesture recognition
  /// system identifies the gesture as a fling, consider using [flingFrom]
  /// instead.
523
  ///
524 525 526
  /// The operation happens at once. If you want the drag to last for a period
  /// of time, consider using [timedDragFrom].
  ///
527
  /// {@macro flutter.flutter_test.drag}
528 529 530 531 532 533 534 535
  Future<void> dragFrom(
    Offset startLocation,
    Offset offset, {
    int pointer,
    int buttons = kPrimaryButton,
    double touchSlopX = kDragSlopDefault,
    double touchSlopY = kDragSlopDefault,
  }) {
536
    assert(kDragSlopDefault > kTouchSlop);
537
    return TestAsyncUtils.guard<void>(() async {
538
      final TestGesture gesture = await startGesture(startLocation, pointer: pointer, buttons: buttons);
539
      assert(gesture != null);
540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604

      final double xSign = offset.dx.sign;
      final double ySign = offset.dy.sign;

      final double offsetX = offset.dx;
      final double offsetY = offset.dy;

      final bool separateX = offset.dx.abs() > touchSlopX && touchSlopX > 0;
      final bool separateY = offset.dy.abs() > touchSlopY && touchSlopY > 0;

      if (separateY || separateX) {
        final double offsetSlope = offsetY / offsetX;
        final double inverseOffsetSlope = offsetX / offsetY;
        final double slopSlope = touchSlopY / touchSlopX;
        final double absoluteOffsetSlope = offsetSlope.abs();
        final double signedSlopX = touchSlopX * xSign;
        final double signedSlopY = touchSlopY * ySign;
        if (absoluteOffsetSlope != slopSlope) {
          // The drag goes through one or both of the extents of the edges of the box.
          if (absoluteOffsetSlope < slopSlope) {
            assert(offsetX.abs() > touchSlopX);
            // The drag goes through the vertical edge of the box.
            // It is guaranteed that the |offsetX| > touchSlopX.
            final double diffY = offsetSlope.abs() * touchSlopX * ySign;

            // The vector from the origin to the vertical edge.
            await gesture.moveBy(Offset(signedSlopX, diffY));
            if (offsetY.abs() <= touchSlopY) {
              // The drag ends on or before getting to the horizontal extension of the horizontal edge.
              await gesture.moveBy(Offset(offsetX - signedSlopX, offsetY - diffY));
            } else {
              final double diffY2 = signedSlopY - diffY;
              final double diffX2 = inverseOffsetSlope * diffY2;

              // The vector from the edge of the box to the horizontal extension of the horizontal edge.
              await gesture.moveBy(Offset(diffX2, diffY2));
              await gesture.moveBy(Offset(offsetX - diffX2 - signedSlopX, offsetY - signedSlopY));
            }
          } else {
            assert(offsetY.abs() > touchSlopY);
            // The drag goes through the horizontal edge of the box.
            // It is guaranteed that the |offsetY| > touchSlopY.
            final double diffX = inverseOffsetSlope.abs() * touchSlopY * xSign;

            // The vector from the origin to the vertical edge.
            await gesture.moveBy(Offset(diffX, signedSlopY));
            if (offsetX.abs() <= touchSlopX) {
              // The drag ends on or before getting to the vertical extension of the vertical edge.
              await gesture.moveBy(Offset(offsetX - diffX, offsetY - signedSlopY));
            } else {
              final double diffX2 = signedSlopX - diffX;
              final double diffY2 = offsetSlope * diffX2;

              // The vector from the edge of the box to the vertical extension of the vertical edge.
              await gesture.moveBy(Offset(diffX2, diffY2));
              await gesture.moveBy(Offset(offsetX - signedSlopX, offsetY - diffY2 - signedSlopY));
            }
          }
        } else { // The drag goes through the corner of the box.
          await gesture.moveBy(Offset(signedSlopX, signedSlopY));
          await gesture.moveBy(Offset(offsetX - signedSlopX, offsetY - signedSlopY));
        }
      } else { // The drag ends inside the box.
        await gesture.moveBy(offset);
      }
605 606
      await gesture.up();
    });
607 608
  }

609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664
  /// Attempts to drag the given widget by the given offset in the `duration`
  /// time, starting in the middle of the widget.
  ///
  /// If the middle of the widget is not exposed, this might send
  /// events to another object.
  ///
  /// This is the timed version of [drag]. This may or may not result in a
  /// [fling] or ballistic animation, depending on the speed from
  /// `offset/duration`.
  ///
  /// {@template flutter.flutter_test.timeddrag}
  /// The move events are sent at a given `frequency` in Hz (or events per
  /// second). It defaults to 60Hz.
  ///
  /// The movement is linear in time.
  ///
  /// See also [LiveTestWidgetsFlutterBindingFramePolicy.benchmarkLive] for
  /// more accurate time control.
  /// {@endtemplate}
  Future<void> timedDrag(
    Finder finder,
    Offset offset,
    Duration duration, {
    int pointer,
    int buttons = kPrimaryButton,
    double frequency = 60.0,
  }) {
    return timedDragFrom(
      getCenter(finder),
      offset,
      duration,
      pointer: pointer,
      buttons: buttons,
      frequency: frequency,
    );
  }

  /// Attempts a series of [PointerEvent]s to simulate a drag operation in the
  /// `duration` time.
  ///
  /// This is the timed version of [dragFrom]. This may or may not result in a
  /// [flingFrom] or ballistic animation, depending on the speed from
  /// `offset/duration`.
  ///
  /// {@macro flutter.flutter_test.timeddrag}
  Future<void> timedDragFrom(
    Offset startLocation,
    Offset offset,
    Duration duration, {
    int pointer,
    int buttons = kPrimaryButton,
    double frequency = 60.0,
  }) {
    assert(frequency > 0);
    final int intervals = duration.inMicroseconds * frequency ~/ 1E6;
    assert(intervals > 1);
665
    pointer ??= _getNextPointer();
666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704
    final List<Duration> timeStamps = <Duration>[
      for (int t = 0; t <= intervals; t += 1)
        duration * t ~/ intervals,
    ];
    final List<Offset> offsets = <Offset>[
      startLocation,
      for (int t = 0; t <= intervals; t += 1)
        startLocation + offset * (t / intervals),
    ];
    final List<PointerEventRecord> records = <PointerEventRecord>[
      PointerEventRecord(Duration.zero, <PointerEvent>[
          PointerAddedEvent(
            timeStamp: Duration.zero,
            position: startLocation,
          ),
          PointerDownEvent(
            timeStamp: Duration.zero,
            position: startLocation,
            pointer: pointer,
            buttons: buttons,
          ),
        ]),
      ...<PointerEventRecord>[
        for(int t = 0; t <= intervals; t += 1)
          PointerEventRecord(timeStamps[t], <PointerEvent>[
            PointerMoveEvent(
              timeStamp: timeStamps[t],
              position: offsets[t+1],
              delta: offsets[t+1] - offsets[t],
              pointer: pointer,
              buttons: buttons,
            )
          ]),
      ],
      PointerEventRecord(duration, <PointerEvent>[
        PointerUpEvent(
          timeStamp: duration,
          position: offsets.last,
          pointer: pointer,
705 706
          // The PointerData received from the engine with
          // change = PointerChange.up, which translates to PointerUpEvent,
707 708 709 710 711 712 713 714 715 716
          // doesn't provide the button field.
          // buttons: buttons,
        )
      ]),
    ];
    return TestAsyncUtils.guard<void>(() async {
      return handlePointerEventRecord(records);
    });
  }

717 718 719 720
  /// The next available pointer identifier.
  ///
  /// This is the default pointer identifier that will be used the next time the
  /// [startGesture] method is called without an explicit pointer identifier.
721
  int get nextPointer => _nextPointer;
722

723 724 725 726 727
  static int _nextPointer = 1;

  static int _getNextPointer() {
    final int result = _nextPointer;
    _nextPointer += 1;
728 729 730
    return result;
  }

731 732 733 734 735
  /// Creates gesture and returns the [TestGesture] object which you can use
  /// to continue the gesture using calls on the [TestGesture] object.
  ///
  /// You can use [startGesture] instead if your gesture begins with a down
  /// event.
736 737 738 739 740 741
  Future<TestGesture> createGesture({
    int pointer,
    PointerDeviceKind kind = PointerDeviceKind.touch,
    int buttons = kPrimaryButton,
  }) async {
    return TestGesture(
742 743
      hitTester: hitTestOnBinding,
      dispatcher: sendEventToBinding,
744 745
      kind: kind,
      pointer: pointer ?? _getNextPointer(),
746
      buttons: buttons,
747
    );
748 749
  }

750 751 752 753 754 755
  /// Creates a gesture with an initial down gesture at a particular point, and
  /// returns the [TestGesture] object which you can use to continue the
  /// gesture.
  ///
  /// You can use [createGesture] if your gesture doesn't begin with an initial
  /// down gesture.
756 757 758 759
  Future<TestGesture> startGesture(
    Offset downLocation, {
    int pointer,
    PointerDeviceKind kind = PointerDeviceKind.touch,
760
    int buttons = kPrimaryButton,
761
  }) async {
762
    assert(downLocation != null);
763 764 765 766 767
    final TestGesture result = await createGesture(
      pointer: pointer,
      kind: kind,
      buttons: buttons,
    );
768 769 770 771
    await result.down(downLocation);
    return result;
  }

772
  /// Forwards the given location to the binding's hitTest logic.
773
  HitTestResult hitTestOnBinding(Offset location) {
774
    final HitTestResult result = HitTestResult();
775 776 777 778
    binding.hitTest(result, location);
    return result;
  }

779
  /// Forwards the given pointer event to the binding.
780 781
  Future<void> sendEventToBinding(PointerEvent event, HitTestResult result) {
    return TestAsyncUtils.guard<void>(() async {
782 783
      binding.dispatchEvent(event, result);
    });
784 785
  }

786 787 788
  // GEOMETRY

  /// Returns the point at the center of the given widget.
789 790
  Offset getCenter(Finder finder) {
    return _getElementPoint(finder, (Size size) => size.center(Offset.zero));
791 792 793
  }

  /// Returns the point at the top left of the given widget.
794 795
  Offset getTopLeft(Finder finder) {
    return _getElementPoint(finder, (Size size) => Offset.zero);
796 797 798 799
  }

  /// Returns the point at the top right of the given widget. This
  /// point is not inside the object's hit test area.
800 801
  Offset getTopRight(Finder finder) {
    return _getElementPoint(finder, (Size size) => size.topRight(Offset.zero));
802 803 804 805
  }

  /// Returns the point at the bottom left of the given widget. This
  /// point is not inside the object's hit test area.
806 807
  Offset getBottomLeft(Finder finder) {
    return _getElementPoint(finder, (Size size) => size.bottomLeft(Offset.zero));
808 809 810 811
  }

  /// Returns the point at the bottom right of the given widget. This
  /// point is not inside the object's hit test area.
812 813
  Offset getBottomRight(Finder finder) {
    return _getElementPoint(finder, (Size size) => size.bottomRight(Offset.zero));
814 815
  }

816
  Offset _getElementPoint(Finder finder, Offset sizeToPoint(Size size)) {
817
    TestAsyncUtils.guardSync();
818
    final Element element = finder.evaluate().single;
819
    final RenderBox box = element.renderObject as RenderBox;
820 821 822 823 824 825 826
    assert(box != null);
    return box.localToGlobal(sizeToPoint(box.size));
  }

  /// Returns the size of the given widget. This is only valid once
  /// the widget's render object has been laid out at least once.
  Size getSize(Finder finder) {
827
    TestAsyncUtils.guardSync();
828
    final Element element = finder.evaluate().single;
829
    final RenderBox box = element.renderObject as RenderBox;
830 831 832
    assert(box != null);
    return box.size;
  }
833

834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901
  /// Simulates sending physical key down and up events through the system channel.
  ///
  /// This only simulates key events coming from a physical keyboard, not from a
  /// soft keyboard.
  ///
  /// Specify `platform` as one of the platforms allowed in
  /// [Platform.operatingSystem] to make the event appear to be from that type
  /// of system. Defaults to "android". Must not be null. Some platforms (e.g.
  /// Windows, iOS) are not yet supported.
  ///
  /// Keys that are down when the test completes are cleared after each test.
  ///
  /// This method sends both the key down and the key up events, to simulate a
  /// key press. To simulate individual down and/or up events, see
  /// [sendKeyDownEvent] and [sendKeyUpEvent].
  ///
  /// See also:
  ///
  ///  - [sendKeyDownEvent] to simulate only a key down event.
  ///  - [sendKeyUpEvent] to simulate only a key up event.
  Future<void> sendKeyEvent(LogicalKeyboardKey key, { String platform = 'android' }) async {
    assert(platform != null);
    await simulateKeyDownEvent(key, platform: platform);
    // Internally wrapped in async guard.
    return simulateKeyUpEvent(key, platform: platform);
  }

  /// Simulates sending a physical key down event through the system channel.
  ///
  /// This only simulates key down events coming from a physical keyboard, not
  /// from a soft keyboard.
  ///
  /// Specify `platform` as one of the platforms allowed in
  /// [Platform.operatingSystem] to make the event appear to be from that type
  /// of system. Defaults to "android". Must not be null. Some platforms (e.g.
  /// Windows, iOS) are not yet supported.
  ///
  /// Keys that are down when the test completes are cleared after each test.
  ///
  /// See also:
  ///
  ///  - [sendKeyUpEvent] to simulate the corresponding key up event.
  ///  - [sendKeyEvent] to simulate both the key up and key down in the same call.
  Future<void> sendKeyDownEvent(LogicalKeyboardKey key, { String platform = 'android' }) async {
    assert(platform != null);
    // Internally wrapped in async guard.
    return simulateKeyDownEvent(key, platform: platform);
  }

  /// Simulates sending a physical key up event through the system channel.
  ///
  /// This only simulates key up events coming from a physical keyboard,
  /// not from a soft keyboard.
  ///
  /// Specify `platform` as one of the platforms allowed in
  /// [Platform.operatingSystem] to make the event appear to be from that type
  /// of system. Defaults to "android". May not be null.
  ///
  /// See also:
  ///
  ///  - [sendKeyDownEvent] to simulate the corresponding key down event.
  ///  - [sendKeyEvent] to simulate both the key up and key down in the same call.
  Future<void> sendKeyUpEvent(LogicalKeyboardKey key, { String platform = 'android' }) async {
    assert(platform != null);
    // Internally wrapped in async guard.
    return simulateKeyUpEvent(key, platform: platform);
  }

902 903 904
  /// Returns the rect of the given widget. This is only valid once
  /// the widget's render object has been laid out at least once.
  Rect getRect(Finder finder) => getTopLeft(finder) & getSize(finder);
905

906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948
  /// Attempts to find the [SemanticsNode] of first result from `finder`.
  ///
  /// If the object identified by the finder doesn't own it's semantic node,
  /// this will return the semantics data of the first ancestor with semantics.
  /// The ancestor's semantic data will include the child's as well as
  /// other nodes that have been merged together.
  ///
  /// If the [SemanticsNode] of the object identified by the finder is
  /// force-merged into an ancestor (e.g. via the [MergeSemantics] widget)
  /// the node into which it is merged is returned. That node will include
  /// all the semantics information of the nodes merged into it.
  ///
  /// Will throw a [StateError] if the finder returns more than one element or
  /// if no semantics are found or are not enabled.
  SemanticsNode getSemantics(Finder finder) {
    if (binding.pipelineOwner.semanticsOwner == null)
      throw StateError('Semantics are not enabled.');
    final Iterable<Element> candidates = finder.evaluate();
    if (candidates.isEmpty) {
      throw StateError('Finder returned no matching elements.');
    }
    if (candidates.length > 1) {
      throw StateError('Finder returned more than one element.');
    }
    final Element element = candidates.single;
    RenderObject renderObject = element.findRenderObject();
    SemanticsNode result = renderObject.debugSemantics;
    while (renderObject != null && (result == null || result.isMergedIntoParent)) {
      renderObject = renderObject?.parent as RenderObject;
      result = renderObject?.debugSemantics;
    }
    if (result == null)
      throw StateError('No Semantics data found.');
    return result;
  }

  /// Enable semantics in a test by creating a [SemanticsHandle].
  ///
  /// The handle must be disposed at the end of the test.
  SemanticsHandle ensureSemantics() {
    return binding.pipelineOwner.ensureSemantics();
  }

949 950 951 952 953 954 955 956
  /// Given a widget `W` specified by [finder] and a [Scrollable] widget `S` in
  /// its ancestry tree, this scrolls `S` so as to make `W` visible.
  ///
  /// Usually the `finder` for this method should be labeled
  /// `skipOffstage: false`, so that [Finder] deals with widgets that's out of
  /// the screen correctly.
  ///
  /// This does not work when the `S` is long and `W` far away from the
957
  /// displayed part does not have a cached element yet. See
958 959 960 961
  /// https://github.com/flutter/flutter/issues/61458
  ///
  /// Shorthand for `Scrollable.ensureVisible(element(finder))`
  Future<void> ensureVisible(Finder finder) => Scrollable.ensureVisible(element(finder));
962

963
  /// Repeatedly scrolls a [Scrollable] by `delta` in the
964
  /// [Scrollable.axisDirection] until `finder` is visible.
965 966 967
  ///
  /// Between each scroll, wait for `duration` time for settling.
  ///
968 969
  /// If `scrollable` is `null`, this will find a [Scrollable].
  ///
970 971 972 973 974
  /// Throws a [StateError] if `finder` is not found for maximum `maxScrolls`
  /// times.
  ///
  /// This is different from [ensureVisible] in that this allows looking for
  /// `finder` that is not built yet, but the caller must specify the scrollable
975 976 977 978
  /// that will build child specified by `finder` when there are multiple
  ///[Scrollable]s.
  ///
  /// See also [dragUntilVisible].
979 980 981
  Future<void> scrollUntilVisible(
    Finder finder,
    double delta, {
982
      Finder scrollable,
983 984 985 986 987
      int maxScrolls = 50,
      Duration duration = const Duration(milliseconds: 50),
    }
  ) {
    assert(maxScrolls > 0);
988
    scrollable ??= find.byType(Scrollable);
989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004
    return TestAsyncUtils.guard<void>(() async {
      Offset moveStep;
      switch(widget<Scrollable>(scrollable).axisDirection) {
        case AxisDirection.up:
          moveStep = Offset(0, delta);
          break;
        case AxisDirection.down:
          moveStep = Offset(0, -delta);
          break;
        case AxisDirection.left:
          moveStep = Offset(delta, 0);
          break;
        case AxisDirection.right:
          moveStep = Offset(-delta, 0);
          break;
      }
1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029
      await dragUntilVisible(
        finder,
        scrollable,
        moveStep,
        maxIteration: maxScrolls,
        duration: duration);
    });
  }

  /// Repeatedly drags the `view` by `moveStep` until `finder` is visible.
  ///
  /// Between each operation, wait for `duration` time for settling.
  ///
  /// Throws a [StateError] if `finder` is not found for maximum `maxIteration`
  /// times.
  Future<void> dragUntilVisible(
    Finder finder,
    Finder view,
    Offset moveStep, {
      int maxIteration = 50,
      Duration duration = const Duration(milliseconds: 50),
  }) {
    return TestAsyncUtils.guard<void>(() async {
      while(maxIteration > 0 && finder.evaluate().isEmpty) {
        await drag(view, moveStep);
1030
        await pump(duration);
1031
        maxIteration-= 1;
1032 1033 1034 1035
      }
      await Scrollable.ensureVisible(element(finder));
    });
  }
1036
}
1037 1038 1039 1040 1041 1042 1043 1044 1045 1046

/// Variant of [WidgetController] that can be used in tests running
/// on a device.
///
/// This is used, for instance, by [FlutterDriver].
class LiveWidgetController extends WidgetController {
  /// Creates a widget controller that uses the given binding.
  LiveWidgetController(WidgetsBinding binding) : super(binding);

  @override
1047
  Future<void> pump([Duration duration]) async {
1048
    if (duration != null)
1049
      await Future<void>.delayed(duration);
1050 1051 1052
    binding.scheduleFrame();
    await binding.endOfFrame;
  }
1053

1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069
  @override
  Future<int> pumpAndSettle([
    Duration duration = const Duration(milliseconds: 100),
  ]) {
    assert(duration != null);
    assert(duration > Duration.zero);
    return TestAsyncUtils.guard<int>(() async {
      int count = 0;
      do {
        await pump(duration);
        count += 1;
      } while (binding.hasScheduledFrame);
      return count;
    });
  }

1070 1071
  @override
  Future<List<Duration>> handlePointerEventRecord(List<PointerEventRecord> records) {
1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113
    assert(records != null);
    assert(records.isNotEmpty);
    return TestAsyncUtils.guard<List<Duration>>(() async {
      // hitTestHistory is an equivalence of _hitTests in [GestureBinding],
      // used as state for all pointers which are currently down.
      final Map<int, HitTestResult> hitTestHistory = <int, HitTestResult>{};
      final List<Duration> handleTimeStampDiff = <Duration>[];
      DateTime startTime;
      for (final PointerEventRecord record in records) {
        final DateTime now = clock.now();
        startTime ??= now;
        // So that the first event is promised to receive a zero timeDiff
        final Duration timeDiff = record.timeDelay - now.difference(startTime);
        if (timeDiff.isNegative) {
          // This happens when something (e.g. GC) takes a long time during the
          // processing of the events.
          // Flush all past events
          handleTimeStampDiff.add(-timeDiff);
          for (final PointerEvent event in record.events) {
            _handlePointerEvent(event, hitTestHistory);
          }
        } else {
          await Future<void>.delayed(timeDiff);
          handleTimeStampDiff.add(
            // Recalculating the time diff for getting exact time when the event
            // packet is sent. For a perfect Future.delayed like the one in a
            // fake async this new diff should be zero.
            clock.now().difference(startTime) - record.timeDelay,
          );
          for (final PointerEvent event in record.events) {
            _handlePointerEvent(event, hitTestHistory);
          }
        }
      }
      // This makes sure that a gesture is completed, with no more pointers
      // active.
      assert(hitTestHistory.isEmpty);
      return handleTimeStampDiff;
    });
  }

  // This method is almost identical to [GestureBinding._handlePointerEvent]
1114
  // to replicate the behavior of the real binding.
1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152
  void _handlePointerEvent(
    PointerEvent event,
    Map<int, HitTestResult> _hitTests
  ) {
    HitTestResult hitTestResult;
    if (event is PointerDownEvent || event is PointerSignalEvent) {
      assert(!_hitTests.containsKey(event.pointer));
      hitTestResult = HitTestResult();
      binding.hitTest(hitTestResult, event.position);
      if (event is PointerDownEvent) {
        _hitTests[event.pointer] = hitTestResult;
      }
      assert(() {
        if (debugPrintHitTestResults)
          debugPrint('$event: $hitTestResult');
        return true;
      }());
    } else if (event is PointerUpEvent || event is PointerCancelEvent) {
      hitTestResult = _hitTests.remove(event.pointer);
    } else if (event.down) {
      // Because events that occur with the pointer down (like
      // PointerMoveEvents) should be dispatched to the same place that their
      // initial PointerDownEvent was, we want to re-use the path we found when
      // the pointer went down, rather than do hit detection each time we get
      // such an event.
      hitTestResult = _hitTests[event.pointer];
    }
    assert(() {
      if (debugPrintMouseHoverEvents && event is PointerHoverEvent)
        debugPrint('$event');
      return true;
    }());
    if (hitTestResult != null ||
        event is PointerHoverEvent ||
        event is PointerAddedEvent ||
        event is PointerRemovedEvent) {
      binding.dispatchEvent(event, hitTestResult);
    }
1153
  }
1154
}