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

5
import 'dart:async';
6

7
import 'package:flutter/cupertino.dart';
8
import 'package:flutter/gestures.dart';
9
import 'package:flutter/material.dart';
10
import 'package:flutter/rendering.dart';
11
import 'package:flutter/scheduler.dart';
12
import 'package:flutter/widgets.dart';
13
import 'package:meta/meta.dart';
14
import 'package:test_api/test_api.dart' as test_package;
15

16
import 'all_elements.dart';
17
import 'binding.dart';
18
import 'controller.dart';
19
import 'finders.dart';
20
import 'matchers.dart';
21
import 'test_async_utils.dart';
22
import 'test_compat.dart';
23
import 'test_text_input.dart';
24

25 26 27
/// Keep users from needing multiple imports to test semantics.
export 'package:flutter/rendering.dart' show SemanticsHandle;

28 29 30
/// 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.
31
export 'package:test_api/test_api.dart' hide
32 33 34 35 36 37
  test,
  group,
  setUpAll,
  tearDownAll,
  setUp,
  tearDown,
38 39 40
  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
41

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

45 46 47 48 49
/// Runs the [callback] inside the Flutter test environment.
///
/// Use this function for testing custom [StatelessWidget]s and
/// [StatefulWidget]s.
///
50 51
/// The callback can be asynchronous (using `async`/`await` or
/// using explicit [Future]s).
52 53 54 55 56 57 58 59
/// Tests using the [AutomatedTestWidgetsFlutterBinding]
/// have a default time out of two seconds,
/// which is automatically increased for some expensive operations,
/// and can also be manually increased by calling
/// [AutomatedTestWidgetsFlutterBinding.addTime].
/// The maximum that this timeout can reach (automatically or manually increased)
/// is defined by the timeout property,
/// which defaults to [TestWidgetsFlutterBinding.defaultTestTimeout].
60
///
61 62 63 64 65
/// If the `enableSemantics` 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.
///
66 67 68 69 70 71
/// 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].
///
72 73 74
/// See also:
///
///  * [AutomatedTestWidgetsFlutterBinding.addTime] to learn more about
75
///    timeout and how to manually increase timeouts.
76
///
77
/// ## Sample code
78
///
79
/// ```dart
80 81 82 83 84
/// testWidgets('MyWidget', (WidgetTester tester) async {
///   await tester.pumpWidget(new MyWidget());
///   await tester.tap(find.text('Save'));
///   expect(find.text('Success'), findsOneWidget);
/// });
85
/// ```
86
@isTest
87 88 89
void testWidgets(
  String description,
  WidgetTesterCallback callback, {
90
  bool skip = false,
91
  test_package.Timeout timeout,
92
  bool semanticsEnabled = false,
93
}) {
94
  final TestWidgetsFlutterBinding binding = TestWidgetsFlutterBinding.ensureInitialized();
95
  final WidgetTester tester = WidgetTester._(binding);
96
  timeout ??= binding.defaultTestTimeout;
97
  test(
98 99
    description,
    () {
100 101 102 103
      SemanticsHandle semanticsHandle;
      if (semanticsEnabled == true) {
        semanticsHandle = tester.ensureSemantics();
      }
104
      tester._recordNumberOfSemanticsHandles();
105 106
      test_package.addTearDown(binding.postTest);
      return binding.runTest(
107 108 109 110
        () async {
          await callback(tester);
          semanticsHandle?.dispose();
        },
111 112 113 114 115
        tester._endOfTestVerifications,
        description: description ?? '',
      );
    },
    skip: skip,
116
    timeout: timeout,
117
  );
118 119 120 121 122 123 124 125 126 127 128 129 130
}

