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

5
import 'package:flutter/cupertino.dart';
6
import 'package:flutter/foundation.dart';
7
import 'package:flutter/gestures.dart';
8
import 'package:flutter/material.dart' show Tooltip;
9
import 'package:flutter/rendering.dart';
10
import 'package:flutter/scheduler.dart';
11
import 'package:flutter/services.dart';
12
import 'package:flutter/widgets.dart';
13
import 'package:meta/meta.dart';
14 15

// ignore: deprecated_member_use
16
import 'package:test_api/test_api.dart' as test_package;
17

18
import 'all_elements.dart';
19
import 'binding.dart';
20
import 'controller.dart';
21
import 'finders.dart';
22
import 'matchers.dart';
23
import 'restoration.dart';
24
import 'test_async_utils.dart';
25
import 'test_compat.dart';
26
import 'test_pointer.dart';
27
import 'test_text_input.dart';
28

29 30 31
/// Keep users from needing multiple imports to test semantics.
export 'package:flutter/rendering.dart' show SemanticsHandle;

32
// ignore: deprecated_member_use
33 34 35
/// Hide these imports so that they do not conflict with our own implementations in
/// test_compat.dart. This handles setting up a declarer when one is not defined, which
/// can happen when a test is executed via flutter_run.
36
export 'package:test_api/test_api.dart' hide
37 38 39 40 41 42
  test,
  group,
  setUpAll,
  tearDownAll,
  setUp,
  tearDown,
43 44 45
  expect, // we have our own wrapper below
  TypeMatcher, // matcher's TypeMatcher conflicts with the one in the Flutter framework
  isInstanceOf; // we have our own wrapper in matchers.dart
46

47
/// Signature for callback to [testWidgets] and [benchmarkWidgets].
48
typedef WidgetTesterCallback = Future<void> Function(WidgetTester widgetTester);
49

50 51 52 53 54
/// Runs the [callback] inside the Flutter test environment.
///
/// Use this function for testing custom [StatelessWidget]s and
/// [StatefulWidget]s.
///
55 56
/// The callback can be asynchronous (using `async`/`await` or
/// using explicit [Future]s).
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74
///
/// There are two kinds of timeouts that can be specified. The `timeout`
/// argument specifies the backstop timeout implemented by the `test` package.
/// If set, it should be relatively large (minutes). It defaults to ten minutes
/// for tests run by `flutter test`, and is unlimited for tests run by `flutter
/// run`; specifically, it defaults to
/// [TestWidgetsFlutterBinding.defaultTestTimeout].
///
/// The `initialTimeout` argument specifies the timeout implemented by the
/// `flutter_test` package itself. If set, it may be relatively small (seconds),
/// as it is automatically increased for some expensive operations, and can also
/// be manually increased by calling
/// [AutomatedTestWidgetsFlutterBinding.addTime]. The effective maximum value of
/// this timeout (even after calling `addTime`) is the one specified by the
/// `timeout` argument.
///
/// In general, timeouts are race conditions and cause flakes, so best practice
/// is to avoid the use of timeouts in tests.
75
///
76
/// If the `semanticsEnabled` parameter is set to `true`,
77 78
/// [WidgetTester.ensureSemantics] will have been called before the tester is
/// passed to the `callback`, and that handle will automatically be disposed
79
/// after the callback is finished. It defaults to true.
80
///
81 82 83 84 85 86
/// This function uses the [test] function in the test package to
/// register the given callback as a test. The callback, when run,
/// will be given a new instance of [WidgetTester]. The [find] object
/// provides convenient widget [Finder]s for use with the
/// [WidgetTester].
///
87 88 89 90
/// When the [variant] argument is set, [testWidgets] will run the test once for
/// each value of the [TestVariant.values]. If [variant] is not set, the test
/// will be run once using the base test environment.
///
91 92 93
/// If the [tags] are passed, they declare user-defined tags that are implemented by
/// the `test` package.
///
94 95 96
/// See also:
///
///  * [AutomatedTestWidgetsFlutterBinding.addTime] to learn more about
97
///    timeout and how to manually increase timeouts.
98
///
99
/// ## Sample code
100
///
101
/// ```dart
102 103 104 105 106
/// testWidgets('MyWidget', (WidgetTester tester) async {
///   await tester.pumpWidget(new MyWidget());
///   await tester.tap(find.text('Save'));
///   expect(find.text('Success'), findsOneWidget);
/// });
107
/// ```
108
@isTest
109 110 111
void testWidgets(
  String description,
  WidgetTesterCallback callback, {
112
  bool skip = false,
113 114
  test_package.Timeout? timeout,
  Duration? initialTimeout,
115
  bool semanticsEnabled = true,
116
  TestVariant<Object?> variant = const DefaultTestVariant(),
117
  dynamic tags,
118
}) {
119 120
  assert(variant != null);
  assert(variant.values.isNotEmpty, 'There must be at least on value to test in the testing variant');
121
  final TestWidgetsFlutterBinding binding = TestWidgetsFlutterBinding.ensureInitialized() as TestWidgetsFlutterBinding;
122
  final WidgetTester tester = WidgetTester._(binding);
123
  for (final dynamic value in variant.values) {
124 125 126 127 128 129
    final String variationDescription = variant.describeValue(value);
    final String combinedDescription = variationDescription.isNotEmpty ? '$description ($variationDescription)' : description;
    test(
      combinedDescription,
      () {
        tester._testDescription = combinedDescription;
130
        SemanticsHandle? semanticsHandle;
131 132 133 134 135 136 137
        if (semanticsEnabled == true) {
          semanticsHandle = tester.ensureSemantics();
        }
        tester._recordNumberOfSemanticsHandles();
        test_package.addTearDown(binding.postTest);
        return binding.runTest(
          () async {
138
            binding.reset();
139 140
            debugResetSemanticsIdCounter();
            tester.resetTestTextInput();
141
            Object? memento;
142 143 144 145 146 147 148 149 150
            try {
              memento = await variant.setUp(value);
              await callback(tester);
            } finally {
              await variant.tearDown(value, memento);
            }
            semanticsHandle?.dispose();
          },
          tester._endOfTestVerifications,
151
          description: combinedDescription,
152 153 154 155 156
          timeout: initialTimeout,
        );
      },
      skip: skip,
      timeout: timeout ?? binding.defaultTestTimeout,
157
      tags: tags,
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189
    );
  }
}

