testWidgets function
- @isTest
Runs the callback
inside the Flutter test environment.
Use this function for testing custom StatelessWidgets and StatefulWidgets.
The callback can be asynchronous (using async
/await
or
using explicit Futures).
There are two kinds of timeouts that can be specified. The timeout
argument specifies the backstop timeout implemented by the test
package.
If set, it should be relatively large (minutes). It defaults to ten minutes
for tests run by flutter test
, and is unlimited for tests run by flutter run
; specifically, it defaults to
TestWidgetsFlutterBinding.defaultTestTimeout.
The initialTimeout
argument specifies the timeout implemented by the
flutter_test
package itself. If set, it may be relatively small (seconds),
as it is automatically increased for some expensive operations, and can also
be manually increased by calling
AutomatedTestWidgetsFlutterBinding.addTime. The effective maximum value of
this timeout (even after calling addTime
) is the one specified by the
timeout
argument.
In general, timeouts are race conditions and cause flakes, so best practice is to avoid the use of timeouts in tests.
If the semanticsEnabled
parameter is set to true
,
WidgetTester.ensureSemantics will have been called before the tester is
passed to the callback
, and that handle will automatically be disposed
after the callback is finished. It defaults to true.
This function uses the test function in the test package to register the given callback as a test. The callback, when run, will be given a new instance of WidgetTester. The find object provides convenient widget Finders for use with the WidgetTester.
See also:
- AutomatedTestWidgetsFlutterBinding.addTime to learn more about timeout and how to manually increase timeouts.
Sample code
testWidgets('MyWidget', (WidgetTester tester) async {
await tester.pumpWidget(new MyWidget());
await tester.tap(find.text('Save'));
expect(find.text('Success'), findsOneWidget);
});
Implementation
@isTest
void testWidgets(
String description,
WidgetTesterCallback callback, {
bool skip = false,
test_package.Timeout timeout,
Duration initialTimeout,
bool semanticsEnabled = true,
}) {
final TestWidgetsFlutterBinding binding = TestWidgetsFlutterBinding.ensureInitialized() as TestWidgetsFlutterBinding;
final WidgetTester tester = WidgetTester._(binding);
test(
description,
() {
SemanticsHandle semanticsHandle;
if (semanticsEnabled == true) {
semanticsHandle = tester.ensureSemantics();
}
tester._recordNumberOfSemanticsHandles();
test_package.addTearDown(binding.postTest);
return binding.runTest(
() async {
debugResetSemanticsIdCounter();
await callback(tester);
semanticsHandle?.dispose();
},
tester._endOfTestVerifications,
description: description ?? '',
timeout: initialTimeout,
);
},
skip: skip,
timeout: timeout ?? binding.defaultTestTimeout,
);
}