/// 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
131 132 133 134
/// 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!
135 136
///
/// Benchmarks must not be run in checked mode. To avoid this, this
137
/// function will print a big message if it is run in checked mode.
138 139 140 141
///
/// Example:
///
///     main() async {
142
///       assert(false); // fail in checked mode
143 144
///       await benchmarkWidgets((WidgetTester tester) async {
///         await tester.pumpWidget(new MyWidget());
145 146
///         final Stopwatch timer = new Stopwatch()..start();
///         for (int index = 0; index < 10000; index += 1) {
147 148
///           await tester.tap(find.text('Tap me'));
///           await tester.pump();
149 150
///         }
///         timer.stop();
151
///         debugPrint('Time taken: ${timer.elapsedMilliseconds}ms');
152 153 154
///       });
///       exit(0);
///     }
155
Future<void> benchmarkWidgets(WidgetTesterCallback callback) {
156 157 158 159 160 161 162 163 164
  assert(() {
    print('┏╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍┓');
    print('┇ ⚠ THIS BENCHMARK IS BEING RUN WITH ASSERTS ENABLED ⚠  ┇');
    print('┡╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍┦');
    print('│                                                       │');
    print('│  Numbers obtained from a benchmark while asserts are  │');
    print('│  enabled will not accurately reflect the performance  │');
    print('│  that will be experienced by end users using release  ╎');
    print('│  builds. Benchmarks should be run using this command  ┆');
165
    print('│  line:  flutter run --release benchmark.dart          ┊');
166 167 168
    print('│                                                        ');
    print('└─────────────────────────────────────────────────╌┄┈  🐢');
    return true;
169
  }());
170
  final TestWidgetsFlutterBinding binding = TestWidgetsFlutterBinding.ensureInitialized();
171
  assert(binding is! AutomatedTestWidgetsFlutterBinding);
172
  final WidgetTester tester = WidgetTester._(binding);
173
  tester._recordNumberOfSemanticsHandles();
174 175 176
  return binding.runTest(
    () => callback(tester),
    tester._endOfTestVerifications,
177
  ) ?? Future<void>.value();
178
}
179

180 181 182 183 184
/// 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.
185 186 187 188
///
/// See also:
///
///  * [expectLater] for use with asynchronous matchers.
189 190 191
void expect(
  dynamic actual,
  dynamic matcher, {
192
  String reason,
Ian Hickson's avatar
Ian Hickson committed
193
  dynamic skip, // true or a String
194 195
}) {
  TestAsyncUtils.guardSync();
Ian Hickson's avatar
Ian Hickson committed
196
  test_package.expect(actual, matcher, reason: reason, skip: skip);
197 198 199 200 201 202 203 204 205 206 207
}

/// 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.
208 209 210
void expectSync(
  dynamic actual,
  dynamic matcher, {
211 212
  String reason,
}) {
213
  test_package.expect(actual, matcher, reason: reason);
214 215
}

216 217 218 219 220 221 222 223
/// 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.
224 225 226
Future<void> expectLater(
  dynamic actual,
  dynamic matcher, {
227 228 229
  String reason,
  dynamic skip, // true or a String
}) {
230 231 232
  // 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();
233 234
  return test_package.expectLater(actual, matcher, reason: reason, skip: skip)
           .then<void>((dynamic value) => null);
235 236
}

237
/// Class that programmatically interacts with widgets and the test environment.
238 239 240 241
///
/// 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 {
242 243 244 245
  WidgetTester._(TestWidgetsFlutterBinding binding) : super(binding) {
    if (binding is LiveTestWidgetsFlutterBinding)
      binding.deviceEventDispatcher = this;
  }
246

247 248 249
  /// The binding instance used by the testing framework.
  @override
  TestWidgetsFlutterBinding get binding => super.binding;
250 251 252

  /// Renders the UI from the given [widget].
  ///
253 254 255 256
  /// 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.
257 258 259 260
  ///
  /// 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.
261
  ///
262 263 264 265 266 267 268 269 270 271 272 273 274
  /// 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].
  ///
  /// {@tool sample}
  /// ```dart
  /// testWidgets('MyWidget asserts invalid bounds', (WidgetTester tester) async {
  ///   await tester.pumpWidget(MyWidget(-1));
  ///   expect(tester.takeException(), isAssertionError); // or isNull, as appropriate.
  /// });
  /// ```
  /// {@end-tool}
  ///
275 276
  /// See also [LiveTestWidgetsFlutterBindingFramePolicy], which affects how
  /// this method works when the test is run with `flutter run`.
277 278
  Future<void> pumpWidget(
    Widget widget, [
279
    Duration duration,
280
    EnginePhase phase = EnginePhase.sendSemanticsUpdate,
281
  ]) {
282
    return TestAsyncUtils.guard<void>(() {
283 284
      binding.attachRootWidget(widget);
      binding.scheduleFrame();
285 286
      return binding.pump(duration, phase);
    });
287 288
  }

289 290 291 292 293
  /// Triggers a frame after `duration` amount of time.
  ///
  /// This makes the framework act as if the application had janked (missed
  /// frames) for `duration` amount of time, and then received a v-sync signal
  /// to paint the application.
294
  ///
295 296
  /// This is a convenience function that just calls
  /// [TestWidgetsFlutterBinding.pump].
297 298 299
  ///
  /// See also [LiveTestWidgetsFlutterBindingFramePolicy], which affects how
  /// this method works when the test is run with `flutter run`.
300
  @override