/// An abstract base class for describing test environment variants.
///
/// These serve as elements of the `variants` argument to [testWidgets].
///
/// Use care when adding more testing variants: it multiplies the number of
/// tests which run. This can drastically increase the time it takes to run all
/// the tests.
abstract class TestVariant<T> {
  /// A const constructor so that subclasses can be const.
  const TestVariant();

  /// Returns an iterable of the variations that this test dimension represents.
  ///
  /// The variations returned should be unique so that the same variation isn't
  /// needlessly run twice.
  Iterable<T> get values;

  /// Returns the string that will be used to both add to the test description, and
  /// be printed when a test fails for this variation.
  String describeValue(T value);

  /// A function that will be called before each value is tested, with the
  /// value that will be tested.
  ///
  /// This function should preserve any state needed to restore the testing
  /// environment back to its base state when [tearDown] is called in the
  /// `Object` that is returned. The returned object will then be passed to
  /// [tearDown] as a `memento` when the test is complete.
190
  Future<Object?> setUp(T value);
191 192 193 194 195 196 197

  /// A function that is guaranteed to be called after a value is tested, even
  /// if it throws an exception.
  ///
  /// Calling this function must return the testing environment back to the base
  /// state it was in before [setUp] was called. The [memento] is the object
  /// returned from [setUp] when it was called.
198
  Future<void> tearDown(T value, covariant Object? memento);
199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232
}

/// The [TestVariant] that represents the "default" test that is run if no
/// `variants` iterable is specified for [testWidgets].
///
/// This variant can be added into a list of other test variants to provide
/// a "control" test where nothing is changed from the base test environment.
class DefaultTestVariant extends TestVariant<void> {
  /// A const constructor for a [DefaultTestVariant].
  const DefaultTestVariant();

  @override
  Iterable<void> get values => const <void>[null];

  @override
  String describeValue(void value) => '';

  @override
  Future<void> setUp(void value) async {}

  @override
  Future<void> tearDown(void value, void memento) async {}
}

/// A [TestVariant] that runs tests with [debugDefaultTargetPlatformOverride]
/// set to different values of [TargetPlatform].
class TargetPlatformVariant extends TestVariant<TargetPlatform> {
  /// Creates a [TargetPlatformVariant] that tests the given [values].
  const TargetPlatformVariant(this.values);

  /// Creates a [TargetPlatformVariant] that tests all values from
  /// the [TargetPlatform] enum.
  TargetPlatformVariant.all() : values = TargetPlatform.values.toSet();

233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248
  /// Creates a [TargetPlatformVariant] that includes platforms that are
  /// considered desktop platforms.
  TargetPlatformVariant.desktop() : values = <TargetPlatform>{
    TargetPlatform.linux,
    TargetPlatform.macOS,
    TargetPlatform.windows,
  };

  /// Creates a [TargetPlatformVariant] that includes platforms that are
  /// considered mobile platforms.
  TargetPlatformVariant.mobile() : values = <TargetPlatform>{
    TargetPlatform.android,
    TargetPlatform.iOS,
    TargetPlatform.fuchsia,
  };

249 250 251 252 253 254 255 256 257 258 259
  /// Creates a [TargetPlatformVariant] that tests only the given value of
  /// [TargetPlatform].
  TargetPlatformVariant.only(TargetPlatform platform) : values = <TargetPlatform>{platform};

  @override
  final Set<TargetPlatform> values;

  @override
  String describeValue(TargetPlatform value) => value.toString();

  @override
260 261
  Future<TargetPlatform?> setUp(TargetPlatform value) async {
    final TargetPlatform? previousTargetPlatform = debugDefaultTargetPlatformOverride;
262 263 264 265 266
    debugDefaultTargetPlatformOverride = value;
    return previousTargetPlatform;
  }

  @override
267
  Future<void> tearDown(TargetPlatform value, TargetPlatform? memento) async {
268 269
    debugDefaultTargetPlatformOverride = memento;
  }
270 271
}

