WidgetTester class

Class that programmatically interacts with widgets and the test environment.

Typically, a test uses pumpWidget to load a widget tree (in a manner very similar to how runApp works in a Flutter application). Then, methods such as tap, drag, enterText, fling, longPress, etc, can be used to interact with the application. The application runs in a FakeAsync zone, which allows time to be stepped forward deliberately; this is done using the pump method.

The expect function can then be used to examine the state of the application, typically using Finders such as those in the find namespace, and Matchers such as findsOneWidget.

testWidgets('MyWidget', (WidgetTester tester) async {
  await tester.pumpWidget(const MyWidget());
  await tester.tap(find.text('Save'));
  await tester.pump(); // allow the application to handle
  await tester.pump(const Duration(seconds: 1)); // skip past the animation
  expect(find.text('Success'), findsOneWidget);
});

For convenience, instances of this class (such as the one provided by testWidgets) can be used as the vsync for AnimationController objects.

When the binding is LiveTestWidgetsFlutterBinding, events from LiveTestWidgetsFlutterBinding.deviceEventDispatcher will be handled in dispatchEvent. Thus, using flutter run to run a test lets one tap on the screen to generate Finders relevant to the test.

Inheritance
Implemented types

Properties

allElements Iterable<Element>
All elements currently in the widget tree (lazy pre-order traversal).
no setterinherited
allRenderObjects Iterable<RenderObject>
Render objects of all the widgets currently in the widget tree (lazy pre-order traversal).
no setterinherited
allStates Iterable<State<StatefulWidget>>
All states currently in the widget tree (lazy pre-order traversal).
no setterinherited
allWidgets Iterable<Widget>
All widgets currently in the widget tree (lazy pre-order traversal).
no setterinherited
binding TestWidgetsFlutterBinding
The binding instance used by the testing framework.
no setteroverride
hashCode int
The hash code for this object.
no setterinherited
hasRunningAnimations bool
Whether there are any transient callbacks scheduled.
no setter
layers List<Layer>
Returns a list of all the Layer objects in the rendering.
no setterinherited
nextPointer int
The next available pointer identifier.
no setterinherited
platformDispatcher TestPlatformDispatcher
The TestPlatformDispatcher that is being used in this test.
no setterinherited
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
semantics SemanticsController
Provides access to a SemanticsController for testing anything related to the Semantics tree.
no setterinherited
testDescription String
The description string of the test currently being run.
no setter
testTextInput TestTextInput
Returns the TestTextInput singleton.
no setter
view TestFlutterView
The TestFlutterView provided by default when testing with WidgetTester.pumpWidget.
no setterinherited

Methods

