controller.dart [flutter/packages/flutter_test/lib/src/controller.dart]

1	// Copyright 2014 The Flutter Authors. All rights reserved.
2	// Use of this source code is governed by a BSD-style license that can be
3	// found in the LICENSE file.
4
5	/// @docImport 'dart:io';
6	///
7	/// @docImport 'package:flutter/scheduler.dart';
8	/// @docImport 'package:flutter_driver/flutter_driver.dart';
9	///
10	/// @docImport 'binding.dart';
11	/// @docImport 'finders.dart';
12	/// @docImport 'matchers.dart';
13	/// @docImport 'widget_tester.dart';
14	library;
15
16	import 'package:clock/clock.dart';
17	import 'package:flutter/foundation.dart';
18	import 'package:flutter/gestures.dart';
19	import 'package:flutter/rendering.dart';
20	import 'package:flutter/services.dart';
21	import 'package:flutter/widgets.dart';
22
23	import 'event_simulation.dart';
24	import 'finders.dart' as finders;
25	import 'test_async_utils.dart';
26	import 'test_pointer.dart';
27	import 'tree_traversal.dart';
28	import 'window.dart';
29
30	/// The default drag touch slop used to break up a large drag into multiple
31	/// smaller moves.
32	///
33	/// This value must be greater than [kTouchSlop].
34	const double kDragSlopDefault = `20.0`;
35
36	// Finds the end index (exclusive) of the span at `startIndex`, or `endIndex` if
37	// there are no other spans between `startIndex` and `endIndex`.
38	// The InlineSpan protocol doesn't expose the length of the span so we'll
39	// have to iterate through the whole range.
40	(InlineSpan, int)? _findEndOfSpan(InlineSpan rootSpan, int startIndex, int endIndex) {
41	assert(endIndex > startIndex);
42	final InlineSpan? subspan = rootSpan.getSpanForPosition(TextPosition(offset: startIndex));
43	if (subspan == `null`) {
44	return `null`;
45	}
46	int i = startIndex + `1`;
47	while (i < endIndex && rootSpan.getSpanForPosition(TextPosition(offset: i)) == subspan) {
48	i += `1`;
49	}
50	return (subspan, i);
51	}
52
53	// Examples can assume:
54	// typedef MyWidget = Placeholder;
55
56	/// Class that programmatically interacts with the [Semantics] tree.
57	///
58	/// Allows for testing of the [Semantics] tree, which is used by assistive
59	/// technology, search engines, and other analysis software to determine the
60	/// meaning of an application.
61	///
62	/// Should be accessed through [WidgetController.semantics]. If no custom
63	/// implementation is provided, a default [SemanticsController] will be created.
64	class SemanticsController {
65	/// Creates a [SemanticsController] that uses the given binding. Will be
66	/// automatically created as part of instantiating a [WidgetController], but
67	/// a custom implementation can be passed via the [WidgetController] constructor.
68	SemanticsController._(this._controller);
69
70	static final int _scrollingActions =
71	SemanticsAction.scrollUp.index \|
72	SemanticsAction.scrollDown.index \|
73	SemanticsAction.scrollLeft.index \|
74	SemanticsAction.scrollRight.index \|
75	SemanticsAction.scrollToOffset.index;
76
77	/// Based on Android's FOCUSABLE_FLAGS. See [flutter/engine/AccessibilityBridge.java](https://github.com/flutter/flutter/blob/main/engine/src/flutter/shell/platform/android/io/flutter/view/AccessibilityBridge.java).
78	static final int _importantFlagsForAccessibility =
79	SemanticsFlag.hasCheckedState.index \|
80	SemanticsFlag.hasToggledState.index \|
81	SemanticsFlag.hasEnabledState.index \|
82	SemanticsFlag.isButton.index \|
83	SemanticsFlag.isTextField.index \|
84	SemanticsFlag.isFocusable.index \|
85	SemanticsFlag.isSlider.index \|
86	SemanticsFlag.isInMutuallyExclusiveGroup.index;
87
88	final WidgetController _controller;
89
90	/// Attempts to find the [SemanticsNode] of first result from `finder`.
91	///
92	/// If the object identified by the finder doesn't own its semantic node,
93	/// this will return the semantics data of the first ancestor with semantics.
94	/// The ancestor's semantic data will include the child's as well as
95	/// other nodes that have been merged together.
96	///
97	/// If the [SemanticsNode] of the object identified by the finder is
98	/// force-merged into an ancestor (e.g. via the [MergeSemantics] widget)
99	/// the node into which it is merged is returned. That node will include
100	/// all the semantics information of the nodes merged into it.
101	///
102	/// Will throw a [StateError] if the finder returns more than one element or
103	/// if no semantics are found or are not enabled.
104	SemanticsNode find(finders.FinderBase<Element> finder) {
105	TestAsyncUtils.guardSync();
106	final Iterable<Element> candidates = finder.evaluate();
107	if (candidates.isEmpty) {
108	throw StateError('Finder returned no matching elements.');
109	}
110	if (candidates.length > `1`) {
111	throw StateError('Finder returned more than one element.');
112	}
113	final Element element = candidates.single;
114	RenderObject? renderObject = element.findRenderObject();
115	SemanticsNode? result = renderObject?.debugSemantics;
116	while (renderObject != `null` && (result == `null` \|\| result.isMergedIntoParent)) {
117	renderObject = renderObject.parent;
118	result = renderObject?.debugSemantics;
119	}
120	if (result == `null`) {
121	throw StateError('No Semantics data found.');
122	}
123	return result;
124	}
125
126	/// Simulates a traversal of the currently visible semantics tree as if by
127	/// assistive technologies.
128	///
129	/// Starts at the node for `startNode`. If `startNode` is not provided, then
130	/// the traversal begins with the first accessible node in the tree. If
131	/// `startNode` finds zero elements or more than one element, a [StateError]
132	/// will be thrown.
133	///
134	/// Ends at the node for `endNode`, inclusive. If `endNode` is not provided,
135	/// then the traversal ends with the last accessible node in the currently
136	/// available tree. If `endNode` finds zero elements or more than one element,
137	/// a [StateError] will be thrown.
138	///
139	/// If provided, the nodes for `endNode` and `startNode` must be part of the
140	/// same semantics tree, i.e. they must be part of the same view.
141	///
142	/// If neither `startNode` or `endNode` is provided, `view` can be provided to
143	/// specify the semantics tree to traverse. If `view` is left unspecified,
144	/// [WidgetTester.view] is traversed by default.
145	///
146	/// Since the order is simulated, edge cases that differ between platforms
147	/// (such as how the last visible item in a scrollable list is handled) may be
148	/// inconsistent with platform behavior, but are expected to be sufficient for
149	/// testing order, availability to assistive technologies, and interactions.
150	///
151	/// ## Sample Code
152	///
153	/// ```dart
154	/// testWidgets('MyWidget', (WidgetTester tester) async {
155	/// await tester.pumpWidget(const MyWidget());
156	///
157	/// expect(
158	/// tester.semantics.simulatedAccessibilityTraversal(),
159	/// containsAllInOrder(<Matcher>[
160	/// containsSemantics(label: 'My Widget'),
161	/// containsSemantics(label: 'is awesome!', isChecked: true),
162	/// ]),
163	/// );
164	/// });
165	/// ```
166	///
167	/// See also:
168	///
169	/// [containsSemantics] and [matchesSemantics], which can be used to match*
170	/// against a single node in the traversal.
171	/// [containsAllInOrder], which can be given an [Iterable<Matcher>] to fuzzy*
172	/// match the order allowing extra nodes before after and between matching
173	/// parts of the traversal.
174	/// [orderedEquals], which can be given an [Iterable<Matcher>] to exactly*
175	/// match the order of the traversal.
176	Iterable<SemanticsNode> simulatedAccessibilityTraversal({
177	@Deprecated(
178	'Use startNode instead. '
179	'This method was originally created before semantics finders were available. '
180	'Semantics finders avoid edge cases where some nodes are not discoverable by widget finders and should be preferred for semantics testing. '
181	'This feature was deprecated after v3.15.0-15.2.pre.',
182	)
183	finders.FinderBase<Element>? start,
184	@Deprecated(
185	'Use endNode instead. '
186	'This method was originally created before semantics finders were available. '
187	'Semantics finders avoid edge cases where some nodes are not discoverable by widget finders and should be preferred for semantics testing. '
188	'This feature was deprecated after v3.15.0-15.2.pre.',
189	)
190	finders.FinderBase<Element>? end,
191	finders.FinderBase<SemanticsNode>? startNode,
192	finders.FinderBase<SemanticsNode>? endNode,
193	FlutterView? view,
194	}) {
195	TestAsyncUtils.guardSync();
196	assert(
197	start == `null` \|\| startNode == `null`,
198	'Cannot provide both start and startNode. Prefer startNode as start is deprecated.',
199	);
200	assert(
201	end == `null` \|\| endNode == `null`,
202	'Cannot provide both end and endNode. Prefer endNode as end is deprecated.',
203	);
204
205	FlutterView? startView;
206	if (start != `null`) {
207	startView = _controller.viewOf(start);
208	if (view != `null` && startView != view) {
209	throw StateError(
210	'The start node is not part of the provided view.\n'
211	'Finder: ${start.toString(describeSelf: `true`)}\n'
212	'View of start node: $startView\n'
213	'Specified view: $view',
214	);
215	}
216	} else if (startNode != `null`) {
217	final SemanticsOwner owner = startNode.evaluate().single.owner!;
218	final RenderView renderView = _controller.binding.renderViews.firstWhere(
219	(RenderView render) => render.owner!.semanticsOwner == owner,
220	);
221	startView = renderView.flutterView;
222	if (view != `null` && startView != view) {
223	throw StateError(
224	'The start node is not part of the provided view.\n'
225	'Finder: ${startNode.toString(describeSelf: `true`)}\n'
226	'View of start node: $startView\n'
227	'Specified view: $view',
228	);
229	}
230	}
231
232	FlutterView? endView;
233	if (end != `null`) {
234	endView = _controller.viewOf(end);
235	if (view != `null` && endView != view) {
236	throw StateError(
237	'The end node is not part of the provided view.\n'
238	'Finder: ${end.toString(describeSelf: `true`)}\n'
239	'View of end node: $endView\n'
240	'Specified view: $view',
241	);
242	}
243	} else if (endNode != `null`) {
244	final SemanticsOwner owner = endNode.evaluate().single.owner!;
245	final RenderView renderView = _controller.binding.renderViews.firstWhere(
246	(RenderView render) => render.owner!.semanticsOwner == owner,
247	);
248	endView = renderView.flutterView;
249	if (view != `null` && endView != view) {
250	throw StateError(
251	'The end node is not part of the provided view.\n'
252	'Finder: ${endNode.toString(describeSelf: `true`)}\n'
253	'View of end node: $endView\n'
254	'Specified view: $view',
255	);
256	}
257	}
258
259	if (endView != `null` && startView != `null` && endView != startView) {
260	throw StateError(
261	'The start and end node are in different views.\n'
262	'Start finder: ${start!.toString(describeSelf: `true`)}\n'
263	'End finder: ${end!.toString(describeSelf: `true`)}\n'
264	'View of start node: $startView\n'
265	'View of end node: $endView',
266	);
267	}
268
269	final FlutterView actualView = view ?? startView ?? endView ?? _controller.view;
270	final RenderView renderView = _controller.binding.renderViews.firstWhere(
271	(RenderView r) => r.flutterView == actualView,
272	);
273
274	final List<SemanticsNode> traversal = <SemanticsNode>[];
275	_accessibilityTraversal(renderView.owner!.semanticsOwner!.rootSemanticsNode!, traversal);
276
277	// Setting the range
278	SemanticsNode? node;
279	String? errorString;
280
281	int startIndex;
282	if (start != `null`) {
283	node = find(start);
284	startIndex = traversal.indexOf(node);
285	errorString = start.toString(describeSelf: `true`);
286	} else if (startNode != `null`) {
287	node = startNode.evaluate().single;
288	startIndex = traversal.indexOf(node);
289	errorString = startNode.toString(describeSelf: `true`);
290	} else {
291	startIndex = `0`;
292	}
293	if (startIndex == -`1`) {
294	throw StateError(
295	'The expected starting node was not found.\n'
296	'Finder: $errorString\n\n'
297	'Expected Start Node: $node\n\n'
298	'Traversal: [\n ${traversal.join('\n ')}\n]',
299	);
300	}
301
302	int? endIndex;
303	if (end != `null`) {
304	node = find(end);
305	endIndex = traversal.indexOf(node);
306	errorString = end.toString(describeSelf: `true`);
307	} else if (endNode != `null`) {
308	node = endNode.evaluate().single;
309	endIndex = traversal.indexOf(node);
310	errorString = endNode.toString(describeSelf: `true`);
311	}
312	if (endIndex == -`1`) {
313	throw StateError(
314	'The expected ending node was not found.\n'
315	'Finder: $errorString\n\n'
316	'Expected End Node: $node\n\n'
317	'Traversal: [\n ${traversal.join('\n ')}\n]',
318	);
319	}
320	endIndex ??= traversal.length - `1`;
321
322	return traversal.getRange(startIndex, endIndex + `1`);
323	}
324
325	/// Recursive depth first traversal of the specified `node`, adding nodes
326	/// that are important for semantics to the `traversal` list.
327	void _accessibilityTraversal(SemanticsNode node, List<SemanticsNode> traversal) {
328	if (_isImportantForAccessibility(node)) {
329	traversal.add(node);
330	}
331
332	final List<SemanticsNode> children = node.debugListChildrenInOrder(
333	DebugSemanticsDumpOrder.traversalOrder,
334	);
335	for (final SemanticsNode child in children) {
336	_accessibilityTraversal(child, traversal);
337	}
338	}
339
340	/// Whether or not the node is important for semantics. Should match most cases
341	/// on the platforms, but certain edge cases will be inconsistent.
342	///
343	/// Based on:
344	///
345	/// * [flutter/engine/AccessibilityBridge.java#SemanticsNode.isFocusable()](https://github.com/flutter/flutter/blob/main/engine/src/flutter/shell/platform/android/io/flutter/view/AccessibilityBridge.java#L2641)
346	/// * [flutter/engine/SemanticsObject.mm#SemanticsObject.isAccessibilityElement](https://github.com/flutter/flutter/blob/main/engine/src/flutter/shell/platform/darwin/ios/framework/Source/SemanticsObject.mm#L449)
347	bool _isImportantForAccessibility(SemanticsNode node) {
348	if (node.isMergedIntoParent) {
349	// If this node is merged, all its information are present on an ancestor
350	// node.
351	return `false`;
352	}
353	final SemanticsData data = node.getSemanticsData();
354	// If the node scopes a route, it doesn't matter what other flags/actions it
355	// has, it is _not_ important for accessibility, so we short circuit.
356	if (data.hasFlag(SemanticsFlag.scopesRoute)) {
357	return `false`;
358	}
359
360	final bool hasNonScrollingAction = data.actions & ~_scrollingActions != `0`;
361	if (hasNonScrollingAction) {
362	return `true`;
363	}
364
365	final bool hasImportantFlag = data.flags & _importantFlagsForAccessibility != `0`;
366	if (hasImportantFlag) {
367	return `true`;
368	}
369
370	final bool hasContent = data.label.isNotEmpty \|\| data.value.isNotEmpty \|\| data.hint.isNotEmpty;
371	if (hasContent) {
372	return `true`;
373	}
374
375	return `false`;
376	}
377
378	/// Performs the given [SemanticsAction] on the [SemanticsNode] found by `finder`.
379	///
380	/// If `args` are provided, they will be passed unmodified with the `action`.
381	/// The `checkForAction` argument allows for attempting to perform `action` on
382	/// `node` even if it doesn't report supporting that action. This is useful
383	/// for implicitly supported actions such as [SemanticsAction.showOnScreen].
384	void performAction(
385	finders.FinderBase<SemanticsNode> finder,
386	SemanticsAction action, {
387	Object? args,
388	bool checkForAction = `true`,
389	}) {
390	final SemanticsNode node = finder.evaluate().single;
391	if (checkForAction && !node.getSemanticsData().hasAction(action)) {
392	throw StateError(
393	'The given node does not support $action. If the action is implicitly '
394	'supported or an unsupported action is being tested for this node, '
395	'set `checkForAction` to false.\n'
396	'Node: $node',
397	);
398	}
399
400	node.owner!.performAction(node.id, action, args);
401	}
402
403	/// Performs a [SemanticsAction.tap] action on the [SemanticsNode] found
404	/// by `finder`.
405	///
406	/// Throws a [StateError] if:
407	/// The given `finder` returns zero or more than one result.*
408	/// The [SemanticsNode] found with `finder` does not support*
409	/// [SemanticsAction.tap].
410	void tap(finders.FinderBase<SemanticsNode> finder) {
411	performAction(finder, SemanticsAction.tap);
412	}
413
414	/// Performs a [SemanticsAction.longPress] action on the [SemanticsNode] found
415	/// by `finder`.
416	///
417	/// Throws a [StateError] if:
418	/// The given `finder` returns zero or more than one result.*
419	/// The [SemanticsNode] found with `finder` does not support*
420	/// [SemanticsAction.longPress].
421	void longPress(finders.FinderBase<SemanticsNode> finder) {
422	performAction(finder, SemanticsAction.longPress);
423	}
424
425	/// Performs a [SemanticsAction.scrollLeft] action on the [SemanticsNode]
426	/// found by `scrollable` or the first scrollable node in the default
427	/// semantics tree if no `scrollable` is provided.
428	///
429	/// Throws a [StateError] if:
430	/// The given `scrollable` returns zero or more than one result.*
431	/// The [SemanticsNode] found with `scrollable` does not support*
432	/// [SemanticsAction.scrollLeft].
433	void scrollLeft({finders.FinderBase<SemanticsNode>? scrollable}) {
434	performAction(scrollable ?? finders.find.semantics.scrollable(), SemanticsAction.scrollLeft);
435	}
436
437	/// Performs a [SemanticsAction.scrollRight] action on the [SemanticsNode]
438	/// found by `scrollable` or the first scrollable node in the default
439	/// semantics tree if no `scrollable` is provided.
440	///
441	/// Throws a [StateError] if:
442	/// The given `scrollable` returns zero or more than one result.*
443	/// The [SemanticsNode] found with `scrollable` does not support*
444	/// [SemanticsAction.scrollRight].
445	void scrollRight({finders.FinderBase<SemanticsNode>? scrollable}) {
446	performAction(scrollable ?? finders.find.semantics.scrollable(), SemanticsAction.scrollRight);
447	}
448
449	/// Performs a [SemanticsAction.scrollUp] action on the [SemanticsNode] found
450	/// by `scrollable` or the first scrollable node in the default semantics
451	/// tree if no `scrollable` is provided.
452	///
453	/// Throws a [StateError] if:
454	/// The given `scrollable` returns zero or more than one result.*
455	/// The [SemanticsNode] found with `scrollable` does not support*
456	/// [SemanticsAction.scrollUp].
457	void scrollUp({finders.FinderBase<SemanticsNode>? scrollable}) {
458	performAction(scrollable ?? finders.find.semantics.scrollable(), SemanticsAction.scrollUp);
459	}
460
461	/// Performs a [SemanticsAction.scrollDown] action on the [SemanticsNode]
462	/// found by `scrollable` or the first scrollable node in the default
463	/// semantics tree if no `scrollable` is provided.
464	///
465	/// Throws a [StateError] if:
466	/// The given `scrollable` returns zero or more than one result.*
467	/// The [SemanticsNode] found with `scrollable` does not support*
468	/// [SemanticsAction.scrollDown].
469	void scrollDown({finders.FinderBase<SemanticsNode>? scrollable}) {
470	performAction(scrollable ?? finders.find.semantics.scrollable(), SemanticsAction.scrollDown);
471	}
472
473	/// Performs a [SemanticsAction.increase] action on the [SemanticsNode]
474	/// found by `finder`.
475	///
476	/// Throws a [StateError] if:
477	/// The given `finder` returns zero or more than one result.*
478	/// The [SemanticsNode] found with `finder` does not support*
479	/// [SemanticsAction.increase].
480	void increase(finders.FinderBase<SemanticsNode> finder) {
481	performAction(finder, SemanticsAction.increase);
482	}
483
484	/// Performs a [SemanticsAction.decrease] action on the [SemanticsNode]
485	/// found by `finder`.
486	///
487	/// Throws a [StateError] if:
488	/// The given `finder` returns zero or more than one result.*
489	/// The [SemanticsNode] found with `finder` does not support*
490	/// [SemanticsAction.decrease].
491	void decrease(finders.FinderBase<SemanticsNode> finder) {
492	performAction(finder, SemanticsAction.decrease);
493	}
494
495	/// Performs a [SemanticsAction.showOnScreen] action on the [SemanticsNode]
496	/// found by `finder`.
497	///
498	/// Throws a [StateError] if:
499	/// The given `finder` returns zero or more than one result.*
500	/// The [SemanticsNode] found with `finder` does not support*
501	/// [SemanticsAction.showOnScreen].
502	void showOnScreen(finders.FinderBase<SemanticsNode> finder) {
503	performAction(finder, SemanticsAction.showOnScreen, checkForAction: `false`);
504	}
505
506	/// Performs a [SemanticsAction.moveCursorForwardByCharacter] action on the
507	/// [SemanticsNode] found by `finder`.
508	///
509	/// If `shouldModifySelection` is true, then the cursor will begin or extend
510	/// a selection.
511	///
512	/// Throws a [StateError] if:
513	/// The given `finder` returns zero or more than one result.*
514	/// The [SemanticsNode] found with `finder` does not support*
515	/// [SemanticsAction.moveCursorForwardByCharacter].
516	void moveCursorForwardByCharacter(
517	finders.FinderBase<SemanticsNode> finder, {
518	bool shouldModifySelection = `false`,
519	}) {
520	performAction(
521	finder,
522	SemanticsAction.moveCursorForwardByCharacter,
523	args: shouldModifySelection,
524	);
525	}
526
527	/// Performs a [SemanticsAction.moveCursorForwardByWord] action on the
528	/// [SemanticsNode] found by `finder`.
529	///
530	/// Throws a [StateError] if:
531	/// The given `finder` returns zero or more than one result.*
532	/// The [SemanticsNode] found with `finder` does not support*
533	/// [SemanticsAction.moveCursorForwardByWord].
534	void moveCursorForwardByWord(
535	finders.FinderBase<SemanticsNode> finder, {
536	bool shouldModifySelection = `false`,
537	}) {
538	performAction(finder, SemanticsAction.moveCursorForwardByWord, args: shouldModifySelection);
539	}
540
541	/// Performs a [SemanticsAction.moveCursorBackwardByCharacter] action on the
542	/// [SemanticsNode] found by `finder`.
543	///
544	/// If `shouldModifySelection` is true, then the cursor will begin or extend
545	/// a selection.
546	///
547	/// Throws a [StateError] if:
548	/// The given `finder` returns zero or more than one result.*
549	/// The [SemanticsNode] found with `finder` does not support*
550	/// [SemanticsAction.moveCursorBackwardByCharacter].
551	void moveCursorBackwardByCharacter(
552	finders.FinderBase<SemanticsNode> finder, {
553	bool shouldModifySelection = `false`,
554	}) {
555	performAction(
556	finder,
557	SemanticsAction.moveCursorBackwardByCharacter,
558	args: shouldModifySelection,
559	);
560	}
561
562	/// Performs a [SemanticsAction.moveCursorBackwardByWord] action on the
563	/// [SemanticsNode] found by `finder`.
564	///
565	/// Throws a [StateError] if:
566	/// The given `finder` returns zero or more than one result.*
567	/// The [SemanticsNode] found with `finder` does not support*
568	/// [SemanticsAction.moveCursorBackwardByWord].
569	void moveCursorBackwardByWord(
570	finders.FinderBase<SemanticsNode> finder, {
571	bool shouldModifySelection = `false`,
572	}) {
573	performAction(finder, SemanticsAction.moveCursorBackwardByWord, args: shouldModifySelection);
574	}
575
576	/// Performs a [SemanticsAction.setText] action on the [SemanticsNode]
577	/// found by `finder` using the given `text`.
578	///
579	/// Throws a [StateError] if:
580	/// The given `finder` returns zero or more than one result.*
581	/// The [SemanticsNode] found with `finder` does not support*
582	/// [SemanticsAction.setText].
583	void setText(finders.FinderBase<SemanticsNode> finder, String text) {
584	performAction(finder, SemanticsAction.setText, args: text);
585	}
586
587	/// Performs a [SemanticsAction.setSelection] action on the [SemanticsNode]
588	/// found by `finder`.
589	///
590	/// The `base` parameter is the start index of selection, and the `extent`
591	/// parameter is the length of the selection. Each value should be limited
592	/// between 0 and the length of the found [SemanticsNode]'s `value`.
593	///
594	/// Throws a [StateError] if:
595	/// The given `finder` returns zero or more than one result.*
596	/// The [SemanticsNode] found with `finder` does not support*
597	/// [SemanticsAction.setSelection].
598	void setSelection(
599	finders.FinderBase<SemanticsNode> finder, {
600	required int base,
601	required int extent,
602	}) {
603	performAction(
604	finder,
605	SemanticsAction.setSelection,
606	args: <String, int>{'base': base, 'extent': extent},
607	);
608	}
609
610	/// Performs a [SemanticsAction.copy] action on the [SemanticsNode]
611	/// found by `finder`.
612	///
613	/// Throws a [StateError] if:
614	/// The given `finder` returns zero or more than one result.*
615	/// The [SemanticsNode] found with `finder` does not support*
616	/// [SemanticsAction.copy].
617	void copy(finders.FinderBase<SemanticsNode> finder) {
618	performAction(finder, SemanticsAction.copy);
619	}
620
621	/// Performs a [SemanticsAction.cut] action on the [SemanticsNode]
622	/// found by `finder`.
623	///
624	/// Throws a [StateError] if:
625	/// The given `finder` returns zero or more than one result.*
626	/// The [SemanticsNode] found with `finder` does not support*
627	/// [SemanticsAction.cut].
628	void cut(finders.FinderBase<SemanticsNode> finder) {
629	performAction(finder, SemanticsAction.cut);
630	}
631
632	/// Performs a [SemanticsAction.paste] action on the [SemanticsNode]
633	/// found by `finder`.
634	///
635	/// Throws a [StateError] if:
636	/// The given `finder` returns zero or more than one result.*
637	/// The [SemanticsNode] found with `finder` does not support*
638	/// [SemanticsAction.paste].
639	void paste(finders.FinderBase<SemanticsNode> finder) {
640	performAction(finder, SemanticsAction.paste);
641	}
642
643	/// Performs a [SemanticsAction.didGainAccessibilityFocus] action on the
644	/// [SemanticsNode] found by `finder`.
645	///
646	/// Throws a [StateError] if:
647	/// The given `finder` returns zero or more than one result.*
648	/// The [SemanticsNode] found with `finder` does not support*
649	/// [SemanticsAction.didGainAccessibilityFocus].
650	void didGainAccessibilityFocus(finders.FinderBase<SemanticsNode> finder) {
651	performAction(finder, SemanticsAction.didGainAccessibilityFocus);
652	}
653
654	/// Performs a [SemanticsAction.didLoseAccessibilityFocus] action on the
655	/// [SemanticsNode] found by `finder`.
656	///
657	/// Throws a [StateError] if:
658	/// The given `finder` returns zero or more than one result.*
659	/// The [SemanticsNode] found with `finder` does not support*
660	/// [SemanticsAction.didLoseAccessibilityFocus].
661	void didLoseAccessibilityFocus(finders.FinderBase<SemanticsNode> finder) {
662	performAction(finder, SemanticsAction.didLoseAccessibilityFocus);
663	}
664
665	/// Performs a [SemanticsAction.customAction] action on the
666	/// [SemanticsNode] found by `finder`.
667	///
668	/// Throws a [StateError] if:
669	/// The given `finder` returns zero or more than one result.*
670	/// The [SemanticsNode] found with `finder` does not support*
671	/// [SemanticsAction.customAction].
672	void customAction(finders.FinderBase<SemanticsNode> finder, CustomSemanticsAction action) {
673	performAction(
674	finder,
675	SemanticsAction.customAction,
676	args: CustomSemanticsAction.getIdentifier(action),
677	);
678	}
679
680	/// Performs a [SemanticsAction.dismiss] action on the [SemanticsNode]
681	/// found by `finder`.
682	///
683	/// Throws a [StateError] if:
684	/// The given `finder` returns zero or more than one result.*
685	/// The [SemanticsNode] found with `finder` does not support*
686	/// [SemanticsAction.dismiss].
687	void dismiss(finders.FinderBase<SemanticsNode> finder) {
688	performAction(finder, SemanticsAction.dismiss);
689	}
690	}
691
692	/// Class that programmatically interacts with widgets.
693	///
694	/// For a variant of this class suited specifically for unit tests, see
695	/// [WidgetTester]. For one suitable for live tests on a device, consider
696	/// [LiveWidgetController].
697	///
698	/// Concrete subclasses must implement the [pump] method.
699	abstract class WidgetController {
700	/// Creates a widget controller that uses the given binding.
701	WidgetController(this.binding);
702
703	/// A reference to the current instance of the binding.
704	final WidgetsBinding binding;
705
706	/// The [TestPlatformDispatcher] that is being used in this test.
707	///
708	/// This will be injected into the framework such that calls to
709	/// [WidgetsBinding.platformDispatcher] will use this. This allows
710	/// users to change platform specific properties for testing.
711	///
712	/// See also:
713	///
714	/// [TestFlutterView] which allows changing view specific properties*
715	/// for testing
716	/// [view] and [viewOf] which are used to find*
717	/// [TestFlutterView]s from the widget tree
718	TestPlatformDispatcher get platformDispatcher =>
719	binding.platformDispatcher as TestPlatformDispatcher;
720
721	/// The [TestFlutterView] provided by default when testing with
722	/// [WidgetTester.pumpWidget].
723	///
724	/// If the test uses multiple views, this will return the view that is painted
725	/// into by [WidgetTester.pumpWidget]. If a different view needs to be
726	/// accessed use [viewOf] to ensure that the view related to the widget being
727	/// evaluated is the one that gets updated.
728	///
729	/// See also:
730	///
731	/// [viewOf], which can find a [TestFlutterView] related to a given finder.*
732	/// This is how to modify view properties for testing when dealing with
733	/// multiple views.
734	TestFlutterView get view => platformDispatcher.implicitView!;
735
736	/// Provides access to a [SemanticsController] for testing anything related to
737	/// the [Semantics] tree.
738	///
739	/// Assistive technologies, search engines, and other analysis tools all make
740	/// use of the [Semantics] tree to determine the meaning of an application.
741	/// If semantics has been disabled for the test, this will throw a [StateError].
742	SemanticsController get semantics {
743	if (!binding.semanticsEnabled) {
744	throw StateError(
745	'Semantics are not enabled. Enable them by passing '
746	'`semanticsEnabled: true` to `testWidgets`, or by manually creating a '
747	'`SemanticsHandle` with `WidgetController.ensureSemantics()`.',
748	);
749	}
750
751	return _semantics;
752	}
753
754	late final SemanticsController _semantics = SemanticsController._(this);
755
756	// FINDER API
757
758	// TODO(ianh): verify that the return values are of type T and throw
759	// a good message otherwise, in all the generic methods below
760
761	/// Finds the [TestFlutterView] that is the closest ancestor of the widget
762	/// found by [finder].
763	///
764	/// [TestFlutterView] can be used to modify view specific properties for testing.
765	///
766	/// See also:
767	///
768	/// [view] which returns the [TestFlutterView] used when only a single*
769	/// view is being used.
770	TestFlutterView viewOf(finders.FinderBase<Element> finder) {
771	return _viewOf(finder) as TestFlutterView;
772	}
773
774	FlutterView _viewOf(finders.FinderBase<Element> finder) {
775	return firstWidget<View>(
776	finders.find.ancestor(of: finder, matching: finders.find.byType(View)),
777	).view;
778	}
779
780	/// Checks if `finder` exists in the tree.
781	bool any(finders.FinderBase<Element> finder) {
782	TestAsyncUtils.guardSync();
783	return finder.evaluate().isNotEmpty;
784	}
785
786	/// All widgets currently in the widget tree (lazy pre-order traversal).
787	///
788	/// Can contain duplicates, since widgets can be used in multiple
789	/// places in the widget tree.
790	Iterable<Widget> get allWidgets {
791	TestAsyncUtils.guardSync();
792	return allElements.map<Widget>((Element element) => element.widget);
793	}
794
795	/// The matching widget in the widget tree.
796	///
797	/// Throws a [StateError] if `finder` is empty or matches more than
798	/// one widget.
799	///
800	/// Use [firstWidget] if you expect to match several widgets but only want the first.*
801	/// Use [widgetList] if you expect to match several widgets and want all of them.*
802	T widget<T extends Widget>(finders.FinderBase<Element> finder) {
803	TestAsyncUtils.guardSync();
804	return finder.evaluate().single.widget as T;
805	}
806
807	/// The first matching widget according to a depth-first pre-order
808	/// traversal of the widget tree.
809	///
810	/// Throws a [StateError] if `finder` is empty.
811	///
812	/// Use [widget] if you only expect to match one widget.*
813	T firstWidget<T extends Widget>(finders.FinderBase<Element> finder) {
814	TestAsyncUtils.guardSync();
815	return finder.evaluate().first.widget as T;
816	}
817
818	/// The matching widgets in the widget tree.
819	///
820	/// Use [widget] if you only expect to match one widget.*
821	/// Use [firstWidget] if you expect to match several but only want the first.*
822	Iterable<T> widgetList<T extends Widget>(finders.FinderBase<Element> finder) {
823	TestAsyncUtils.guardSync();
824	return finder.evaluate().map<T>((Element element) {
825	final T result = element.widget as T;
826	return result;
827	});
828	}
829
830	/// Find all layers that are children of the provided [finder].
831	///
832	/// The [finder] must match exactly one element.
833	Iterable<Layer> layerListOf(finders.FinderBase<Element> finder) {
834	TestAsyncUtils.guardSync();
835	final Element element = finder.evaluate().single;
836	final RenderObject object = element.renderObject!;
837	RenderObject current = object;
838	while (current.debugLayer == `null`) {
839	current = current.parent!;
840	}
841	final ContainerLayer layer = current.debugLayer!;
842	return _walkLayers(layer);
843	}
844
845	/// All elements currently in the widget tree (lazy pre-order traversal).
846	///
847	/// The returned iterable is lazy. It does not walk the entire widget tree
848	/// immediately, but rather a chunk at a time as the iteration progresses
849	/// using [Iterator.moveNext].
850	Iterable<Element> get allElements {
851	TestAsyncUtils.guardSync();
852	return collectAllElementsFrom(binding.rootElement!, skipOffstage: `false`);
853	}
854
855	/// The matching element in the widget tree.
856	///
857	/// Throws a [StateError] if `finder` is empty or matches more than
858	/// one element.
859	///
860	/// Use [firstElement] if you expect to match several elements but only want the first.*
861	/// Use [elementList] if you expect to match several elements and want all of them.*
862	T element<T extends Element>(finders.FinderBase<Element> finder) {
863	TestAsyncUtils.guardSync();
864	return finder.evaluate().single as T;
865	}
866
867	/// The first matching element according to a depth-first pre-order
868	/// traversal of the widget tree.
869	///
870	/// Throws a [StateError] if `finder` is empty.
871	///
872	/// Use [element] if you only expect to match one element.*
873	T firstElement<T extends Element>(finders.FinderBase<Element> finder) {
874	TestAsyncUtils.guardSync();
875	return finder.evaluate().first as T;
876	}
877
878	/// The matching elements in the widget tree.
879	///
880	/// Use [element] if you only expect to match one element.*
881	/// Use [firstElement] if you expect to match several but only want the first.*
882	Iterable<T> elementList<T extends Element>(finders.FinderBase<Element> finder) {
883	TestAsyncUtils.guardSync();
884	return finder.evaluate().cast<T>();
885	}
886
887	/// All states currently in the widget tree (lazy pre-order traversal).
888	///
889	/// The returned iterable is lazy. It does not walk the entire widget tree
890	/// immediately, but rather a chunk at a time as the iteration progresses
891	/// using [Iterator.moveNext].
892	Iterable<State> get allStates {
893	TestAsyncUtils.guardSync();
894	return allElements.whereType<StatefulElement>().map<State>(
895	(StatefulElement element) => element.state,
896	);
897	}
898
899	/// The matching state in the widget tree.
900	///
901	/// Throws a [StateError] if `finder` is empty, matches more than
902	/// one state, or matches a widget that has no state.
903	///
904	/// Use [firstState] if you expect to match several states but only want the first.*
905	/// Use [stateList] if you expect to match several states and want all of them.*
906	T state<T extends State>(finders.FinderBase<Element> finder) {
907	TestAsyncUtils.guardSync();
908	return _stateOf<T>(finder.evaluate().single, finder);
909	}
910
911	/// The first matching state according to a depth-first pre-order
912	/// traversal of the widget tree.
913	///
914	/// Throws a [StateError] if `finder` is empty or if the first
915	/// matching widget has no state.
916	///
917	/// Use [state] if you only expect to match one state.*
918	T firstState<T extends State>(finders.FinderBase<Element> finder) {
919	TestAsyncUtils.guardSync();
920	return _stateOf<T>(finder.evaluate().first, finder);
921	}
922
923	/// The matching states in the widget tree.
924	///
925	/// Throws a [StateError] if any of the elements in `finder` match a widget
926	/// that has no state.
927	///
928	/// Use [state] if you only expect to match one state.*
929	/// Use [firstState] if you expect to match several but only want the first.*
930	Iterable<T> stateList<T extends State>(finders.FinderBase<Element> finder) {
931	TestAsyncUtils.guardSync();
932	return finder.evaluate().map<T>((Element element) => _stateOf<T>(element, finder));
933	}
934
935	T _stateOf<T extends State>(Element element, finders.FinderBase<Element> finder) {
936	TestAsyncUtils.guardSync();
937	if (element is StatefulElement) {
938	return element.state as T;
939	}
940	throw StateError(
941	'Widget of type ${element.widget.runtimeType}, with ${finder.describeMatch(finders.Plurality.many)}, is not a StatefulWidget.',
942	);
943	}
944
945	/// Render objects of all the widgets currently in the widget tree
946	/// (lazy pre-order traversal).
947	///
948	/// This will almost certainly include many duplicates since the
949	/// render object of a [StatelessWidget] or [StatefulWidget] is the
950	/// render object of its child; only [RenderObjectWidget]s have
951	/// their own render object.
952	Iterable<RenderObject> get allRenderObjects {
953	TestAsyncUtils.guardSync();
954	return allElements.map<RenderObject>((Element element) => element.renderObject!);
955	}
956
957	/// The render object of the matching widget in the widget tree.
958	///
959	/// Throws a [StateError] if `finder` is empty or matches more than
960	/// one widget (even if they all have the same render object).
961	///
962	/// Use [firstRenderObject] if you expect to match several render objects but only want the first.*
963	/// Use [renderObjectList] if you expect to match several render objects and want all of them.*
964	T renderObject<T extends RenderObject>(finders.FinderBase<Element> finder) {
965	TestAsyncUtils.guardSync();
966	return finder.evaluate().single.renderObject! as T;
967	}
968
969	/// The render object of the first matching widget according to a
970	/// depth-first pre-order traversal of the widget tree.
971	///
972	/// Throws a [StateError] if `finder` is empty.
973	///
974	/// Use [renderObject] if you only expect to match one render object.*
975	T firstRenderObject<T extends RenderObject>(finders.FinderBase<Element> finder) {
976	TestAsyncUtils.guardSync();
977	return finder.evaluate().first.renderObject! as T;
978	}
979
980	/// The render objects of the matching widgets in the widget tree.
981	///
982	/// Use [renderObject] if you only expect to match one render object.*
983	/// Use [firstRenderObject] if you expect to match several but only want the first.*
984	Iterable<T> renderObjectList<T extends RenderObject>(finders.FinderBase<Element> finder) {
985	TestAsyncUtils.guardSync();
986	return finder.evaluate().map<T>((Element element) {
987	final T result = element.renderObject! as T;
988	return result;
989	});
990	}
991
992	/// Returns a list of all the [Layer] objects in the rendering.
993	List<Layer> get layers {
994	return <Layer>[
995	for (final RenderView renderView in binding.renderViews)
996	..._walkLayers(renderView.debugLayer!),
997	];
998	}
999
1000	Iterable<Layer> _walkLayers(Layer layer) sync* {
1001	TestAsyncUtils.guardSync();
1002	yield layer;
1003	if (layer is ContainerLayer) {
1004	final ContainerLayer root = layer;
1005	Layer? child = root.firstChild;
1006	while (child != `null`) {
1007	yield* _walkLayers(child);
1008	child = child.nextSibling;
1009	}
1010	}
1011	}
1012
1013	// INTERACTION
1014
1015	/// Dispatch a pointer down / pointer up sequence at the center of
1016	/// the given widget, assuming it is exposed.
1017	///
1018	/// {@template flutter.flutter_test.WidgetController.tap.warnIfMissed}
1019	/// The `warnIfMissed` argument, if true (the default), causes a warning to be
1020	/// displayed on the console if the specified [Finder] indicates a widget and
1021	/// location that, were a pointer event to be sent to that location, would not
1022	/// actually send any events to the widget (e.g. because the widget is
1023	/// obscured, or the location is off-screen, or the widget is transparent to
1024	/// pointer events).
1025	///
1026	/// Set the argument to false to silence that warning if you intend to not
1027	/// actually hit the specified element.
1028	/// {@endtemplate}
1029	///
1030	/// For example, a test that verifies that tapping a disabled button does not
1031	/// trigger the button would set `warnIfMissed` to false, because the button
1032	/// would ignore the tap.
1033	Future<void> tap(
1034	finders.FinderBase<Element> finder, {
1035	int? pointer,
1036	int buttons = kPrimaryButton,
1037	bool warnIfMissed = `true`,
1038	PointerDeviceKind kind = PointerDeviceKind.touch,
1039	}) {
1040	return tapAt(
1041	getCenter(finder, warnIfMissed: warnIfMissed, callee: 'tap'),
1042	pointer: pointer,
1043	buttons: buttons,
1044	kind: kind,
1045	);
1046	}
1047
1048	/// Dispatch a pointer down / pointer up sequence at a hit-testable
1049	/// [InlineSpan] (typically a [TextSpan]) within the given text range.
1050	///
1051	/// This method performs a more spatially precise tap action on a piece of
1052	/// static text, than the widget-based [tap] method.
1053	///
1054	/// The given [Finder] must find one and only one matching substring, and the
1055	/// substring must be hit-testable (meaning, it must not be off-screen, or be
1056	/// obscured by other widgets, or in a disabled widget). Otherwise this method
1057	/// throws a [FlutterError].
1058	///
1059	/// If the target substring contains more than one hit-testable [InlineSpan]s,
1060	/// [tapOnText] taps on one of them, but does not guarantee which.
1061	///
1062	/// The `pointer` and `button` arguments specify [PointerEvent.pointer] and
1063	/// [PointerEvent.buttons] of the tap event.
1064	Future<void> tapOnText(
1065	finders.FinderBase<finders.TextRangeContext> textRangeFinder, {
1066	int? pointer,
1067	int buttons = kPrimaryButton,
1068	}) {
1069	final Iterable<finders.TextRangeContext> ranges = textRangeFinder.evaluate();
1070	if (ranges.isEmpty) {
1071	throw FlutterError(textRangeFinder.toString());
1072	}
1073	if (ranges.length > `1`) {
1074	throw FlutterError(
1075	'$textRangeFinder. The "tapOnText" method needs a single non-empty TextRange.',
1076	);
1077	}
1078	final Offset? tapLocation = _findHitTestableOffsetIn(ranges.single);
1079	if (tapLocation == `null`) {
1080	final finders.TextRangeContext found = textRangeFinder.evaluate().single;
1081	throw FlutterError.fromParts(<DiagnosticsNode>[
1082	ErrorSummary('Finder specifies a TextRange that can not receive pointer events.'),
1083	ErrorDescription('The finder used was: ${textRangeFinder.toString(describeSelf: `true`)}'),
1084	ErrorDescription(
1085	'Found a matching substring in a static text widget, within ${found.textRange}.',
1086	),
1087	ErrorDescription(
1088	'But the "tapOnText" method could not find a hit-testable Offset with in that text range.',
1089	),
1090	found.renderObject.toDiagnosticsNode(
1091	name: 'The RenderBox of that static text widget was',
1092	style: DiagnosticsTreeStyle.shallow,
1093	),
1094	]);
1095	}
1096	return tapAt(tapLocation, pointer: pointer, buttons: buttons);
1097	}
1098
1099	/// Dispatch a pointer down / pointer up sequence at the given location.
1100	Future<void> tapAt(
1101	Offset location, {
1102	int? pointer,
1103	int buttons = kPrimaryButton,
1104	PointerDeviceKind kind = PointerDeviceKind.touch,
1105	}) {
1106	return TestAsyncUtils.guard<void>(() async {
1107	final TestGesture gesture = await startGesture(
1108	location,
1109	pointer: pointer,
1110	buttons: buttons,
1111	kind: kind,
1112	);
1113	await gesture.up();
1114	});
1115	}
1116
1117	/// Dispatch a pointer down at the center of the given widget, assuming it is
1118	/// exposed.
1119	///
1120	/// {@macro flutter.flutter_test.WidgetController.tap.warnIfMissed}
1121	///
1122	/// The return value is a [TestGesture] object that can be used to continue the
1123	/// gesture (e.g. moving the pointer or releasing it).
1124	///
1125	/// See also:
1126	///
1127	/// [tap], which presses and releases a pointer at the given location.*
1128	/// [longPress], which presses and releases a pointer with a gap in*
1129	/// between long enough to trigger the long-press gesture.
1130	Future<TestGesture> press(
1131	finders.FinderBase<Element> finder, {
1132	int? pointer,
1133	int buttons = kPrimaryButton,
1134	bool warnIfMissed = `true`,
1135	PointerDeviceKind kind = PointerDeviceKind.touch,
1136	}) {
1137	return TestAsyncUtils.guard<TestGesture>(() {
1138	return startGesture(
1139	getCenter(finder, warnIfMissed: warnIfMissed, callee: 'press'),
1140	pointer: pointer,
1141	buttons: buttons,
1142	kind: kind,
1143	);
1144	});
1145	}
1146
1147	/// Dispatch a pointer down / pointer up sequence (with a delay of
1148	/// [kLongPressTimeout] + [kPressTimeout] between the two events) at the
1149	/// center of the given widget, assuming it is exposed.
1150	///
1151	/// {@macro flutter.flutter_test.WidgetController.tap.warnIfMissed}
1152	///
1153	/// For example, consider a widget that, when long-pressed, shows an overlay
1154	/// that obscures the original widget. A test for that widget might first
1155	/// long-press that widget with `warnIfMissed` at its default value true, then
1156	/// later verify that long-pressing the same location (using the same finder)
1157	/// has no effect (since the widget is now obscured), setting `warnIfMissed`
1158	/// to false on that second call.
1159	Future<void> longPress(
1160	finders.FinderBase<Element> finder, {
1161	int? pointer,
1162	int buttons = kPrimaryButton,
1163	bool warnIfMissed = `true`,
1164	PointerDeviceKind kind = PointerDeviceKind.touch,
1165	}) {
1166	return longPressAt(
1167	getCenter(finder, warnIfMissed: warnIfMissed, callee: 'longPress'),
1168	pointer: pointer,
1169	buttons: buttons,
1170	kind: kind,
1171	);
1172	}
1173
1174	/// Dispatch a pointer down / pointer up sequence at the given location with
1175	/// a delay of [kLongPressTimeout] + [kPressTimeout] between the two events.
1176	Future<void> longPressAt(
1177	Offset location, {
1178	int? pointer,
1179	int buttons = kPrimaryButton,
1180	PointerDeviceKind kind = PointerDeviceKind.touch,
1181	}) {
1182	return TestAsyncUtils.guard<void>(() async {
1183	final TestGesture gesture = await startGesture(
1184	location,
1185	pointer: pointer,
1186	buttons: buttons,
1187	kind: kind,
1188	);
1189	await pump(kLongPressTimeout + kPressTimeout);
1190	await gesture.up();
1191	});
1192	}
1193
1194	/// Attempts a fling gesture starting from the center of the given
1195	/// widget, moving the given distance, reaching the given speed.
1196	///
1197	/// {@macro flutter.flutter_test.WidgetController.tap.warnIfMissed}
1198	///
1199	/// {@template flutter.flutter_test.WidgetController.fling.offset}
1200	/// The `offset` represents a distance the pointer moves in the global
1201	/// coordinate system of the screen.
1202	///
1203	/// Positive [Offset.dy] values mean the pointer moves downward. Negative
1204	/// [Offset.dy] values mean the pointer moves upwards. Accordingly, positive
1205	/// [Offset.dx] values mean the pointer moves towards the right. Negative
1206	/// [Offset.dx] values mean the pointer moves towards left.
1207	/// {@endtemplate}
1208	///
1209	/// {@template flutter.flutter_test.WidgetController.fling}
1210	/// This can pump frames.
1211	///
1212	/// Exactly 50 pointer events are synthesized.
1213	///
1214	/// The `speed` is in pixels per second in the direction given by `offset`.
1215	///
1216	/// The `offset` and `speed` control the interval between each pointer event.
1217	/// For example, if the `offset` is 200 pixels down, and the `speed` is 800
1218	/// pixels per second, the pointer events will be sent for each increment
1219	/// of 4 pixels (200/50), over 250ms (200/800), meaning events will be sent
1220	/// every 1.25ms (250/200).
1221	///
1222	/// To make tests more realistic, frames may be pumped during this time (using
1223	/// calls to [pump]). If the total duration is longer than `frameInterval`,
1224	/// then one frame is pumped each time that amount of time elapses while
1225	/// sending events, or each time an event is synthesized, whichever is rarer.
1226	///
1227	/// See [LiveTestWidgetsFlutterBindingFramePolicy.benchmarkLive] if the method
1228	/// is used in a live environment and accurate time control is important.
1229	///
1230	/// The `initialOffset` argument, if non-zero, causes the pointer to first
1231	/// apply that offset, then pump a delay of `initialOffsetDelay`. This can be
1232	/// used to simulate a drag followed by a fling, including dragging in the
1233	/// opposite direction of the fling (e.g. dragging 200 pixels to the right,
1234	/// then fling to the left over 200 pixels, ending at the exact point that the
1235	/// drag started).
1236	/// {@endtemplate}
1237	///
1238	/// A fling is essentially a drag that ends at a particular speed. If you
1239	/// just want to drag and end without a fling, use [drag].
1240	Future<void> fling(
1241	finders.FinderBase<Element> finder,
1242	Offset offset,
1243	double speed, {
1244	int? pointer,
1245	int buttons = kPrimaryButton,
1246	Duration frameInterval = const Duration(milliseconds: `16`),
1247	Offset initialOffset = Offset.zero,
1248	Duration initialOffsetDelay = const Duration(seconds: `1`),
1249	bool warnIfMissed = `true`,
1250	PointerDeviceKind deviceKind = PointerDeviceKind.touch,
1251	}) {
1252	return flingFrom(
1253	getCenter(finder, warnIfMissed: warnIfMissed, callee: 'fling'),
1254	offset,
1255	speed,
1256	pointer: pointer,
1257	buttons: buttons,
1258	frameInterval: frameInterval,
1259	initialOffset: initialOffset,
1260	initialOffsetDelay: initialOffsetDelay,
1261	deviceKind: deviceKind,
1262	);
1263	}
1264
1265	/// Attempts a fling gesture starting from the given location, moving the
1266	/// given distance, reaching the given speed.
1267	///
1268	/// {@macro flutter.flutter_test.WidgetController.fling}
1269	///
1270	/// A fling is essentially a drag that ends at a particular speed. If you
1271	/// just want to drag and end without a fling, use [dragFrom].
1272	Future<void> flingFrom(
1273	Offset startLocation,
1274	Offset offset,
1275	double speed, {
1276	int? pointer,
1277	int buttons = kPrimaryButton,
1278	Duration frameInterval = const Duration(milliseconds: `16`),
1279	Offset initialOffset = Offset.zero,
1280	Duration initialOffsetDelay = const Duration(seconds: `1`),
1281	PointerDeviceKind deviceKind = PointerDeviceKind.touch,
1282	}) {
1283	assert(offset.distance > `0.0`);
1284	assert(speed > `0.0`); // speed is pixels/second
1285	return TestAsyncUtils.guard<void>(() async {
1286	final TestPointer testPointer = TestPointer(
1287	pointer ?? _getNextPointer(),
1288	deviceKind,
1289	`null`,
1290	buttons,
1291	);
1292	const int kMoveCount =
1293	`50`; // Needs to be >= kHistorySize, see _LeastSquaresVelocityTrackerStrategy
1294	final double timeStampDelta = `1000000.0` * offset.distance / (kMoveCount * speed);
1295	double timeStamp = `0.0`;
1296	double lastTimeStamp = timeStamp;
1297	await sendEventToBinding(
1298	testPointer.down(startLocation, timeStamp: Duration(microseconds: timeStamp.round())),
1299	);
1300	if (initialOffset.distance > `0.0`) {
1301	await sendEventToBinding(
1302	testPointer.move(
1303	startLocation + initialOffset,
1304	timeStamp: Duration(microseconds: timeStamp.round()),
1305	),
1306	);
1307	timeStamp += initialOffsetDelay.inMicroseconds;
1308	await pump(initialOffsetDelay);
1309	}
1310	for (int i = `0`; i <= kMoveCount; i += `1`) {
1311	final Offset location =
1312	startLocation + initialOffset + Offset.lerp(Offset.zero, offset, i / kMoveCount)!;
1313	await sendEventToBinding(
1314	testPointer.move(location, timeStamp: Duration(microseconds: timeStamp.round())),
1315	);
1316	timeStamp += timeStampDelta;
1317	if (timeStamp - lastTimeStamp > frameInterval.inMicroseconds) {
1318	await pump(Duration(microseconds: (timeStamp - lastTimeStamp).truncate()));
1319	lastTimeStamp = timeStamp;
1320	}
1321	}
1322	await sendEventToBinding(
1323	testPointer.up(timeStamp: Duration(microseconds: timeStamp.round())),
1324	);
1325	});
1326	}
1327
1328	/// Attempts a trackpad fling gesture starting from the center of the given
1329	/// widget, moving the given distance, reaching the given speed. A trackpad
1330	/// fling sends PointerPanZoom events instead of a sequence of touch events.
1331	///
1332	/// {@macro flutter.flutter_test.WidgetController.tap.warnIfMissed}
1333	///
1334	/// {@macro flutter.flutter_test.WidgetController.fling}
1335	///
1336	/// A fling is essentially a drag that ends at a particular speed. If you
1337	/// just want to drag and end without a fling, use [drag].
1338	Future<void> trackpadFling(
1339	finders.FinderBase<Element> finder,
1340	Offset offset,
1341	double speed, {
1342	int? pointer,
1343	int buttons = kPrimaryButton,
1344	Duration frameInterval = const Duration(milliseconds: `16`),
1345	Offset initialOffset = Offset.zero,
1346	Duration initialOffsetDelay = const Duration(seconds: `1`),
1347	bool warnIfMissed = `true`,
1348	}) {
1349	return trackpadFlingFrom(
1350	getCenter(finder, warnIfMissed: warnIfMissed, callee: 'fling'),
1351	offset,
1352	speed,
1353	pointer: pointer,
1354	buttons: buttons,
1355	frameInterval: frameInterval,
1356	initialOffset: initialOffset,
1357	initialOffsetDelay: initialOffsetDelay,
1358	);
1359	}
1360
1361	/// Attempts a fling gesture starting from the given location, moving the
1362	/// given distance, reaching the given speed. A trackpad fling sends
1363	/// PointerPanZoom events instead of a sequence of touch events.
1364	///
1365	/// {@macro flutter.flutter_test.WidgetController.fling}
1366	///
1367	/// A fling is essentially a drag that ends at a particular speed. If you
1368	/// just want to drag and end without a fling, use [dragFrom].
1369	Future<void> trackpadFlingFrom(
1370	Offset startLocation,
1371	Offset offset,
1372	double speed, {
1373	int? pointer,
1374	int buttons = kPrimaryButton,
1375	Duration frameInterval = const Duration(milliseconds: `16`),
1376	Offset initialOffset = Offset.zero,
1377	Duration initialOffsetDelay = const Duration(seconds: `1`),
1378	}) {
1379	assert(offset.distance > `0.0`);
1380	assert(speed > `0.0`); // speed is pixels/second
1381	return TestAsyncUtils.guard<void>(() async {
1382	final TestPointer testPointer = TestPointer(
1383	pointer ?? _getNextPointer(),
1384	PointerDeviceKind.trackpad,
1385	`null`,
1386	buttons,
1387	);
1388	const int kMoveCount =
1389	`50`; // Needs to be >= kHistorySize, see _LeastSquaresVelocityTrackerStrategy
1390	final double timeStampDelta = `1000000.0` * offset.distance / (kMoveCount * speed);
1391	double timeStamp = `0.0`;
1392	double lastTimeStamp = timeStamp;
1393	await sendEventToBinding(
1394	testPointer.panZoomStart(
1395	startLocation,
1396	timeStamp: Duration(microseconds: timeStamp.round()),
1397	),
1398	);
1399	if (initialOffset.distance > `0.0`) {
1400	await sendEventToBinding(
1401	testPointer.panZoomUpdate(
1402	startLocation,
1403	pan: initialOffset,
1404	timeStamp: Duration(microseconds: timeStamp.round()),
1405	),
1406	);
1407	timeStamp += initialOffsetDelay.inMicroseconds;
1408	await pump(initialOffsetDelay);
1409	}
1410	for (int i = `0`; i <= kMoveCount; i += `1`) {
1411	final Offset pan = initialOffset + Offset.lerp(Offset.zero, offset, i / kMoveCount)!;
1412	await sendEventToBinding(
1413	testPointer.panZoomUpdate(
1414	startLocation,
1415	pan: pan,
1416	timeStamp: Duration(microseconds: timeStamp.round()),
1417	),
1418	);
1419	timeStamp += timeStampDelta;
1420	if (timeStamp - lastTimeStamp > frameInterval.inMicroseconds) {
1421	await pump(Duration(microseconds: (timeStamp - lastTimeStamp).truncate()));
1422	lastTimeStamp = timeStamp;
1423	}
1424	}
1425	await sendEventToBinding(
1426	testPointer.panZoomEnd(timeStamp: Duration(microseconds: timeStamp.round())),
1427	);
1428	});
1429	}
1430
1431	/// A simulator of how the framework handles a series of [PointerEvent]s
1432	/// received from the Flutter engine.
1433	///
1434	/// The [PointerEventRecord.timeDelay] is used as the time delay of the events
1435	/// injection relative to the starting point of the method call.
1436	///
1437	/// Returns a list of the difference between the real delay time when the
1438	/// [PointerEventRecord.events] are processed and
1439	/// [PointerEventRecord.timeDelay].
1440	/// - For [AutomatedTestWidgetsFlutterBinding] where the clock is fake, the
1441	/// return value should be exact zeros.
1442	/// - For [LiveTestWidgetsFlutterBinding], the values are typically small
1443	/// positives, meaning the event happens a little later than the set time,
1444	/// but a very small portion may have a tiny negative value for about tens of
1445	/// microseconds. This is due to the nature of [Future.delayed].
1446	///
1447	/// The closer the return values are to zero the more faithful it is to the
1448	/// `records`.
1449	///
1450	/// See [PointerEventRecord].
1451	Future<List<Duration>> handlePointerEventRecord(List<PointerEventRecord> records);
1452
1453	/// Called to indicate that there should be a new frame after an optional
1454	/// delay.
1455	///
1456	/// The frame is pumped after a delay of [duration] if [duration] is not null,
1457	/// or immediately otherwise.
1458	///
1459	/// This is invoked by [flingFrom], for instance, so that the sequence of
1460	/// pointer events occurs over time.
1461	///
1462	/// The [WidgetTester] subclass implements this by deferring to the [binding].
1463	///
1464	/// See also:
1465	///
1466	/// [SchedulerBinding.endOfFrame], which returns a future that could be*
1467	/// appropriate to return in the implementation of this method.
1468	Future<void> pump([Duration duration]);
1469
1470	/// Repeatedly calls [pump] with the given `duration` until there are no
1471	/// longer any frames scheduled. This will call [pump] at least once, even if
1472	/// no frames are scheduled when the function is called, to flush any pending
1473	/// microtasks which may themselves schedule a frame.
1474	///
1475	/// This essentially waits for all animations to have completed.
1476	///
1477	/// If it takes longer that the given `timeout` to settle, then the test will
1478	/// fail (this method will throw an exception). In particular, this means that
1479	/// if there is an infinite animation in progress (for example, if there is an
1480	/// indeterminate progress indicator spinning), this method will throw.
1481	///
1482	/// The default timeout is ten minutes, which is longer than most reasonable
1483	/// finite animations would last.
1484	///
1485	/// If the function returns, it returns the number of pumps that it performed.
1486	///
1487	/// In general, it is better practice to figure out exactly why each frame is
1488	/// needed, and then to [pump] exactly as many frames as necessary. This will
1489	/// help catch regressions where, for instance, an animation is being started
1490	/// one frame later than it should.
1491	///
1492	/// Alternatively, one can check that the return value from this function
1493	/// matches the expected number of pumps.
1494	Future<int> pumpAndSettle([Duration duration = const Duration(milliseconds: `100`)]);
1495
1496	/// Attempts to drag the given widget by the given offset, by
1497	/// starting a drag in the middle of the widget.
1498	///
1499	/// {@macro flutter.flutter_test.WidgetController.tap.warnIfMissed}
1500	///
1501	/// If you want the drag to end with a speed so that the gesture recognition
1502	/// system identifies the gesture as a fling, consider using [fling] instead.
1503	///
1504	/// The operation happens at once. If you want the drag to last for a period
1505	/// of time, consider using [timedDrag].
1506	///
1507	/// {@macro flutter.flutter_test.WidgetController.fling.offset}
1508	///
1509	/// {@template flutter.flutter_test.WidgetController.drag}
1510	/// By default, if the x or y component of offset is greater than
1511	/// [kDragSlopDefault], the gesture is broken up into two separate moves
1512	/// calls. Changing `touchSlopX` or `touchSlopY` will change the minimum
1513	/// amount of movement in the respective axis before the drag will be broken
1514	/// into multiple calls. To always send the drag with just a single call to
1515	/// [TestGesture.moveBy], `touchSlopX` and `touchSlopY` should be set to 0.
1516	///
1517	/// Breaking the drag into multiple moves is necessary for accurate execution
1518	/// of drag update calls with a [DragStartBehavior] variable set to
1519	/// [DragStartBehavior.start]. Without such a change, the dragUpdate callback
1520	/// from a drag recognizer will never be invoked.
1521	///
1522	/// To force this function to a send a single move event, the `touchSlopX` and
1523	/// `touchSlopY` variables should be set to 0. However, generally, these values
1524	/// should be left to their default values.
1525	/// {@endtemplate}
1526	Future<void> drag(
1527	finders.FinderBase<Element> finder,
1528	Offset offset, {
1529	int? pointer,
1530	int buttons = kPrimaryButton,
1531	double touchSlopX = kDragSlopDefault,
1532	double touchSlopY = kDragSlopDefault,
1533	bool warnIfMissed = `true`,
1534	PointerDeviceKind kind = PointerDeviceKind.touch,
1535	}) {
1536	return dragFrom(
1537	getCenter(finder, warnIfMissed: warnIfMissed, callee: 'drag'),
1538	offset,
1539	pointer: pointer,
1540	buttons: buttons,
1541	touchSlopX: touchSlopX,
1542	touchSlopY: touchSlopY,
1543	kind: kind,
1544	);
1545	}
1546
1547	/// Attempts a drag gesture consisting of a pointer down, a move by
1548	/// the given offset, and a pointer up.
1549	///
1550	/// If you want the drag to end with a speed so that the gesture recognition
1551	/// system identifies the gesture as a fling, consider using [flingFrom]
1552	/// instead.
1553	///
1554	/// The operation happens at once. If you want the drag to last for a period
1555	/// of time, consider using [timedDragFrom].
1556	///
1557	/// {@macro flutter.flutter_test.WidgetController.drag}
1558	Future<void> dragFrom(
1559	Offset startLocation,
1560	Offset offset, {
1561	int? pointer,
1562	int buttons = kPrimaryButton,
1563	double touchSlopX = kDragSlopDefault,
1564	double touchSlopY = kDragSlopDefault,
1565	PointerDeviceKind kind = PointerDeviceKind.touch,
1566	}) {
1567	assert(kDragSlopDefault > kTouchSlop);
1568	return TestAsyncUtils.guard<void>(() async {
1569	final TestGesture gesture = await startGesture(
1570	startLocation,
1571	pointer: pointer,
1572	buttons: buttons,
1573	kind: kind,
1574	);
1575
1576	final double xSign = offset.dx.sign;
1577	final double ySign = offset.dy.sign;
1578
1579	final double offsetX = offset.dx;
1580	final double offsetY = offset.dy;
1581
1582	final bool separateX = offset.dx.abs() > touchSlopX && touchSlopX > `0`;
1583	final bool separateY = offset.dy.abs() > touchSlopY && touchSlopY > `0`;
1584
1585	if (separateY \|\| separateX) {
1586	final double offsetSlope = offsetY / offsetX;
1587	final double inverseOffsetSlope = offsetX / offsetY;
1588	final double slopSlope = touchSlopY / touchSlopX;
1589	final double absoluteOffsetSlope = offsetSlope.abs();
1590	final double signedSlopX = touchSlopX * xSign;
1591	final double signedSlopY = touchSlopY * ySign;
1592	if (absoluteOffsetSlope != slopSlope) {
1593	// The drag goes through one or both of the extents of the edges of the box.
1594	if (absoluteOffsetSlope < slopSlope) {
1595	assert(offsetX.abs() > touchSlopX);
1596	// The drag goes through the vertical edge of the box.
1597	// It is guaranteed that the \|offsetX\| > touchSlopX.
1598	final double diffY = offsetSlope.abs() * touchSlopX * ySign;
1599
1600	// The vector from the origin to the vertical edge.
1601	await gesture.moveBy(Offset(signedSlopX, diffY));
1602	if (offsetY.abs() <= touchSlopY) {
1603	// The drag ends on or before getting to the horizontal extension of the horizontal edge.
1604	await gesture.moveBy(Offset(offsetX - signedSlopX, offsetY - diffY));
1605	} else {
1606	final double diffY2 = signedSlopY - diffY;
1607	final double diffX2 = inverseOffsetSlope * diffY2;
1608
1609	// The vector from the edge of the box to the horizontal extension of the horizontal edge.
1610	await gesture.moveBy(Offset(diffX2, diffY2));
1611	await gesture.moveBy(Offset(offsetX - diffX2 - signedSlopX, offsetY - signedSlopY));
1612	}
1613	} else {
1614	assert(offsetY.abs() > touchSlopY);
1615	// The drag goes through the horizontal edge of the box.
1616	// It is guaranteed that the \|offsetY\| > touchSlopY.
1617	final double diffX = inverseOffsetSlope.abs() * touchSlopY * xSign;
1618
1619	// The vector from the origin to the vertical edge.
1620	await gesture.moveBy(Offset(diffX, signedSlopY));
1621	if (offsetX.abs() <= touchSlopX) {
1622	// The drag ends on or before getting to the vertical extension of the vertical edge.
1623	await gesture.moveBy(Offset(offsetX - diffX, offsetY - signedSlopY));
1624	} else {
1625	final double diffX2 = signedSlopX - diffX;
1626	final double diffY2 = offsetSlope * diffX2;
1627
1628	// The vector from the edge of the box to the vertical extension of the vertical edge.
1629	await gesture.moveBy(Offset(diffX2, diffY2));
1630	await gesture.moveBy(Offset(offsetX - signedSlopX, offsetY - diffY2 - signedSlopY));
1631	}
1632	}
1633	} else {
1634	// The drag goes through the corner of the box.
1635	await gesture.moveBy(Offset(signedSlopX, signedSlopY));
1636	await gesture.moveBy(Offset(offsetX - signedSlopX, offsetY - signedSlopY));
1637	}
1638	} else {
1639	// The drag ends inside the box.
1640	await gesture.moveBy(offset);
1641	}
1642	await gesture.up();
1643	});
1644	}
1645
1646	/// Attempts to drag the given widget by the given offset in the `duration`
1647	/// time, starting in the middle of the widget.
1648	///
1649	/// {@macro flutter.flutter_test.WidgetController.tap.warnIfMissed}
1650	///
1651	/// {@macro flutter.flutter_test.WidgetController.fling.offset}
1652	///
1653	/// This is the timed version of [drag]. This may or may not result in a
1654	/// [fling] or ballistic animation, depending on the speed from
1655	/// `offset/duration`.
1656	///
1657	/// {@template flutter.flutter_test.WidgetController.timedDrag}
1658	/// The move events are sent at a given `frequency` in Hz (or events per
1659	/// second). It defaults to 60Hz.
1660	///
1661	/// The movement is linear in time.
1662	///
1663	/// See also [LiveTestWidgetsFlutterBindingFramePolicy.benchmarkLive] for
1664	/// more accurate time control.
1665	/// {@endtemplate}
1666	Future<void> timedDrag(
1667	finders.FinderBase<Element> finder,
1668	Offset offset,
1669	Duration duration, {
1670	int? pointer,
1671	int buttons = kPrimaryButton,
1672	double frequency = `60.0`,
1673	bool warnIfMissed = `true`,
1674	}) {
1675	return timedDragFrom(
1676	getCenter(finder, warnIfMissed: warnIfMissed, callee: 'timedDrag'),
1677	offset,
1678	duration,
1679	pointer: pointer,
1680	buttons: buttons,
1681	frequency: frequency,
1682	);
1683	}
1684
1685	/// Attempts a series of [PointerEvent]s to simulate a drag operation in the
1686	/// `duration` time.
1687	///
1688	/// This is the timed version of [dragFrom]. This may or may not result in a
1689	/// [flingFrom] or ballistic animation, depending on the speed from
1690	/// `offset/duration`.
1691	///
1692	/// {@macro flutter.flutter_test.WidgetController.timedDrag}
1693	Future<void> timedDragFrom(
1694	Offset startLocation,
1695	Offset offset,
1696	Duration duration, {
1697	int? pointer,
1698	int buttons = kPrimaryButton,
1699	double frequency = `60.0`,
1700	}) {
1701	assert(frequency > `0`);
1702	final int intervals = duration.inMicroseconds * frequency ~/ `1E6`;
1703	assert(intervals > `1`);
1704	pointer ??= _getNextPointer();
1705	final List<Duration> timeStamps = <Duration>[
1706	for (int t = `0`; t <= intervals; t += `1`) duration * t ~/ intervals,
1707	];
1708	final List<Offset> offsets = <Offset>[
1709	startLocation,
1710	for (int t = `0`; t <= intervals; t += `1`) startLocation + offset * (t / intervals),
1711	];
1712	final List<PointerEventRecord> records = <PointerEventRecord>[
1713	PointerEventRecord(Duration.zero, <PointerEvent>[
1714	PointerAddedEvent(position: startLocation),
1715	PointerDownEvent(position: startLocation, pointer: pointer, buttons: buttons),
1716	]),
1717	...<PointerEventRecord>[
1718	for (int t = `0`; t <= intervals; t += `1`)
1719	PointerEventRecord(timeStamps[t], <PointerEvent>[
1720	PointerMoveEvent(
1721	timeStamp: timeStamps[t],
1722	position: offsets[t + `1`],
1723	delta: offsets[t + `1`] - offsets[t],
1724	pointer: pointer,
1725	buttons: buttons,
1726	),
1727	]),
1728	],
1729	PointerEventRecord(duration, <PointerEvent>[
1730	PointerUpEvent(
1731	timeStamp: duration,
1732	position: offsets.last,
1733	pointer: pointer,
1734	// The PointerData received from the engine with
1735	// change = PointerChange.up, which translates to PointerUpEvent,
1736	// doesn't provide the button field.
1737	// buttons: buttons,
1738	),
1739	]),
1740	];
1741	return TestAsyncUtils.guard<void>(() async {
1742	await handlePointerEventRecord(records);
1743	});
1744	}
1745
1746	/// The next available pointer identifier.
1747	///
1748	/// This is the default pointer identifier that will be used the next time the
1749	/// [startGesture] method is called without an explicit pointer identifier.
1750	int get nextPointer => _nextPointer;
1751
1752	static int _nextPointer = `1`;
1753
1754	static int _getNextPointer() {
1755	final int result = _nextPointer;
1756	_nextPointer += `1`;
1757	return result;
1758	}
1759
1760	TestGesture _createGesture({
1761	int? pointer,
1762	required PointerDeviceKind kind,
1763	required int buttons,
1764	}) {
1765	return TestGesture(
1766	dispatcher: sendEventToBinding,
1767	kind: kind,
1768	pointer: pointer ?? _getNextPointer(),
1769	buttons: buttons,
1770	);
1771	}
1772
1773	/// Creates gesture and returns the [TestGesture] object which you can use
1774	/// to continue the gesture using calls on the [TestGesture] object.
1775	///
1776	/// You can use [startGesture] instead if your gesture begins with a down
1777	/// event.
1778	Future<TestGesture> createGesture({
1779	int? pointer,
1780	PointerDeviceKind kind = PointerDeviceKind.touch,
1781	int buttons = kPrimaryButton,
1782	}) async {
1783	return _createGesture(pointer: pointer, kind: kind, buttons: buttons);
1784	}
1785
1786	/// Creates a gesture with an initial appropriate starting gesture at a
1787	/// particular point, and returns the [TestGesture] object which you can use
1788	/// to continue the gesture. Usually, the starting gesture will be a down event,
1789	/// but if [kind] is set to [PointerDeviceKind.trackpad], the gesture will start
1790	/// with a panZoomStart gesture.
1791	///
1792	/// You can use [createGesture] if your gesture doesn't begin with an initial
1793	/// down or panZoomStart gesture.
1794	///
1795	/// See also:
1796	/// [WidgetController.drag], a method to simulate a drag.*
1797	/// [WidgetController.timedDrag], a method to simulate the drag of a given*
1798	/// widget in a given duration. It sends move events at a given frequency and
1799	/// it is useful when there are listeners involved.
1800	/// [WidgetController.fling], a method to simulate a fling.*
1801	Future<TestGesture> startGesture(
1802	Offset downLocation, {
1803	int? pointer,
1804	PointerDeviceKind kind = PointerDeviceKind.touch,
1805	int buttons = kPrimaryButton,
1806	}) async {
1807	final TestGesture result = _createGesture(pointer: pointer, kind: kind, buttons: buttons);
1808	if (kind == PointerDeviceKind.trackpad) {
1809	await result.panZoomStart(downLocation);
1810	} else {
1811	await result.down(downLocation);
1812	}
1813	return result;
1814	}
1815
1816	/// Forwards the given location to the binding's hitTest logic.
1817	HitTestResult hitTestOnBinding(Offset location, {int? viewId}) {
1818	viewId ??= view.viewId;
1819	final HitTestResult result = HitTestResult();
1820	binding.hitTestInView(result, location, viewId);
1821	return result;
1822	}
1823
1824	/// Forwards the given pointer event to the binding.
1825	Future<void> sendEventToBinding(PointerEvent event) {
1826	return TestAsyncUtils.guard<void>(() async {
1827	binding.handlePointerEvent(event);
1828	});
1829	}
1830
1831	/// Calls [debugPrint] with the given message.
1832	///
1833	/// This is overridden by the WidgetTester subclass to use the test binding's
1834	/// [TestWidgetsFlutterBinding.debugPrintOverride], so that it appears on the
1835	/// console even if the test is logging output from the application.
1836	@protected
1837	void printToConsole(String message) {
1838	debugPrint(message);
1839	}
1840
1841	// GEOMETRY
1842
1843	/// Returns the point at the center of the given widget.
1844	///
1845	/// {@template flutter.flutter_test.WidgetController.getCenter.warnIfMissed}
1846	/// If `warnIfMissed` is true (the default is false), then the returned
1847	/// coordinate is checked to see if a hit test at the returned location would
1848	/// actually include the specified element in the [HitTestResult], and if not,
1849	/// a warning is printed to the console.
1850	///
1851	/// The `callee` argument is used to identify the method that should be
1852	/// referenced in messages regarding `warnIfMissed`. It can be ignored unless
1853	/// this method is being called from another that is forwarding its own
1854	/// `warnIfMissed` parameter (see e.g. the implementation of [tap]).
1855	/// {@endtemplate}
1856	Offset getCenter(
1857	finders.FinderBase<Element> finder, {
1858	bool warnIfMissed = `false`,
1859	String callee = 'getCenter',
1860	}) {
1861	return _getElementPoint(
1862	finder,
1863	(Size size) => size.center(Offset.zero),
1864	warnIfMissed: warnIfMissed,
1865	callee: callee,
1866	);
1867	}
1868
1869	/// Returns the point at the top left of the given widget.
1870	///
1871	/// {@macro flutter.flutter_test.WidgetController.getCenter.warnIfMissed}
1872	Offset getTopLeft(
1873	finders.FinderBase<Element> finder, {
1874	bool warnIfMissed = `false`,
1875	String callee = 'getTopLeft',
1876	}) {
1877	return _getElementPoint(
1878	finder,
1879	(Size size) => Offset.zero,
1880	warnIfMissed: warnIfMissed,
1881	callee: callee,
1882	);
1883	}
1884
1885	/// Returns the point at the top right of the given widget. This
1886	/// point is not inside the object's hit test area.
1887	///
1888	/// {@macro flutter.flutter_test.WidgetController.getCenter.warnIfMissed}
1889	Offset getTopRight(
1890	finders.FinderBase<Element> finder, {
1891	bool warnIfMissed = `false`,
1892	String callee = 'getTopRight',
1893	}) {
1894	return _getElementPoint(
1895	finder,
1896	(Size size) => size.topRight(Offset.zero),
1897	warnIfMissed: warnIfMissed,
1898	callee: callee,
1899	);
1900	}
1901
1902	/// Returns the point at the bottom left of the given widget. This
1903	/// point is not inside the object's hit test area.
1904	///
1905	/// {@macro flutter.flutter_test.WidgetController.getCenter.warnIfMissed}
1906	Offset getBottomLeft(
1907	finders.FinderBase<Element> finder, {
1908	bool warnIfMissed = `false`,
1909	String callee = 'getBottomLeft',
1910	}) {
1911	return _getElementPoint(
1912	finder,
1913	(Size size) => size.bottomLeft(Offset.zero),
1914	warnIfMissed: warnIfMissed,
1915	callee: callee,
1916	);
1917	}
1918
1919	/// Returns the point at the bottom right of the given widget. This
1920	/// point is not inside the object's hit test area.
1921	///
1922	/// {@macro flutter.flutter_test.WidgetController.getCenter.warnIfMissed}
1923	Offset getBottomRight(
1924	finders.FinderBase<Element> finder, {
1925	bool warnIfMissed = `false`,
1926	String callee = 'getBottomRight',
1927	}) {
1928	return _getElementPoint(
1929	finder,
1930	(Size size) => size.bottomRight(Offset.zero),
1931	warnIfMissed: warnIfMissed,
1932	callee: callee,
1933	);
1934	}
1935
1936	/// Whether warnings relating to hit tests not hitting their mark should be
1937	/// fatal (cause the test to fail).
1938	///
1939	/// Some methods, e.g. [tap], have an argument `warnIfMissed` which causes a
1940	/// warning to be displayed if the specified [Finder] indicates a widget and
1941	/// location that, were a pointer event to be sent to that location, would not
1942	/// actually send any events to the widget (e.g. because the widget is
1943	/// obscured, or the location is off-screen, or the widget is transparent to
1944	/// pointer events).
1945	///
1946	/// This warning was added in 2021. In ordinary operation this warning is
1947	/// non-fatal since making it fatal would be a significantly breaking change
1948	/// for anyone who already has tests relying on the ability to target events
1949	/// using finders where the events wouldn't reach the widgets specified by the
1950	/// finders in question.
1951	///
1952	/// However, doing this is usually unintentional. To make the warning fatal,
1953	/// thus failing any tests where it occurs, this property can be set to true.
1954	///
1955	/// Typically this is done using a `flutter_test_config.dart` file, as described
1956	/// in the documentation for the [flutter_test] library.
1957	static bool hitTestWarningShouldBeFatal = `false`;
1958
1959	/// Finds one hit-testable Offset in the given `textRangeContext`'s render
1960	/// object.
1961	Offset? _findHitTestableOffsetIn(finders.TextRangeContext textRangeContext) {
1962	TestAsyncUtils.guardSync();
1963	final TextRange range = textRangeContext.textRange;
1964	assert(range.isNormalized);
1965	assert(range.isValid);
1966	final Offset renderParagraphPaintOffset = textRangeContext.renderObject.localToGlobal(
1967	Offset.zero,
1968	);
1969	assert(renderParagraphPaintOffset.isFinite);
1970
1971	int spanStart = range.start;
1972	while (spanStart < range.end) {
1973	switch (_findEndOfSpan(textRangeContext.renderObject.text, spanStart, range.end)) {
1974	case (final HitTestTarget target, final int endIndex):
1975	// Uses BoxHeightStyle.tight in getBoxesForSelection to make sure the
1976	// returned boxes don't extend outside of the hit-testable region.
1977	final Iterable<Offset> testOffsets = textRangeContext.renderObject
1978	.getBoxesForSelection(TextSelection(baseOffset: spanStart, extentOffset: endIndex))
1979	// Try hit-testing the center of each TextBox.
1980	.map((TextBox textBox) => textBox.toRect().center);
1981
1982	for (final Offset localOffset in testOffsets) {
1983	final HitTestResult result = HitTestResult();
1984	final Offset globalOffset = localOffset + renderParagraphPaintOffset;
1985	binding.hitTestInView(result, globalOffset, textRangeContext.view.view.viewId);
1986	if (result.path.any((HitTestEntry entry) => entry.target == target)) {
1987	return globalOffset;
1988	}
1989	}
1990	spanStart = endIndex;
1991	case (_, final int endIndex):
1992	spanStart = endIndex;
1993	case `null`:
1994	break;
1995	}
1996	}
1997	return `null`;
1998	}
1999
2000	Offset _getElementPoint(
2001	finders.FinderBase<Element> finder,
2002	Offset Function(Size size) sizeToPoint, {
2003	required bool warnIfMissed,
2004	required String callee,
2005	}) {
2006	TestAsyncUtils.guardSync();
2007	final Iterable<Element> elements = finder.evaluate();
2008	if (elements.isEmpty) {
2009	throw FlutterError(
2010	'The finder "$finder" (used in a call to "$callee()") could not find any matching widgets.',
2011	);
2012	}
2013	if (elements.length > `1`) {
2014	throw FlutterError(
2015	'The finder "$finder" (used in a call to "$callee()") ambiguously found multiple matching widgets. The "$callee()" method needs a single target.',
2016	);
2017	}
2018	final Element element = elements.single;
2019	final RenderObject? renderObject = element.renderObject;
2020	if (renderObject == `null`) {
2021	throw FlutterError(
2022	'The finder "$finder" (used in a call to "$callee()") found an element, but it does not have a corresponding render object. '
2023	'Maybe the element has not yet been rendered?',
2024	);
2025	}
2026	if (renderObject is! RenderBox) {
2027	throw FlutterError(
2028	'The finder "$finder" (used in a call to "$callee()") found an element whose corresponding render object is not a RenderBox (it is a ${renderObject.runtimeType}: "$renderObject"). '
2029	'Unfortunately "$callee()" only supports targeting widgets that correspond to RenderBox objects in the rendering.',
2030	);
2031	}
2032	final RenderBox box = element.renderObject! as RenderBox;
2033	final Offset location = box.localToGlobal(sizeToPoint(box.size));
2034	if (warnIfMissed) {
2035	final FlutterView view = _viewOf(finder);
2036	final HitTestResult result = HitTestResult();
2037	binding.hitTestInView(result, location, view.viewId);
2038	final bool found = result.path.any((HitTestEntry entry) => entry.target == box);
2039	if (!found) {
2040	final RenderView renderView = binding.renderViews.firstWhere(
2041	(RenderView r) => r.flutterView == view,
2042	);
2043	final bool outOfBounds = !(Offset.zero & renderView.size).contains(location);
2044	if (hitTestWarningShouldBeFatal) {
2045	throw FlutterError.fromParts(<DiagnosticsNode>[
2046	ErrorSummary('Finder specifies a widget that would not receive pointer events.'),
2047	ErrorDescription(
2048	'A call to $callee() with finder "$finder" derived an Offset ($location) that would not hit test on the specified widget.',
2049	),
2050	ErrorHint(
2051	'Maybe the widget is actually off-screen, or another widget is obscuring it, or the widget cannot receive pointer events.',
2052	),
2053	if (outOfBounds)
2054	ErrorHint(
2055	'Indeed, $location is outside the bounds of the root of the render tree, ${renderView.size}.',
2056	),
2057	box.toDiagnosticsNode(
2058	name: 'The finder corresponds to this RenderBox',
2059	style: DiagnosticsTreeStyle.singleLine,
2060	),
2061	ErrorDescription('The hit test result at that offset is: $result'),
2062	ErrorDescription(
2063	'If you expected this target not to be able to receive pointer events, pass "warnIfMissed: false" to "$callee()".',
2064	),
2065	ErrorDescription(
2066	'To make this error into a non-fatal warning, set WidgetController.hitTestWarningShouldBeFatal to false.',
2067	),
2068	]);
2069	}
2070	printToConsole(
2071	'\n'
2072	'Warning: A call to $callee() with finder "$finder" derived an Offset ($location) that would not hit test on the specified widget.\n'
2073	'Maybe the widget is actually off-screen, or another widget is obscuring it, or the widget cannot receive pointer events.\n'
2074	'${outOfBounds ? "Indeed, $location is outside the bounds of the root of the render tree, ${renderView.size}.\n" : ""}'
2075	'The finder corresponds to this RenderBox: $box\n'
2076	'The hit test result at that offset is: $result\n'
2077	'${StackTrace.current}'
2078	'To silence this warning, pass "warnIfMissed: false" to "$callee()".\n'
2079	'To make this warning fatal, set WidgetController.hitTestWarningShouldBeFatal to true.\n',
2080	);
2081	}
2082	}
2083	return location;
2084	}
2085
2086	/// Returns the size of the given widget. This is only valid once
2087	/// the widget's render object has been laid out at least once.
2088	Size getSize(finders.FinderBase<Element> finder) {
2089	TestAsyncUtils.guardSync();
2090	final Element element = finder.evaluate().single;
2091	final RenderBox box = element.renderObject! as RenderBox;
2092	return box.size;
2093	}
2094
2095	/// Simulates sending physical key down and up events.
2096	///
2097	/// This only simulates key events coming from a physical keyboard, not from a
2098	/// soft keyboard.
2099	///
2100	/// Specify `platform` as one of the platforms allowed in
2101	/// [Platform.operatingSystem] to make the event appear to be from
2102	/// that type of system. If not specified, defaults to "web" on web, and the
2103	/// operating system name based on [defaultTargetPlatform] everywhere else.
2104	///
2105	/// Specify the `physicalKey` for the event to override what is included in
2106	/// the simulated event. If not specified, it uses a default from the US
2107	/// keyboard layout for the corresponding logical `key`.
2108	///
2109	/// Specify the `character` for the event to override what is included in the
2110	/// simulated event. If not specified, it uses a default derived from the
2111	/// logical `key`.
2112	///
2113	/// Keys that are down when the test completes are cleared after each test.
2114	///
2115	/// This method sends both the key down and the key up events, to simulate a
2116	/// key press. To simulate individual down and/or up events, see
2117	/// [sendKeyDownEvent] and [sendKeyUpEvent].
2118	///
2119	/// Returns true if the key down event was handled by the framework.
2120	///
2121	/// See also:
2122	///
2123	/// - [sendKeyDownEvent] to simulate only a key down event.
2124	/// - [sendKeyUpEvent] to simulate only a key up event.
2125	Future<bool> sendKeyEvent(
2126	LogicalKeyboardKey key, {
2127	String? platform,
2128	String? character,
2129	PhysicalKeyboardKey? physicalKey,
2130	}) async {
2131	final bool handled = await simulateKeyDownEvent(
2132	key,
2133	platform: platform,
2134	character: character,
2135	physicalKey: physicalKey,
2136	);
2137	// Internally wrapped in async guard.
2138	await simulateKeyUpEvent(key, platform: platform, physicalKey: physicalKey);
2139	return handled;
2140	}
2141
2142	/// Simulates sending a physical key down event.
2143	///
2144	/// This only simulates key down events coming from a physical keyboard, not
2145	/// from a soft keyboard.
2146	///
2147	/// Specify `platform` as one of the platforms allowed in
2148	/// [Platform.operatingSystem] to make the event appear to be from
2149	/// that type of system. If not specified, defaults to "web" on web, and the
2150	/// operating system name based on [defaultTargetPlatform] everywhere else.
2151	///
2152	/// Specify the `physicalKey` for the event to override what is included in
2153	/// the simulated event. If not specified, it uses a default from the US
2154	/// keyboard layout for the corresponding logical `key`.
2155	///
2156	/// Specify the `character` for the event to override what is included in the
2157	/// simulated event. If not specified, it uses a default derived from the
2158	/// logical `key`.
2159	///
2160	/// Keys that are down when the test completes are cleared after each test.
2161	///
2162	/// Returns true if the key event was handled by the framework.
2163	///
2164	/// See also:
2165	///
2166	/// - [sendKeyUpEvent] and [sendKeyRepeatEvent] to simulate the corresponding
2167	/// key up and repeat event.
2168	/// - [sendKeyEvent] to simulate both the key up and key down in the same call.
2169	Future<bool> sendKeyDownEvent(
2170	LogicalKeyboardKey key, {
2171	String? platform,
2172	String? character,
2173	PhysicalKeyboardKey? physicalKey,
2174	}) async {
2175	// Internally wrapped in async guard.
2176	return simulateKeyDownEvent(
2177	key,
2178	platform: platform,
2179	character: character,
2180	physicalKey: physicalKey,
2181	);
2182	}
2183
2184	/// Simulates sending a physical key up event through the system channel.
2185	///
2186	/// This only simulates key up events coming from a physical keyboard,
2187	/// not from a soft keyboard.
2188	///
2189	/// Specify `platform` as one of the platforms allowed in
2190	/// [Platform.operatingSystem] to make the event appear to be from
2191	/// that type of system. If not specified, defaults to "web" on web, and the
2192	/// operating system name based on [defaultTargetPlatform] everywhere else.
2193	///
2194	/// Specify the `physicalKey` for the event to override what is included in
2195	/// the simulated event. If not specified, it uses a default from the US
2196	/// keyboard layout for the corresponding logical `key`.
2197	///
2198	/// Returns true if the key event was handled by the framework.
2199	///
2200	/// See also:
2201	///
2202	/// - [sendKeyDownEvent] and [sendKeyRepeatEvent] to simulate the
2203	/// corresponding key down and repeat event.
2204	/// - [sendKeyEvent] to simulate both the key up and key down in the same call.
2205	Future<bool> sendKeyUpEvent(
2206	LogicalKeyboardKey key, {
2207	String? platform,
2208	PhysicalKeyboardKey? physicalKey,
2209	}) async {
2210	// Internally wrapped in async guard.
2211	return simulateKeyUpEvent(key, platform: platform, physicalKey: physicalKey);
2212	}
2213
2214	/// Simulates sending a key repeat event from a physical keyboard.
2215	///
2216	/// This only simulates key repeat events coming from a physical keyboard, not
2217	/// from a soft keyboard.
2218	///
2219	/// Specify `platform` as one of the platforms allowed in
2220	/// [Platform.operatingSystem] to make the event appear to be from
2221	/// that type of system. If not specified, defaults to "web" on web, and the
2222	/// operating system name based on [defaultTargetPlatform] everywhere else.
2223	///
2224	/// Specify the `physicalKey` for the event to override what is included in
2225	/// the simulated event. If not specified, it uses a default from the US
2226	/// keyboard layout for the corresponding logical `key`.
2227	///
2228	/// Specify the `character` for the event to override what is included in the
2229	/// simulated event. If not specified, it uses a default derived from the
2230	/// logical `key`.
2231	///
2232	/// Keys that are down when the test completes are cleared after each test.
2233	///
2234	/// Returns true if the key event was handled by the framework.
2235	///
2236	/// See also:
2237	///
2238	/// - [sendKeyDownEvent] and [sendKeyUpEvent] to simulate the corresponding
2239	/// key down and up event.
2240	/// - [sendKeyEvent] to simulate both the key up and key down in the same call.
2241	Future<bool> sendKeyRepeatEvent(
2242	LogicalKeyboardKey key, {
2243	String? platform,
2244	String? character,
2245	PhysicalKeyboardKey? physicalKey,
2246	}) async {
2247	// Internally wrapped in async guard.
2248	return simulateKeyRepeatEvent(
2249	key,
2250	platform: platform,
2251	character: character,
2252	physicalKey: physicalKey,
2253	);
2254	}
2255
2256	/// Returns the rect of the given widget. This is only valid once
2257	/// the widget's render object has been laid out at least once.
2258	Rect getRect(finders.FinderBase<Element> finder) =>
2259	Rect.fromPoints(getTopLeft(finder), getBottomRight(finder));
2260
2261	/// Attempts to find the [SemanticsNode] of first result from `finder`.
2262	///
2263	/// If the object identified by the finder doesn't own it's semantic node,
2264	/// this will return the semantics data of the first ancestor with semantics.
2265	/// The ancestor's semantic data will include the child's as well as
2266	/// other nodes that have been merged together.
2267	///
2268	/// If the [SemanticsNode] of the object identified by the finder is
2269	/// force-merged into an ancestor (e.g. via the [MergeSemantics] widget)
2270	/// the node into which it is merged is returned. That node will include
2271	/// all the semantics information of the nodes merged into it.
2272	///
2273	/// Will throw a [StateError] if the finder returns more than one element or
2274	/// if no semantics are found or are not enabled.
2275	// TODO(pdblasi-google): Deprecate this and point references to semantics.find. See https://github.com/flutter/flutter/issues/112670.
2276	SemanticsNode getSemantics(finders.FinderBase<Element> finder) => semantics.find(finder);
2277
2278	/// Enable semantics in a test by creating a [SemanticsHandle].
2279	///
2280	/// The handle must be disposed at the end of the test.
2281	SemanticsHandle ensureSemantics() {
2282	return binding.ensureSemantics();
2283	}
2284
2285	/// Given a widget `W` specified by [finder] and a [Scrollable] widget `S` in
2286	/// its ancestry tree, this scrolls `S` so as to make `W` visible.
2287	///
2288	/// Usually the `finder` for this method should be labeled `skipOffstage:
2289	/// false`, so that the [Finder] deals with widgets that are off the screen
2290	/// correctly.
2291	///
2292	/// This does not work when `S` is long enough, and `W` far away enough from
2293	/// the displayed part of `S`, that `S` has not yet cached `W`'s element.
2294	/// Consider using [scrollUntilVisible] in such a situation.
2295	///
2296	/// See also:
2297	///
2298	/// [Scrollable.ensureVisible], which is the production API used to*
2299	/// implement this method.
2300	Future<void> ensureVisible(finders.FinderBase<Element> finder) =>
2301	Scrollable.ensureVisible(element(finder));
2302
2303	/// Repeatedly scrolls a [Scrollable] by `delta` in the
2304	/// [Scrollable.axisDirection] direction until a widget matching `finder` is
2305	/// visible.
2306	///
2307	/// Between each scroll, advances the clock by `duration` time.
2308	///
2309	/// Scrolling is performed until the start of the `finder` is visible. This is
2310	/// due to the default parameter values of the [Scrollable.ensureVisible] method.
2311	///
2312	/// If `scrollable` is `null`, a [Finder] that looks for a [Scrollable] is
2313	/// used instead.
2314	///
2315	/// If `continuous` is `true`, the gesture will be reused to simulate the effect
2316	/// of actual finger scrolling, which is useful when used alongside listeners
2317	/// like [GestureDetector.onTap]. The default is `false`.
2318	///
2319	/// Throws a [StateError] if `finder` is not found after `maxScrolls` scrolls.
2320	///
2321	/// This is different from [ensureVisible] in that this allows looking for
2322	/// `finder` that is not yet built. The caller must specify the scrollable
2323	/// that will build child specified by `finder` when there are multiple
2324	/// [Scrollable]s.
2325	///
2326	/// See also:
2327	///
2328	/// [dragUntilVisible], which implements the body of this method.*
2329	Future<void> scrollUntilVisible(
2330	finders.FinderBase<Element> finder,
2331	double delta, {
2332	finders.FinderBase<Element>? scrollable,
2333	int maxScrolls = `50`,
2334	Duration duration = const Duration(milliseconds: `50`),
2335	bool continuous = `false`,
2336	}) {
2337	assert(maxScrolls > `0`);
2338	scrollable ??= finders.find.byType(Scrollable);
2339	return TestAsyncUtils.guard<void>(() async {
2340	Offset moveStep;
2341	switch (widget<Scrollable>(scrollable!).axisDirection) {
2342	case AxisDirection.up:
2343	moveStep = Offset(`0`, delta);
2344	case AxisDirection.down:
2345	moveStep = Offset(`0`, -delta);
2346	case AxisDirection.left:
2347	moveStep = Offset(delta, `0`);
2348	case AxisDirection.right:
2349	moveStep = Offset(-delta, `0`);
2350	}
2351	await dragUntilVisible(
2352	finder,
2353	scrollable,
2354	moveStep,
2355	maxIteration: maxScrolls,
2356	duration: duration,
2357	continuous: continuous,
2358	);
2359	});
2360	}
2361
2362	/// Repeatedly drags `view` by `moveStep` until `finder` is visible.
2363	///
2364	/// Between each drag, advances the clock by `duration`.
2365	///
2366	/// Throws a [StateError] if `finder` is not found after `maxIteration`
2367	/// drags.
2368	///
2369	/// See also:
2370	///
2371	/// [scrollUntilVisible], which wraps this method with an API that is more*
2372	/// convenient when dealing with a [Scrollable].
2373	Future<void> dragUntilVisible(
2374	finders.FinderBase<Element> finder,
2375	finders.FinderBase<Element> view,
2376	Offset moveStep, {
2377	int maxIteration = `50`,
2378	Duration duration = const Duration(milliseconds: `50`),
2379	bool continuous = `false`,
2380	}) {
2381	return TestAsyncUtils.guard<void>(() async {
2382	TestGesture? gesture;
2383	while (maxIteration > `0` && finder.evaluate().isEmpty) {
2384	if (continuous) {
2385	gesture ??= await startGesture(getCenter(view, warnIfMissed: `true`));
2386	await gesture.moveBy(moveStep);
2387	} else {
2388	await drag(view, moveStep);
2389	}
2390	await pump(duration);
2391	maxIteration -= `1`;
2392	}
2393	await gesture?.up();
2394	await Scrollable.ensureVisible(element(finder));
2395	});
2396	}
2397	}
2398
2399	/// Variant of [WidgetController] that can be used in tests running
2400	/// on a device.
2401	///
2402	/// This is used, for instance, by [FlutterDriver].
2403	class LiveWidgetController extends WidgetController {
2404	/// Creates a widget controller that uses the given binding.
2405	LiveWidgetController(super.binding);
2406
2407	@override
2408	Future<void> pump([Duration? duration]) async {
2409	if (duration != `null`) {
2410	await Future<void>.delayed(duration);
2411	}
2412	binding.scheduleFrame();
2413	await binding.endOfFrame;
2414	}
2415
2416	@override
2417	Future<int> pumpAndSettle([Duration duration = const Duration(milliseconds: `100`)]) {
2418	assert(duration > Duration.zero);
2419	return TestAsyncUtils.guard<int>(() async {
2420	int count = `0`;
2421	do {
2422	await pump(duration);
2423	count += `1`;
2424	} while (binding.hasScheduledFrame);
2425	return count;
2426	});
2427	}
2428
2429	@override
2430	Future<List<Duration>> handlePointerEventRecord(List<PointerEventRecord> records) {
2431	assert(records.isNotEmpty);
2432	return TestAsyncUtils.guard<List<Duration>>(() async {
2433	final List<Duration> handleTimeStampDiff = <Duration>[];
2434	DateTime? startTime;
2435	for (final PointerEventRecord record in records) {
2436	final DateTime now = clock.now();
2437	startTime ??= now;
2438	// So that the first event is promised to receive a zero timeDiff.
2439	final Duration timeDiff = record.timeDelay - now.difference(startTime);
2440	if (timeDiff.isNegative) {
2441	// This happens when something (e.g. GC) takes a long time during the
2442	// processing of the events.
2443	// Flush all past events.
2444	handleTimeStampDiff.add(-timeDiff);
2445	record.events.forEach(binding.handlePointerEvent);
2446	} else {
2447	await Future<void>.delayed(timeDiff);
2448	handleTimeStampDiff.add(
2449	// Recalculating the time diff for getting exact time when the event
2450	// packet is sent. For a perfect Future.delayed like the one in a
2451	// fake async this new diff should be zero.
2452	clock.now().difference(startTime) - record.timeDelay,
2453	);
2454	record.events.forEach(binding.handlePointerEvent);
2455	}
2456	}
2457
2458	return handleTimeStampDiff;
2459	});
2460	}
2461	}
2462