272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310
/// A [TestVariant] that runs separate tests with each of the given values.
///
/// To use this variant, define it before the test, and then access
/// [currentValue] inside the test.
///
/// The values are typically enums, but they don't have to be. The `toString`
/// for the given value will be used to describe the variant. Values will have
/// their type name stripped from their `toString` output, so that enum values
/// will only print the value, not the type.
///
/// {@tool snippet}
/// This example shows how to set up the test to access the [currentValue]. In
/// this example, two tests will be run, one with `value1`, and one with
/// `value2`. The test with `value2` will fail. The names of the tests will be:
///
///   - `Test handling of TestScenario (value1)`
///   - `Test handling of TestScenario (value2)`
///
/// ```dart
/// enum TestScenario {
///   value1,
///   value2,
///   value3,
/// }
///
/// final ValueVariant<TestScenario> variants = ValueVariant<TestScenario>(
///   <TestScenario>{value1, value2},
/// );
///
/// testWidgets('Test handling of TestScenario', (WidgetTester tester) {
///   expect(variants.currentValue, equals(value1));
/// }, variant: variants);
/// ```
/// {@end-tool}
class ValueVariant<T> extends TestVariant<T> {
  /// Creates a [ValueVariant] that tests the given [values].
  ValueVariant(this.values);

  /// Returns the value currently under test.
311 312
  T? get currentValue => _currentValue;
  T? _currentValue;
313 314 315 316 317 318 319 320 321 322 323 324 325 326

  @override
  final Set<T> values;

  @override
  String describeValue(T value) => value.toString().replaceFirst('$T.', '');

  @override
  Future<T> setUp(T value) async => _currentValue = value;

  @override
  Future<void> tearDown(T value, T memento) async {}
}

327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342
/// The warning message to show when a benchmark is performed with assert on.
const String kDebugWarning = '''
┏╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍┓
┇ ⚠    THIS BENCHMARK IS BEING RUN IN DEBUG MODE     ⚠  ┇
┡╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍┦
│                                                       │
│  Numbers obtained from a benchmark while asserts are  │
│  enabled will not accurately reflect the performance  │
│  that will be experienced by end users using release  ╎
│  builds. Benchmarks should be run using this command  ╎
│  line:  "flutter run --profile test.dart" or          ┊
│  or "flutter drive --profile -t test.dart".           ┊
│                                                       ┊
└─────────────────────────────────────────────────╌┄┈  🐢
''';

343 344 345 346 347 348 349 350 351 352 353
/// Runs the [callback] inside the Flutter benchmark environment.
///
/// Use this function for benchmarking custom [StatelessWidget]s and
/// [StatefulWidget]s when you want to be able to use features from
/// [TestWidgetsFlutterBinding]. The callback, when run, will be given
/// a new instance of [WidgetTester]. The [find] object provides
/// convenient widget [Finder]s for use with the [WidgetTester].
///
/// The callback can be asynchronous (using `async`/`await` or using
/// explicit [Future]s). If it is, then [benchmarkWidgets] will return
/// a [Future] that completes when the callback's does. Otherwise, it
354 355 356 357
/// will return a Future that is always complete.
///
/// If the callback is asynchronous, make sure you `await` the call
/// to [benchmarkWidgets], otherwise it won't run!
358
///
359 360 361 362 363
/// If the `semanticsEnabled` parameter is set to `true`,
/// [WidgetTester.ensureSemantics] will have been called before the tester is
/// passed to the `callback`, and that handle will automatically be disposed
/// after the callback is finished.
///
364 365 366 367
/// Benchmarks must not be run in checked mode, because the performance is not
/// representative. To avoid this, this function will print a big message if it
/// is run in checked mode. Unit tests of this method pass `mayRunWithAsserts`,
/// but it should not be used for actual benchmarking.
368 369 370 371
///
/// Example:
///
///     main() async {
372
///       assert(false); // fail in checked mode
373 374
///       await benchmarkWidgets((WidgetTester tester) async {
///         await tester.pumpWidget(new MyWidget());
375 376
///         final Stopwatch timer = new Stopwatch()..start();
///         for (int index = 0; index < 10000; index += 1) {
377 378
///           await tester.tap(find.text('Tap me'));
///           await tester.pump();
379 380
///         }
///         timer.stop();
381
///         debugPrint('Time taken: ${timer.elapsedMilliseconds}ms');
382 383 384
///       });
///       exit(0);
///     }
385 386 387
Future<void> benchmarkWidgets(
  WidgetTesterCallback callback, {
  bool mayRunWithAsserts = false,
388
  bool semanticsEnabled = false,
389
}) {
390
  assert(() {
391 392
    if (mayRunWithAsserts)
      return true;
393
    print(kDebugWarning);
394
    return true;
395
  }());
396
  final TestWidgetsFlutterBinding binding = TestWidgetsFlutterBinding.ensureInitialized() as TestWidgetsFlutterBinding;
397
  assert(binding is! AutomatedTestWidgetsFlutterBinding);
398
  final WidgetTester tester = WidgetTester._(binding);
399
  SemanticsHandle? semanticsHandle;
400 401 402
  if (semanticsEnabled == true) {
    semanticsHandle = tester.ensureSemantics();
  }
403
  tester._recordNumberOfSemanticsHandles();
404
  return binding.runTest(
405 406 407 408
    () async {
      await callback(tester);
      semanticsHandle?.dispose();
    },
409
    tester._endOfTestVerifications,
410
  );
411
}
412

413 414 415 416 417
/// Assert that `actual` matches `matcher`.
///
/// See [test_package.expect] for details. This is a variant of that function
/// that additionally verifies that there are no asynchronous APIs
/// that have not yet resolved.
418 419 420 421
///
/// See also:
///
///  * [expectLater] for use with asynchronous matchers.
422 423 424
void expect(
  dynamic actual,
  dynamic matcher, {
425
  String? reason,
Ian Hickson's avatar
Ian Hickson committed
426
  dynamic skip, // true or a String
427 428
}) {
  TestAsyncUtils.guardSync();
Ian Hickson's avatar
Ian Hickson committed
429
  test_package.expect(actual, matcher, reason: reason, skip: skip);
430 431 432 433 434 435 436 437 438 439 440
}