any(FinderBase<Element> finder) bool
Checks if finder exists in the tree.
inherited
createGesture({int? pointer, PointerDeviceKind kind = PointerDeviceKind.touch, int buttons = kPrimaryButton}) Future<TestGesture>
Creates gesture and returns the TestGesture object which you can use to continue the gesture using calls on the TestGesture object.
inherited
createTicker(TickerCallback onTick) Ticker
Creates a ticker with the given callback.
override
dispatchEvent(PointerEvent event, HitTestResult result) → void
Handler for device events caught by the binding in live test mode.
override
drag(FinderBase<Element> finder, Offset offset, {int? pointer, int buttons = kPrimaryButton, double touchSlopX = kDragSlopDefault, double touchSlopY = kDragSlopDefault, bool warnIfMissed = true, PointerDeviceKind kind = PointerDeviceKind.touch}) Future<void>
Attempts to drag the given widget by the given offset, by starting a drag in the middle of the widget.
inherited
dragFrom(Offset startLocation, Offset offset, {int? pointer, int buttons = kPrimaryButton, double touchSlopX = kDragSlopDefault, double touchSlopY = kDragSlopDefault, PointerDeviceKind kind = PointerDeviceKind.touch}) Future<void>
Attempts a drag gesture consisting of a pointer down, a move by the given offset, and a pointer up.
inherited
dragUntilVisible(FinderBase<Element> finder, FinderBase<Element> view, Offset moveStep, {int maxIteration = 50, Duration duration = const Duration(milliseconds: 50)}) Future<void>
Repeatedly drags view by moveStep until finder is visible.
inherited
element<T extends Element>(FinderBase<Element> finder) → T
The matching element in the widget tree.
inherited
elementList<T extends Element>(FinderBase<Element> finder) Iterable<T>
The matching elements in the widget tree.
inherited
ensureSemantics() SemanticsHandle
Enable semantics in a test by creating a SemanticsHandle.
inherited
ensureVisible(FinderBase<Element> finder) Future<void>
Given a widget W specified by finder and a Scrollable widget S in its ancestry tree, this scrolls S so as to make W visible.
inherited
enterText(FinderBase<Element> finder, String text) Future<void>
Give the text input widget specified by finder the focus and replace its content with text, as if it had been provided by the onscreen keyboard.
firstElement<T extends Element>(FinderBase<Element> finder) → T
The first matching element according to a depth-first pre-order traversal of the widget tree.
inherited
firstRenderObject<T extends RenderObject>(FinderBase<Element> finder) → T
The render object of the first matching widget according to a depth-first pre-order traversal of the widget tree.
inherited
firstState<T extends State<StatefulWidget>>(FinderBase<Element> finder) → T
The first matching state according to a depth-first pre-order traversal of the widget tree.
inherited
firstWidget<T extends Widget>(FinderBase<Element> finder) → T
The first matching widget according to a depth-first pre-order traversal of the widget tree.
inherited
fling(FinderBase<Element> finder, Offset offset, double speed, {int? pointer, int buttons = kPrimaryButton, Duration frameInterval = const Duration(milliseconds: 16), Offset initialOffset = Offset.zero, Duration initialOffsetDelay = const Duration(seconds: 1), bool warnIfMissed = true, PointerDeviceKind deviceKind = PointerDeviceKind.touch}) Future<void>
Attempts a fling gesture starting from the center of the given widget, moving the given distance, reaching the given speed.
inherited
flingFrom(Offset startLocation, Offset offset, double speed, {int? pointer, int buttons = kPrimaryButton, Duration frameInterval = const Duration(milliseconds: 16), Offset initialOffset = Offset.zero, Duration initialOffsetDelay = const Duration(seconds: 1), PointerDeviceKind deviceKind = PointerDeviceKind.touch}) Future<void>
Attempts a fling gesture starting from the given location, moving the given distance, reaching the given speed.
inherited
getBottomLeft(FinderBase<Element> finder, {bool warnIfMissed = false, String callee = 'getBottomLeft'}) Offset
Returns the point at the bottom left of the given widget. This point is not inside the object's hit test area.
inherited
getBottomRight(FinderBase<Element> finder, {bool warnIfMissed = false, String callee = 'getBottomRight'}) Offset
Returns the point at the bottom right of the given widget. This point is not inside the object's hit test area.
inherited
getCenter(FinderBase<Element> finder, {bool warnIfMissed = false, String callee = 'getCenter'}) Offset
Returns the point at the center of the given widget.
inherited
getRect(FinderBase<Element> finder) Rect
Returns the rect of the given widget. This is only valid once the widget's render object has been laid out at least once.
inherited
getRestorationData() Future<TestRestorationData>
Retrieves the current restoration data from the RestorationManager.
getSemantics(FinderBase<Element> finder) SemanticsNode
Attempts to find the SemanticsNode of first result from finder.
inherited
getSize(FinderBase<Element> finder) Size
Returns the size of the given widget. This is only valid once the widget's render object has been laid out at least once.
inherited
getTopLeft(FinderBase<Element> finder, {bool warnIfMissed = false, String callee = 'getTopLeft'}) Offset
Returns the point at the top left of the given widget.
inherited
getTopRight(FinderBase<Element> finder, {bool warnIfMissed = false, String callee = 'getTopRight'}) Offset
Returns the point at the top right of the given widget. This point is not inside the object's hit test area.
inherited
handlePointerEventRecord(Iterable<PointerEventRecord> records) Future<List<Duration>>
A simulator of how the framework handles a series of PointerEvents received from the Flutter engine.
override
hitTestOnBinding(Offset location, {int? viewId}) HitTestResult
Forwards the given location to the binding's hitTest logic.
override
idle() Future<void>
Acts as if the application went idle.
layerListOf(FinderBase<Element> finder) Iterable<Layer>
Find all layers that are children of the provided finder.
inherited
longPress(FinderBase<Element> finder, {int? pointer, int buttons = kPrimaryButton, bool warnIfMissed = true, PointerDeviceKind kind = PointerDeviceKind.touch}) Future<void>
Dispatch a pointer down / pointer up sequence (with a delay of kLongPressTimeout + kPressTimeout between the two events) at the center of the given widget, assuming it is exposed.
inherited
longPressAt(Offset location, {int? pointer, int buttons = kPrimaryButton, PointerDeviceKind kind = PointerDeviceKind.touch}) Future<void>
Dispatch a pointer down / pointer up sequence at the given location with a delay of kLongPressTimeout + kPressTimeout between the two events.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
pageBack() Future<void>
Makes an effort to dismiss the current page with a Material Scaffold or a CupertinoPageScaffold.
press(FinderBase<Element> finder, {int? pointer, int buttons = kPrimaryButton, bool warnIfMissed = true, PointerDeviceKind kind = PointerDeviceKind.touch}) Future<TestGesture>
Dispatch a pointer down at the center of the given widget, assuming it is exposed.
inherited
printToConsole(String message) → void
Calls debugPrint with the given message.
override
pump([Duration? duration, EnginePhase phase = EnginePhase.sendSemanticsUpdate]) Future<void>
Triggers a frame after duration amount of time.
override
pumpAndSettle([Duration duration = const Duration(milliseconds: 100), EnginePhase phase = EnginePhase.sendSemanticsUpdate, Duration timeout = const Duration(minutes: 10)]) Future<int>
Repeatedly calls pump with the given duration until there are no longer any frames scheduled. This will call pump at least once, even if no frames are scheduled when the function is called, to flush any pending microtasks which may themselves schedule a frame.
override
pumpBenchmark(Duration duration) Future<void>
Triggers a frame after duration amount of time, return as soon as the frame is drawn.
pumpFrames(Widget target, Duration maxDuration, [Duration interval = const Duration(milliseconds: 16, microseconds: 683)]) Future<void>
Repeatedly pump frames that render the target widget with a fixed time interval as many as maxDuration allows.
pumpWidget(Widget widget, [Duration? duration, EnginePhase phase = EnginePhase.sendSemanticsUpdate]) Future<void>
Renders the UI from the given widget.
renderObject<T extends RenderObject>(FinderBase<Element> finder) → T
The render object of the matching widget in the widget tree.
inherited
renderObjectList<T extends RenderObject>(FinderBase<Element> finder) Iterable<T>
The render objects of the matching widgets in the widget tree.
inherited
restartAndRestore() Future<void>
Simulates restoring the state of the widget tree after the application is restarted.
restoreFrom(TestRestorationData data) Future<void>
Restores the widget tree under test to the state described by the provided TestRestorationData.
runAsync<T>(Future<T> callback(), {Duration additionalTime = const Duration(milliseconds: 1000)}) Future<T?>
Runs a callback that performs real asynchronous work.
scrollUntilVisible(FinderBase<Element> finder, double delta, {FinderBase<Element>? scrollable, int maxScrolls = 50, Duration duration = const Duration(milliseconds: 50)}) Future<void>
Repeatedly scrolls a Scrollable by delta in the Scrollable.axisDirection direction until a widget matching finder is visible.
inherited
sendEventToBinding(PointerEvent event) Future<void>
Forwards the given pointer event to the binding.
override
sendKeyDownEvent(LogicalKeyboardKey key, {String platform = _defaultPlatform, String? character, PhysicalKeyboardKey? physicalKey}) Future<bool>
Simulates sending a physical key down event.
inherited
sendKeyEvent(LogicalKeyboardKey key, {String platform = _defaultPlatform, String? character, PhysicalKeyboardKey? physicalKey}) Future<bool>
Simulates sending physical key down and up events.
inherited
sendKeyRepeatEvent(LogicalKeyboardKey key, {String platform = _defaultPlatform, String? character, PhysicalKeyboardKey? physicalKey}) Future<bool>
Simulates sending a key repeat event from a physical keyboard.
inherited
sendKeyUpEvent(LogicalKeyboardKey key, {String platform = _defaultPlatform, PhysicalKeyboardKey? physicalKey}) Future<bool>
Simulates sending a physical key up event through the system channel.
inherited
showKeyboard(FinderBase<Element> finder) Future<void>
Give the text input widget specified by finder the focus, as if the onscreen keyboard had appeared.
startGesture(Offset downLocation, {int? pointer, PointerDeviceKind kind = PointerDeviceKind.touch, int buttons = kPrimaryButton}) Future<TestGesture>
Creates a gesture with an initial appropriate starting gesture at a particular point, and returns the TestGesture object which you can use to continue the gesture. Usually, the starting gesture will be a down event, but if kind is set to PointerDeviceKind.trackpad, the gesture will start with a panZoomStart gesture.
inherited
state<T extends State<StatefulWidget>>(FinderBase<Element> finder) → T
The matching state in the widget tree.
inherited
stateList<T extends State<StatefulWidget>>(FinderBase<Element> finder) Iterable<T>
The matching states in the widget tree.
inherited
takeAnnouncements() List<CapturedAccessibilityAnnouncement>
Returns a list of all the accessibility announcements made by the Flutter framework since the last time this function was called.
takeException() → dynamic
Returns the exception most recently caught by the Flutter framework.
tap(FinderBase<Element> finder, {int? pointer, int buttons = kPrimaryButton, bool warnIfMissed = true, PointerDeviceKind kind = PointerDeviceKind.touch}) Future<void>
Dispatch a pointer down / pointer up sequence at the center of the given widget, assuming it is exposed.
inherited
tapAt(Offset location, {int? pointer, int buttons = kPrimaryButton, PointerDeviceKind kind = PointerDeviceKind.touch}) Future<void>
Dispatch a pointer down / pointer up sequence at the given location.
inherited
tapOnText(FinderBase<TextRangeContext> textRangeFinder, {int? pointer, int buttons = kPrimaryButton}) Future<void>
Dispatch a pointer down / pointer up sequence at a hit-testable InlineSpan (typically a TextSpan) within the given text range.
inherited
timedDrag(FinderBase<Element> finder, Offset offset, Duration duration, {int? pointer, int buttons = kPrimaryButton, double frequency = 60.0, bool warnIfMissed = true}) Future<void>
Attempts to drag the given widget by the given offset in the duration time, starting in the middle of the widget.
inherited
timedDragFrom(Offset startLocation, Offset offset, Duration duration, {int? pointer, int buttons = kPrimaryButton, double frequency = 60.0}) Future<void>
Attempts a series of PointerEvents to simulate a drag operation in the duration time.
inherited
toString() String
A string representation of this object.
inherited
trackpadFling(FinderBase<Element> finder, Offset offset, double speed, {int? pointer, int buttons = kPrimaryButton, Duration frameInterval = const Duration(milliseconds: 16), Offset initialOffset = Offset.zero, Duration initialOffsetDelay = const Duration(seconds: 1), bool warnIfMissed = true}) Future<void>
Attempts a trackpad fling gesture starting from the center of the given widget, moving the given distance, reaching the given speed. A trackpad fling sends PointerPanZoom events instead of a sequence of touch events.
inherited
trackpadFlingFrom(Offset startLocation, Offset offset, double speed, {int? pointer, int buttons = kPrimaryButton, Duration frameInterval = const Duration(milliseconds: 16), Offset initialOffset = Offset.zero, Duration initialOffsetDelay = const Duration(seconds: 1)}) Future<void>
Attempts a fling gesture starting from the given location, moving the given distance, reaching the given speed. A trackpad fling sends PointerPanZoom events instead of a sequence of touch events.
inherited
verifyTickersWereDisposed([String when = 'when none should have been']) → void
Throws an exception if any tickers created by the WidgetTester are still active when the method is called.
viewOf(FinderBase<Element> finder) TestFlutterView
Finds the TestFlutterView that is the closest ancestor of the widget found by finder.
inherited
widget<T extends Widget>(FinderBase<Element> finder) → T
The matching widget in the widget tree.
inherited
widgetList<T extends Widget>(FinderBase<Element> finder) Iterable<T>
The matching widgets in the widget tree.
inherited

Operators

operator ==(Object other) bool
The equality operator.
inherited