301
  Future<void> pump([
302
    Duration duration,
303
    EnginePhase phase = EnginePhase.sendSemanticsUpdate,
304
  ]) {
305
    return TestAsyncUtils.guard<void>(() => binding.pump(duration, phase));
306
  }
307

308 309 310 311 312 313 314 315 316 317
  /// 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(() {
318 319 320
      final TestWidgetsFlutterBinding widgetsBinding = binding;
      return widgetsBinding is LiveTestWidgetsFlutterBinding &&
              widgetsBinding.framePolicy == LiveTestWidgetsFlutterBindingFramePolicy.benchmark;
321 322 323 324 325
    }());

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

326
    await Future<void>.microtask(() { binding.handleBeginFrame(duration); }).catchError(handleError);
327
    await idle();
328
    await Future<void>.microtask(() { binding.handleDrawFrame(); }).catchError(handleError);
329 330 331 332 333 334 335
    await idle();

    if (caughtException != null) {
      throw caughtException;
    }
  }

336
  /// Repeatedly calls [pump] with the given `duration` until there are no
337 338 339
  /// 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.
340 341 342
  ///
  /// This essentially waits for all animations to have completed.
  ///
343 344 345 346 347 348 349
  /// 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.
350 351 352 353 354 355 356 357 358 359
  ///
  /// 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.
360
  Future<int> pumpAndSettle([
361 362 363 364
    Duration duration = const Duration(milliseconds: 100),
    EnginePhase phase = EnginePhase.sendSemanticsUpdate,
    Duration timeout = const Duration(minutes: 10),
  ]) {
365
    assert(duration != null);
366
    assert(duration > Duration.zero);
367
    assert(timeout != null);
368
    assert(timeout > Duration.zero);
369 370 371 372 373 374 375 376 377 378 379
    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;
    }());
380
    int count = 0;
381
    return TestAsyncUtils.guard<void>(() async {
382
      final DateTime endTime = binding.clock.fromNowBy(timeout);
383
      do {
384
        if (binding.clock.now().isAfter(endTime))
385
          throw FlutterError('pumpAndSettle timed out');
386 387
        await binding.pump(duration, phase);
        count += 1;
388
      } while (binding.hasScheduledFrame);
389
    }).then<int>((_) => count);
390 391
  }

392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411
  /// 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
  /// will return a future that completes will `null`.
  ///
  /// 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.
412 413
  Future<T> runAsync<T>(
    Future<T> callback(), {
414
    Duration additionalTime = const Duration(milliseconds: 1000),
415
  }) => binding.runAsync<T>(callback, additionalTime: additionalTime);
416

417
  /// Whether there are any any transient callbacks scheduled.
418 419
  ///
  /// This essentially checks whether all animations have completed.
420 421 422 423 424 425 426 427 428 429 430
  ///
  /// 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.
431 432
  bool get hasRunningAnimations => binding.transientCallbackCount > 0;

433
  @override
434
  HitTestResult hitTestOnBinding(Offset location) {
435 436 437 438
    location = binding.localToGlobal(location);
    return super.hitTestOnBinding(location);
  }

439
  @override
440 441
  Future<void> sendEventToBinding(PointerEvent event, HitTestResult result) {
    return TestAsyncUtils.guard<void>(() async {
442 443 444 445
      binding.dispatchEvent(event, result, source: TestBindingEventSource.test);
    });
  }