/// Assert that `actual` matches `matcher`.
///
/// See [test_package.expect] for details. This variant will _not_ check that
/// there are no outstanding asynchronous API requests. As such, it can be
/// called from, e.g., callbacks that are run during build or layout, or in the
/// completion handlers of futures that execute in response to user input.
///
/// Generally, it is better to use [expect], which does include checks to ensure
/// that asynchronous APIs are not being called.
441 442 443
void expectSync(
  dynamic actual,
  dynamic matcher, {
444
  String? reason,
445
}) {
446
  test_package.expect(actual, matcher, reason: reason);
447 448
}

449 450 451 452 453 454 455 456
/// Just like [expect], but returns a [Future] that completes when the matcher
/// has finished matching.
///
/// See [test_package.expectLater] for details.
///
/// If the matcher fails asynchronously, that failure is piped to the returned
/// future where it can be handled by user code. If it is not handled by user
/// code, the test will fail.
457 458 459
Future<void> expectLater(
  dynamic actual,
  dynamic matcher, {
460
  String? reason,
461 462
  dynamic skip, // true or a String
}) {
463 464 465
  // We can't wrap the delegate in a guard, or we'll hit async barriers in
  // [TestWidgetsFlutterBinding] while we're waiting for the matcher to complete
  TestAsyncUtils.guardSync();
466 467
  return test_package.expectLater(actual, matcher, reason: reason, skip: skip)
           .then<void>((dynamic value) => null);
468 469
}

470
/// Class that programmatically interacts with widgets and the test environment.
471 472 473 474
///
/// For convenience, instances of this class (such as the one provided by
/// `testWidget`) can be used as the `vsync` for `AnimationController` objects.
class WidgetTester extends WidgetController implements HitTestDispatcher, TickerProvider {
475 476 477 478
  WidgetTester._(TestWidgetsFlutterBinding binding) : super(binding) {
    if (binding is LiveTestWidgetsFlutterBinding)
      binding.deviceEventDispatcher = this;
  }
479

480 481 482 483
  /// The description string of the test currently being run.
  String get testDescription => _testDescription;
  String _testDescription = '';

484 485
  /// The binding instance used by the testing framework.
  @override
486
  TestWidgetsFlutterBinding get binding => super.binding as TestWidgetsFlutterBinding;
487 488 489

  /// Renders the UI from the given [widget].
  ///
490 491 492 493
  /// Calls [runApp] with the given widget, then triggers a frame and flushes
  /// microtasks, by calling [pump] with the same `duration` (if any). The
  /// supplied [EnginePhase] is the final phase reached during the pump pass; if
  /// not supplied, the whole pass is executed.
494 495 496 497
  ///
  /// Subsequent calls to this is different from [pump] in that it forces a full
  /// rebuild of the tree, even if [widget] is the same as the previous call.
  /// [pump] will only rebuild the widgets that have changed.
498
  ///
499 500 501 502
  /// This method should not be used as the first parameter to an [expect] or
  /// [expectLater] call to test that a widget throws an exception. Instead, use
  /// [TestWidgetsFlutterBinding.takeException].
  ///
503
  /// {@tool snippet}
504 505 506 507 508 509 510 511
  /// ```dart
  /// testWidgets('MyWidget asserts invalid bounds', (WidgetTester tester) async {
  ///   await tester.pumpWidget(MyWidget(-1));
  ///   expect(tester.takeException(), isAssertionError); // or isNull, as appropriate.
  /// });
  /// ```
  /// {@end-tool}
  ///
512 513
  /// See also [LiveTestWidgetsFlutterBindingFramePolicy], which affects how
  /// this method works when the test is run with `flutter run`.
514 515
  Future<void> pumpWidget(
    Widget widget, [
516
    Duration? duration,
517
    EnginePhase phase = EnginePhase.sendSemanticsUpdate,
518
  ]) {
519
    return TestAsyncUtils.guard<void>(() {
520 521
      binding.attachRootWidget(widget);
      binding.scheduleFrame();
522 523
      return binding.pump(duration, phase);
    });
524 525
  }

526
  @override
527
  Future<List<Duration>> handlePointerEventRecord(Iterable<PointerEventRecord> records) {
528 529 530 531
    assert(records != null);
    assert(records.isNotEmpty);
    return TestAsyncUtils.guard<List<Duration>>(() async {
      final List<Duration> handleTimeStampDiff = <Duration>[];
532
      DateTime? startTime;
533 534 535 536 537 538 539
      for (final PointerEventRecord record in records) {
        final DateTime now = binding.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) {
          // Flush all past events
540
          handleTimeStampDiff.add(-timeDiff);
541
          for (final PointerEvent event in record.events) {
542
            binding.handlePointerEvent(event, source: TestBindingEventSource.test);
543 544 545 546 547
          }
        } else {
          await binding.pump();
          await binding.delayed(timeDiff);
          handleTimeStampDiff.add(
548
            binding.clock.now().difference(startTime) - record.timeDelay,
549 550
          );
          for (final PointerEvent event in record.events) {
551
            binding.handlePointerEvent(event, source: TestBindingEventSource.test);
552 553 554 555 556 557 558 559 560 561
          }
        }
      }
      await binding.pump();
      // This makes sure that a gesture is completed, with no more pointers
      // active.
      return handleTimeStampDiff;
    });
  }

562 563 564
  /// Triggers a frame after `duration` amount of time.
  ///
  /// This makes the framework act as if the application had janked (missed
565
  /// frames) for `duration` amount of time, and then received a "Vsync" signal
566
  /// to paint the application.
567
  ///
568 569 570 571
  /// For a [FakeAsync] environment (typically in `flutter test`), this advances
  /// time and timeout counting; for a live environment this delays `duration`
  /// time.
  ///
572 573
  /// This is a convenience function that just calls
  /// [TestWidgetsFlutterBinding.pump].
574 575 576
  ///
  /// See also [LiveTestWidgetsFlutterBindingFramePolicy], which affects how
  /// this method works when the test is run with `flutter run`.
577
  @override
578
  Future<void> pump([
579
    Duration? duration,
580
    EnginePhase phase = EnginePhase.sendSemanticsUpdate,
581
  ]) {
582
    return TestAsyncUtils.guard<void>(() => binding.pump(duration, phase));
583
  }
584

585 586 587 588 589 590 591 592 593 594
  /// Triggers a frame after `duration` amount of time, return as soon as the frame is drawn.
  ///
  /// This enables driving an artificially high CPU load by rendering frames in
  /// a tight loop. It must be used with the frame policy set to
  /// [LiveTestWidgetsFlutterBindingFramePolicy.benchmark].
  ///
  /// Similarly to [pump], this doesn't actually wait for `duration`, just
  /// advances the clock.
  Future<void> pumpBenchmark(Duration duration) async {
    assert(() {
595 596 597
      final TestWidgetsFlutterBinding widgetsBinding = binding;
      return widgetsBinding is LiveTestWidgetsFlutterBinding &&
              widgetsBinding.framePolicy == LiveTestWidgetsFlutterBindingFramePolicy.benchmark;
598 599 600 601 602
    }());

    dynamic caughtException;
    void handleError(dynamic error, StackTrace stackTrace) => caughtException ??= error;

603
    await Future<void>.microtask(() { binding.handleBeginFrame(duration); }).catchError(handleError);
604
    await idle();
605
    await Future<void>.microtask(() { binding.handleDrawFrame(); }).catchError(handleError);
606 607 608
    await idle();

    if (caughtException != null) {
609
      throw caughtException as Object;
610 611 612
    }
  }

613
  @override
614
  Future<int> pumpAndSettle([
615 616
    Duration duration = const Duration(milliseconds: 100),
    EnginePhase phase = EnginePhase.sendSemanticsUpdate,
617
    Duration timeout = const Duration(minutes: 10),
618
  ]) {
619
    assert(duration != null);
620
    assert(duration > Duration.zero);
621 622
    assert(timeout != null);
    assert(timeout > Duration.zero);
623 624 625 626 627 628 629 630 631 632 633
    assert(() {
      final WidgetsBinding binding = this.binding;
      if (binding is LiveTestWidgetsFlutterBinding &&
          binding.framePolicy == LiveTestWidgetsFlutterBindingFramePolicy.benchmark) {
        throw 'When using LiveTestWidgetsFlutterBindingFramePolicy.benchmark, '
              'hasScheduledFrame is never set to true. This means that pumpAndSettle() '
              'cannot be used, because it has no way to know if the application has '
              'stopped registering new frames.';
      }
      return true;
    }());
634
    return TestAsyncUtils.guard<int>(() async {
635
      final DateTime endTime = binding.clock.fromNowBy(timeout);
636
      int count = 0;
637
      do {
638 639
        if (binding.clock.now().isAfter(endTime))
          throw FlutterError('pumpAndSettle timed out');
640 641
        await binding.pump(duration, phase);
        count += 1;
642
      } while (binding.hasScheduledFrame);
643 644
      return count;
    });
645 646
  }

647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669
  /// Repeatedly pump frames that render the `target` widget with a fixed time
  /// `interval` as many as `maxDuration` allows.
  ///
  /// The `maxDuration` argument is required. The `interval` argument defaults to
  /// 16.683 milliseconds (59.94 FPS).
  Future<void> pumpFrames(
    Widget target,
    Duration maxDuration, [
    Duration interval = const Duration(milliseconds: 16, microseconds: 683),
  ]) {
    assert(maxDuration != null);
    // The interval following the last frame doesn't have to be within the fullDuration.
    Duration elapsed = Duration.zero;
    return TestAsyncUtils.guard<void>(() async {
      binding.attachRootWidget(target);
      binding.scheduleFrame();
      while (elapsed < maxDuration) {
        await binding.pump(interval);
        elapsed += interval;
      }
    });
  }