446 447 448 449 450 451
  /// Handler for device events caught by the binding in live test mode.
  @override
  void dispatchEvent(PointerEvent event, HitTestResult result) {
    if (event is PointerDownEvent) {
      final RenderObject innerTarget = result.path.firstWhere(
        (HitTestEntry candidate) => candidate.target is RenderObject,
452 453 454 455 456 457 458 459 460 461 462 463
      ).target;
      final Element innerTargetElement = collectAllElementsFrom(
        binding.renderViewElement,
        skipOffstage: true,
      ).lastWhere(
        (Element element) => element.renderObject == innerTarget,
        orElse: () => null,
      );
      if (innerTargetElement == null) {
        debugPrint('No widgets found at ${binding.globalToLocal(event.position)}.');
        return;
      }
464 465 466 467 468 469 470 471 472 473
      final List<Element> candidates = <Element>[];
      innerTargetElement.visitAncestorElements((Element element) {
        candidates.add(element);
        return true;
      });
      assert(candidates.isNotEmpty);
      String descendantText;
      int numberOfWithTexts = 0;
      int numberOfTypes = 0;
      int totalNumber = 0;
474
      debugPrint('Some possible finders for the widgets at ${binding.globalToLocal(event.position)}:');
475
      for (Element element in candidates) {
476
        if (totalNumber > 13) // an arbitrary number of finders that feels useful without being overwhelming
477
          break;
478 479 480 481 482 483 484 485 486 487
        totalNumber += 1; // optimistically assume we'll be able to describe it

        if (element.widget is Tooltip) {
          final Tooltip widget = element.widget;
          final Iterable<Element> matches = find.byTooltip(widget.message).evaluate();
          if (matches.length == 1) {
            debugPrint('  find.byTooltip(\'${widget.message}\')');
            continue;
          }
        }
488 489 490 491 492 493 494

        if (element.widget is Text) {
          assert(descendantText == null);
          final Text widget = element.widget;
          final Iterable<Element> matches = find.text(widget.data).evaluate();
          descendantText = widget.data;
          if (matches.length == 1) {
495
            debugPrint('  find.text(\'${widget.data}\')');
496 497 498 499 500 501 502
            continue;
          }
        }

        if (element.widget.key is ValueKey<dynamic>) {
          final ValueKey<dynamic> key = element.widget.key;
          String keyLabel;
503 504 505
          if (key is ValueKey<int> ||
              key is ValueKey<double> ||
              key is ValueKey<bool>) {
506 507
            keyLabel = 'const ${element.widget.key.runtimeType}(${key.value})';
          } else if (key is ValueKey<String>) {
508
            keyLabel = 'const Key(\'${key.value}\')';
509 510 511 512
          }
          if (keyLabel != null) {
            final Iterable<Element> matches = find.byKey(key).evaluate();
            if (matches.length == 1) {
513
              debugPrint('  find.byKey($keyLabel)');
514 515 516 517 518 519 520 521 522
              continue;
            }
          }
        }

        if (!_isPrivate(element.widget.runtimeType)) {
          if (numberOfTypes < 5) {
            final Iterable<Element> matches = find.byType(element.widget.runtimeType).evaluate();
            if (matches.length == 1) {
523
              debugPrint('  find.byType(${element.widget.runtimeType})');
524 525 526 527 528 529 530 531
              numberOfTypes += 1;
              continue;
            }
          }

          if (descendantText != null && numberOfWithTexts < 5) {
            final Iterable<Element> matches = find.widgetWithText(element.widget.runtimeType, descendantText).evaluate();
            if (matches.length == 1) {
532
              debugPrint('  find.widgetWithText(${element.widget.runtimeType}, \'$descendantText\')');
533 534 535 536 537 538 539 540 541
              numberOfWithTexts += 1;
              continue;
            }
          }
        }

        if (!_isPrivate(element.runtimeType)) {
          final Iterable<Element> matches = find.byElementType(element.runtimeType).evaluate();
          if (matches.length == 1) {
542
            debugPrint('  find.byElementType(${element.runtimeType})');
543 544 545 546 547 548 549
            continue;
          }
        }

        totalNumber -= 1; // if we got here, we didn't actually find something to say about it
      }
      if (totalNumber == 0)
550
        debugPrint('  <could not come up with any unique finders>');
551 552 553 554
    }
  }

  bool _isPrivate(Type type) {
555
    // used above so that we don't suggest matchers for private types
556 557 558
    return '_'.matchAsPrefix(type.toString()) != null;
  }

559 560
  /// Returns the exception most recently caught by the Flutter framework.
  ///
561
  /// See [TestWidgetsFlutterBinding.takeException] for details.
562
  dynamic takeException() {
563
    return binding.takeException();
564 565
  }

566 567
  /// Acts as if the application went idle.
  ///
568 569
  /// Runs all remaining microtasks, including those scheduled as a result of
  /// running them, until there are no more microtasks scheduled.
570
  ///
571 572
  /// Does not run timers. May result in an infinite loop or run out of memory
  /// if microtasks continue to recursively schedule new microtasks.
573 574
  Future<void> idle() {
    return TestAsyncUtils.guard<void>(() => binding.idle());
575
  }