670 671 672 673 674 675 676 677 678 679 680 681 682 683
  /// Simulates restoring the state of the widget tree after the application
  /// is restarted.
  ///
  /// The method grabs the current serialized restoration data from the
  /// [RestorationManager], takes down the widget tree to destroy all in-memory
  /// state, and then restores the widget tree from the serialized restoration
  /// data.
  Future<void> restartAndRestore() async {
    assert(
      binding.restorationManager.debugRootBucketAccessed,
      'The current widget tree did not inject the root bucket of the RestorationManager and '
      'therefore no restoration data has been collected to restore from. Did you forget to wrap '
      'your widget tree in a RootRestorationScope?',
    );
684
    final Widget widget = (binding.renderViewElement! as RenderObjectToWidgetElement<RenderObject>).widget.child!;
685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716
    final TestRestorationData restorationData = binding.restorationManager.restorationData;
    runApp(Container(key: UniqueKey()));
    await pump();
    binding.restorationManager.restoreFrom(restorationData);
    return pumpWidget(widget);
  }

  /// Retrieves the current restoration data from the [RestorationManager].
  ///
  /// The returned [TestRestorationData] describes the current state of the
  /// widget tree under test and can be provided to [restoreFrom] to restore
  /// the widget tree to the state described by this data.
  Future<TestRestorationData> getRestorationData() async {
    assert(
      binding.restorationManager.debugRootBucketAccessed,
      'The current widget tree did not inject the root bucket of the RestorationManager and '
      'therefore no restoration data has been collected. Did you forget to wrap your widget tree '
      'in a RootRestorationScope?',
    );
    return binding.restorationManager.restorationData;
  }

  /// Restores the widget tree under test to the state described by the
  /// provided [TestRestorationData].
  ///
  /// The data provided to this method is usually obtained from
  /// [getRestorationData].
  Future<void> restoreFrom(TestRestorationData data) {
    binding.restorationManager.restoreFrom(data);
    return pump();
  }

717 718 719 720 721 722 723 724 725 726 727 728 729 730
  /// Runs a [callback] that performs real asynchronous work.
  ///
  /// This is intended for callers who need to call asynchronous methods where
  /// the methods spawn isolates or OS threads and thus cannot be executed
  /// synchronously by calling [pump].
  ///
  /// If callers were to run these types of asynchronous tasks directly in
  /// their test methods, they run the possibility of encountering deadlocks.
  ///
  /// If [callback] completes successfully, this will return the future
  /// returned by [callback].
  ///
  /// If [callback] completes with an error, the error will be caught by the
  /// Flutter framework and made available via [takeException], and this method
731
  /// will return a future that completes with `null`.
732 733 734 735 736
  ///
  /// Re-entrant calls to this method are not allowed; callers of this method
  /// are required to wait for the returned future to complete before calling
  /// this method again. Attempts to do otherwise will result in a
  /// [TestFailure] error being thrown.
737 738 739 740 741 742 743 744 745 746 747 748
  ///
  /// If your widget test hangs and you are using [runAsync], chances are your
  /// code depends on the result of a task that did not complete. Fake async
  /// environment is unable to resolve a future that was created in [runAsync].
  /// If you observe such behavior or flakiness, you have a number of options:
  ///
  /// * Consider restructuring your code so you do not need [runAsync]. This is
  ///   the optimal solution as widget tests are designed to run in fake async
  ///   environment.
  ///
  /// * Expose a [Future] in your application code that signals the readiness of
  ///   your widget tree, then await that future inside [callback].
749
  Future<T?> runAsync<T>(
750
    Future<T> callback(), {
751
    Duration additionalTime = const Duration(milliseconds: 1000),
752
  }) => binding.runAsync<T?>(callback, additionalTime: additionalTime);
753

754
  /// Whether there are any any transient callbacks scheduled.
755 756
  ///
  /// This essentially checks whether all animations have completed.
757 758 759 760 761 762 763 764 765 766 767
  ///
  /// See also:
  ///
  ///  * [pumpAndSettle], which essentially calls [pump] until there are no
  ///    scheduled frames.
  ///  * [SchedulerBinding.transientCallbackCount], which is the value on which
  ///    this is based.
  ///  * [SchedulerBinding.hasScheduledFrame], which is true whenever a frame is
  ///    pending. [SchedulerBinding.hasScheduledFrame] is made true when a
  ///    widget calls [State.setState], even if there are no transient callbacks
  ///    scheduled. This is what [pumpAndSettle] uses.
768 769
  bool get hasRunningAnimations => binding.transientCallbackCount > 0;

770
  @override
771
  HitTestResult hitTestOnBinding(Offset location) {
772
    assert(location != null);
773 774 775 776
    location = binding.localToGlobal(location);
    return super.hitTestOnBinding(location);
  }

777
  @override
778
  Future<void> sendEventToBinding(PointerEvent event) {
779
    return TestAsyncUtils.guard<void>(() async {
780
      binding.handlePointerEvent(event, source: TestBindingEventSource.test);
781 782 783
    });
  }