576 577 578 579 580

  Set<Ticker> _tickers;

  @override
  Ticker createTicker(TickerCallback onTick) {
581
    _tickers ??= <_TestTicker>{};
582
    final _TestTicker result = _TestTicker(onTick, _removeTicker);
583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603
    _tickers.add(result);
    return result;
  }

  void _removeTicker(_TestTicker ticker) {
    assert(_tickers != null);
    assert(_tickers.contains(ticker));
    _tickers.remove(ticker);
  }

  /// 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) {
      for (Ticker ticker in _tickers) {
        if (ticker.isActive) {
604
          throw FlutterError(
605 606 607 608 609 610 611 612 613 614 615 616 617
            'A Ticker was active $when.\n'
            'All Tickers must be disposed. Tickers used by AnimationControllers '
            'should be disposed by calling dispose() on the AnimationController itself. '
            'Otherwise, the ticker will leak.\n'
            'The offending ticker was: ${ticker.toString(debugIncludeStack: true)}'
          );
        }
      }
    }
  }

  void _endOfTestVerifications() {
    verifyTickersWereDisposed('at the end of the test');
618 619 620 621
    _verifySemanticsHandlesWereDisposed();
  }

  void _verifySemanticsHandlesWereDisposed() {
622 623
    assert(_lastRecordedSemanticsHandles != null);
    if (binding.pipelineOwner.debugOutstandingSemanticsHandles > _lastRecordedSemanticsHandles) {
624
      throw FlutterError(
625 626 627 628 629 630 631
        'A SemanticsHandle was active at the end of the test.\n'
        'All SemanticsHandle instances must be disposed by calling dispose() on '
        'the SemanticsHandle. 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.'
      );
    }
632 633 634 635 636 637 638
    _lastRecordedSemanticsHandles = null;
  }

  int _lastRecordedSemanticsHandles;

  void _recordNumberOfSemanticsHandles() {
    _lastRecordedSemanticsHandles = binding.pipelineOwner.debugOutstandingSemanticsHandles;
639
  }
640 641 642 643

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

647
  /// Give the text input widget specified by [finder] the focus, as if the
648 649
  /// onscreen keyboard had appeared.
  ///
650 651
  /// Implies a call to [pump].
  ///
652 653
  /// The widget specified by [finder] must be an [EditableText] or have
  /// an [EditableText] descendant. For example `find.byType(TextField)`
654
  /// or `find.byType(TextFormField)`, or `find.byType(EditableText)`.
655 656
  ///
  /// Tests that just need to add text to widgets like [TextField]
657
  /// or [TextFormField] only need to call [enterText].
658 659
  Future<void> showKeyboard(Finder finder) async {
    return TestAsyncUtils.guard<void>(() async {
660
      final EditableTextState editable = state<EditableTextState>(
661 662 663 664 665 666 667 668
        find.descendant(
          of: finder,
          matching: find.byType(EditableText),
          matchRoot: true,
        ),
      );
      binding.focusedEditable = editable;
      await pump();
669
    });
670 671
  }

672
  /// Give the text input widget specified by [finder] the focus and
673
  /// enter [text] as if it been provided by the onscreen keyboard.
674 675 676
  ///
  /// The widget specified by [finder] must be an [EditableText] or have
  /// an [EditableText] descendant. For example `find.byType(TextField)`
677
  /// or `find.byType(TextFormField)`, or `find.byType(EditableText)`.
678 679 680
  ///
  /// To just give [finder] the focus without entering any text,
  /// see [showKeyboard].
681 682
  Future<void> enterText(Finder finder, String text) async {
    return TestAsyncUtils.guard<void>(() async {
683 684 685 686
      await showKeyboard(finder);
      testTextInput.enterText(text);
      await idle();
    });
687
  }
688 689 690 691 692 693

  /// 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 {
694
    return TestAsyncUtils.guard<void>(() async {
695 696
      Finder backButton = find.byTooltip('Back');
      if (backButton.evaluate().isEmpty) {
697
        backButton = find.byType(CupertinoNavigationBarBackButton);
698
      }
699

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

702 703
      await tap(backButton);
    });
704
  }
705

706
  /// Attempts to find the [SemanticsNode] of first result from `finder`.
707
  ///
708
  /// If the object identified by the finder doesn't own it's semantic node,
709 710
  /// 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
711 712 713 714
  /// other nodes that have been merged together.
  ///
  /// Will throw a [StateError] if the finder returns more than one element or
  /// if no semantics are found or are not enabled.
715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736
  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) {
      renderObject = renderObject?.parent;
      result = renderObject?.debugSemantics;
    }
    if (result == null)
      throw StateError('No Semantics data found.');
    return result;
  }

737 738 739 740 741 742
  /// 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();
  }
743 744 745 746 747 748

  /// 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.
  ///
  /// Shorthand for `Scrollable.ensureVisible(tester.element(finder))`
  Future<void> ensureVisible(Finder finder) => Scrollable.ensureVisible(element(finder));
749 750
}

751
typedef _TickerDisposeCallback = void Function(_TestTicker ticker);
752 753 754 755 756 757 758 759 760 761 762 763

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

  _TickerDisposeCallback _onDispose;

  @override
  void dispose() {
    if (_onDispose != null)
      _onDispose(this);
    super.dispose();
  }
764
}