784 785 786 787
  /// Handler for device events caught by the binding in live test mode.
  @override
  void dispatchEvent(PointerEvent event, HitTestResult result) {
    if (event is PointerDownEvent) {
788 789 790 791
      final RenderObject innerTarget = result.path
        .map((HitTestEntry candidate) => candidate.target)
        .whereType<RenderObject>()
        .first;
792 793
      final Element? innerTargetElement = collectAllElementsFrom(
        binding.renderViewElement!,
794
        skipOffstage: true,
795 796
      ).cast<Element?>().lastWhere(
        (Element? element) => element!.renderObject == innerTarget,
797 798 799 800 801 802
        orElse: () => null,
      );
      if (innerTargetElement == null) {
        debugPrint('No widgets found at ${binding.globalToLocal(event.position)}.');
        return;
      }
803 804 805 806 807 808
      final List<Element> candidates = <Element>[];
      innerTargetElement.visitAncestorElements((Element element) {
        candidates.add(element);
        return true;
      });
      assert(candidates.isNotEmpty);
809
      String? descendantText;
810 811 812
      int numberOfWithTexts = 0;
      int numberOfTypes = 0;
      int totalNumber = 0;
813
      debugPrint('Some possible finders for the widgets at ${binding.globalToLocal(event.position)}:');
814
      for (final Element element in candidates) {
815
        if (totalNumber > 13) // an arbitrary number of finders that feels useful without being overwhelming
816
          break;
817 818
        totalNumber += 1; // optimistically assume we'll be able to describe it

819 820
        final Widget widget = element.widget;
        if (widget is Tooltip) {
821 822
          final Iterable<Element> matches = find.byTooltip(widget.message).evaluate();
          if (matches.length == 1) {
823
            debugPrint("  find.byTooltip('${widget.message}')");
824 825 826
            continue;
          }
        }
827

828
        if (widget is Text) {
829
          assert(descendantText == null);
830 831 832
          assert(widget.data != null || widget.textSpan != null);
          final String text = widget.data ?? widget.textSpan!.toPlainText();
          final Iterable<Element> matches = find.text(text).evaluate();
833 834
          descendantText = widget.data;
          if (matches.length == 1) {
835
            debugPrint("  find.text('$text')");
836 837 838 839
            continue;
          }
        }

840
        final Key? key = widget.key;
841
        if (key is ValueKey<dynamic>) {
842
          String? keyLabel;
843 844 845
          if (key is ValueKey<int> ||
              key is ValueKey<double> ||
              key is ValueKey<bool>) {
846
            keyLabel = 'const ${key.runtimeType}(${key.value})';
847
          } else if (key is ValueKey<String>) {
848
            keyLabel = "const Key('${key.value}')";
849 850 851 852
          }
          if (keyLabel != null) {
            final Iterable<Element> matches = find.byKey(key).evaluate();
            if (matches.length == 1) {
853
              debugPrint('  find.byKey($keyLabel)');
854 855 856 857 858
              continue;
            }
          }
        }

859
        if (!_isPrivate(widget.runtimeType)) {
860
          if (numberOfTypes < 5) {
861
            final Iterable<Element> matches = find.byType(widget.runtimeType).evaluate();
862
            if (matches.length == 1) {
863
              debugPrint('  find.byType(${widget.runtimeType})');
864 865 866 867 868 869
              numberOfTypes += 1;
              continue;
            }
          }

          if (descendantText != null && numberOfWithTexts < 5) {
870
            final Iterable<Element> matches = find.widgetWithText(widget.runtimeType, descendantText).evaluate();
871
            if (matches.length == 1) {
872
              debugPrint("  find.widgetWithText(${widget.runtimeType}, '$descendantText')");
873 874 875 876 877 878 879 880 881
              numberOfWithTexts += 1;
              continue;
            }
          }
        }

        if (!_isPrivate(element.runtimeType)) {
          final Iterable<Element> matches = find.byElementType(element.runtimeType).evaluate();
          if (matches.length == 1) {
882
            debugPrint('  find.byElementType(${element.runtimeType})');
883 884 885 886 887 888 889
            continue;
          }
        }

        totalNumber -= 1; // if we got here, we didn't actually find something to say about it
      }
      if (totalNumber == 0)
890
        debugPrint('  <could not come up with any unique finders>');
891 892 893 894
    }
  }

  bool _isPrivate(Type type) {
895
    // used above so that we don't suggest matchers for private types
896 897 898
    return '_'.matchAsPrefix(type.toString()) != null;
  }

899 900
  /// Returns the exception most recently caught by the Flutter framework.
  ///
901
  /// See [TestWidgetsFlutterBinding.takeException] for details.
902
  dynamic takeException() {
903
    return binding.takeException();
904 905
  }

906 907
  /// Acts as if the application went idle.
  ///
908 909
  /// Runs all remaining microtasks, including those scheduled as a result of
  /// running them, until there are no more microtasks scheduled.
910
  ///
911 912
  /// Does not run timers. May result in an infinite loop or run out of memory
  /// if microtasks continue to recursively schedule new microtasks.
913 914
  Future<void> idle() {
    return TestAsyncUtils.guard<void>(() => binding.idle());
915
  }
916

917
  Set<Ticker>? _tickers;
918 919 920

  @override
  Ticker createTicker(TickerCallback onTick) {
921
    _tickers ??= <_TestTicker>{};
922
    final _TestTicker result = _TestTicker(onTick, _removeTicker);
923
    _tickers!.add(result);
924 925 926 927 928
    return result;
  }

  void _removeTicker(_TestTicker ticker) {
    assert(_tickers != null);
929 930
    assert(_tickers!.contains(ticker));
    _tickers!.remove(ticker);
931 932 933 934 935 936 937 938 939 940 941
  }

  /// Throws an exception if any tickers created by the [WidgetTester] are still
  /// active when the method is called.
  ///
  /// An argument can be specified to provide a string that will be used in the
  /// error message. It should be an adverbial phrase describing the current
  /// situation, such as "at the end of the test".
  void verifyTickersWereDisposed([ String when = 'when none should have been' ]) {
    assert(when != null);
    if (_tickers != null) {
942
      for (final Ticker ticker in _tickers!) {
943
        if (ticker.isActive) {
944 945 946 947 948 949 950 951 952 953
          throw FlutterError.fromParts(<DiagnosticsNode>[
            ErrorSummary('A Ticker was active $when.'),
            ErrorDescription('All Tickers must be disposed.'),
            ErrorHint(
              'Tickers used by AnimationControllers '
              'should be disposed by calling dispose() on the AnimationController itself. '
              'Otherwise, the ticker will leak.'
            ),
            ticker.describeForError('The offending ticker was')
          ]);
954 955 956 957 958 959 960
        }
      }
    }
  }

  void _endOfTestVerifications() {
    verifyTickersWereDisposed('at the end of the test');
961 962 963 964
    _verifySemanticsHandlesWereDisposed();
  }

  void _verifySemanticsHandlesWereDisposed() {
965
    assert(_lastRecordedSemanticsHandles != null);
966
    if (binding.pipelineOwner.debugOutstandingSemanticsHandles > _lastRecordedSemanticsHandles!) {
967 968 969 970 971 972 973 974 975 976 977 978
      throw FlutterError.fromParts(<DiagnosticsNode>[
        ErrorSummary('A SemanticsHandle was active at the end of the test.'),
        ErrorDescription(
          'All SemanticsHandle instances must be disposed by calling dispose() on '
          'the SemanticsHandle.'
        ),
        ErrorHint(
          'If your test uses SemanticsTester, it is '
          'sufficient to call dispose() on SemanticsTester. Otherwise, the '
          'existing handle will leak into another test and alter its behavior.'
        )
      ]);
979
    }
980 981 982
    _lastRecordedSemanticsHandles = null;
  }

983
  int? _lastRecordedSemanticsHandles;
984 985 986

  void _recordNumberOfSemanticsHandles() {
    _lastRecordedSemanticsHandles = binding.pipelineOwner.debugOutstandingSemanticsHandles;
987
  }
988 989 990 991

  /// Returns the TestTextInput singleton.
  ///
  /// Typical app tests will not need to use this value. To add text to widgets
992
  /// like [TextField] or [TextFormField], call [enterText].
993 994
  TestTextInput get testTextInput => binding.testTextInput;

Dan Field's avatar
Dan Field committed
995 996 997 998 999 1000 1001 1002 1003 1004 1005
  /// Ensures that [testTextInput] is registered and [TestTextInput.log] is
  /// reset.
  ///
  /// This is called by the testing framework before test runs, so that if a
  /// previous test has set its own handler on [SystemChannels.textInput], the
  /// [testTextInput] regains control and the log is fresh for the new test.
  /// It should not typically need to be called by tests.
  void resetTestTextInput() {
    testTextInput.resetAndRegister();
  }

1006
  /// Give the text input widget specified by [finder] the focus, as if the
1007 1008
  /// onscreen keyboard had appeared.
  ///
1009 1010
  /// Implies a call to [pump].
  ///
1011 1012
  /// The widget specified by [finder] must be an [EditableText] or have
  /// an [EditableText] descendant. For example `find.byType(TextField)`
1013
  /// or `find.byType(TextFormField)`, or `find.byType(EditableText)`.
1014 1015
  ///
  /// Tests that just need to add text to widgets like [TextField]
1016
  /// or [TextFormField] only need to call [enterText].
1017 1018
  Future<void> showKeyboard(Finder finder) async {
    return TestAsyncUtils.guard<void>(() async {
1019
      final EditableTextState editable = state<EditableTextState>(
1020 1021 1022 1023 1024 1025 1026 1027
        find.descendant(
          of: finder,
          matching: find.byType(EditableText),
          matchRoot: true,
        ),
      );
      binding.focusedEditable = editable;
      await pump();
1028
    });
1029 1030
  }

1031
  /// Give the text input widget specified by [finder] the focus and
1032
  /// enter [text] as if it been provided by the onscreen keyboard.
1033 1034 1035
  ///
  /// The widget specified by [finder] must be an [EditableText] or have
  /// an [EditableText] descendant. For example `find.byType(TextField)`
1036
  /// or `find.byType(TextFormField)`, or `find.byType(EditableText)`.
1037 1038 1039
  ///
  /// To just give [finder] the focus without entering any text,
  /// see [showKeyboard].
1040 1041
  Future<void> enterText(Finder finder, String text) async {
    return TestAsyncUtils.guard<void>(() async {
1042 1043 1044 1045
      await showKeyboard(finder);
      testTextInput.enterText(text);
      await idle();
    });
1046
  }
1047 1048 1049 1050 1051 1052

  /// Makes an effort to dismiss the current page with a Material [Scaffold] or
  /// a [CupertinoPageScaffold].
  ///
  /// Will throw an error if there is no back button in the page.
  Future<void> pageBack() async {
1053
    return TestAsyncUtils.guard<void>(() async {
1054 1055
      Finder backButton = find.byTooltip('Back');
      if (backButton.evaluate().isEmpty) {
1056
        backButton = find.byType(CupertinoNavigationBarBackButton);
1057
      }
1058

1059
      expectSync(backButton, findsOneWidget, reason: 'One back button expected on screen');
1060

1061 1062
      await tap(backButton);
    });
1063
  }
1064 1065
}

1066
typedef _TickerDisposeCallback = void Function(_TestTicker ticker);
1067 1068 1069 1070

class _TestTicker extends Ticker {
  _TestTicker(TickerCallback onTick, this._onDispose) : super(onTick);

1071
  final _TickerDisposeCallback _onDispose;
1072 1073 1074

  @override
  void dispose() {
1075
    _onDispose(this);
1076 1077
    super.dispose();
  }
1078
}