convenient_test and the Flutter test runner you can actually watch

The same tests, run off the simulator

The package description is a list of capabilities: write and debug tests easily, with full action history, time travel, screenshots, rapid re-execution, video records, interactivity, isolation and more.

The headline claim is a 5x speedup, and the mechanism is stated plainly. In addition to the standard way of integration tests, which is to run them on a real mobile device or a simulator, the package supports running the exact same testing code on your host computer, Windows, MacOS or Linux, with a similar experience. The reasoning given is that running on simulators or real devices is slow and hard to parallelise, while running on the host computer does not have that problem.

There is a caveat the author is careful about. In his own production application the improvement is more than 10x faster, but since he did not create public and reproducible tests, he does not want to claim such a big improvement, so the readme asks you to test it yourself.

The integration story is that you write code normally and execute it as if it were a widget test. The package does not require you to learn a new assertion vocabulary, and the readme notes that if you see weird fonts you may want to loadAppFonts, which points at the golden_toolkit package for loading fonts.

The audience is a Flutter team with real integration tests on a real app, and the first question for any adopter is whether the speedup holds for their tests, because a host execution is a different runtime from a device and some behaviour differs.

Action history and time travel through screenshots

The two features that distinguish this package from a standard integration test are the history and the screenshots.

The full action history shows the actions, taps and assertions taken in the tests with friendly descriptions, in a left panel. It is a structured log rendered as a list rather than a wall of text, so the question a failing test usually asks, what did the app do before this assertion, has an answer in the tool rather than in your scrollback.

Time travel is the same history with pictures attached. The question the readme poses is what the UI looked like when that button was tapped 50 steps ago, and the answer is a screenshot at that point in the run. Tapping an action shows its screenshots, and the readme notes you can use mouse wheels and dragging to zoom and pan them.

There is an honest note about the demonstration footage. The gif for this feature is outdated, and the newer version has an overview of all screenshots and a ruler for each screenshot.

The practical value is highest in the failure case. A test that fails on a device in CI, with no video and no way to reproduce, is a test you end up not running. Here the same run produces a visual trail, which is what makes a failure investigable without a device in your hand.

Video, interactivity and the dev manager

Recorded video is the other half of the diagnostic story. The readme says you can watch what has happened in full detail in a right panel, and the highlighted action stays in sync with the playing video, so tapping an action seeks the video to that moment. The video and the history are two views of the same record, which is why the time travel feature is worth having in a package that records video at all.

Interactivity addresses something Flutter does not normally allow. The readme notes you can temporarily play with the app interactively, and adds in parentheses that Flutter originally cannot interact with the app in test mode.

Rapid re-execution is the loop that makes the rest usable. Edit code, save, run, and the cycle completes within seconds rather than minutes, according to the readme.

The dev manager is what makes the host execution practical. In the repository layout there are seven packages under packages/, including convenient_test, convenient_test_common, convenient_test_common_dart, convenient_test_dev, convenient_test_manager, convenient_test_manager_dart and the manager's example. The manager is the piece that provides the interactive session and the fast loop, and the dev package is the one that stands alone.

The project uses fvm for Flutter version management, with an .fvmrc at the root, and the justfile drives the workflow.

Retryability: the change that affects how you read a red build

Retryability is the feature with the biggest effect on your existing test code, and the readme is blunt about it: no manual pump, wait or retry anymore, just write down what you want and the framework will retry and wait.

The example shows it:

await t.get(find.byTooltip('Fetch Data From Backend')).tap();
// OK even if "fetch data" needs undeterministic time interval. Will automatically pump, wait and retry.
await t.get(find.text('New Data')).should(findsOneWidget);

The tap does not assume the data has arrived. If the fetch is slow, the framework pumps and waits and tries again, and the subsequent assertion then sees the new data.

This is genuinely convenient and it changes the meaning of a failing test. A test that would have failed intermittently now passes, which is the point, but it also means the suite is less likely to tell you when the app has a genuine timing problem. The readme addresses that with flaky test awareness, promising no false alarms while no blindly ignoring, and the integration_test package, mockito and test are all still available for use.

The other entry in the same direction is the enhanced golden feature, a GUI to check golden changes, allow a few pixels to be different, and screenshot widgets above your widget. The readme marks it as a standalone feature that does not require the full convenient_test, and the utilities, entering text without replacing and pumping with run async, are standalone too.

The justfile, the packages and how you develop on it

The justfile is the clearest description of the repository's shape, because every target is a multi-package operation.

The pub-get target walks each package in turn:

    cd packages/convenient_test && fvm flutter pub get
    cd packages/convenient_test/example && fvm flutter pub get
    cd packages/convenient_test_common && fvm flutter pub get

The build-runner target runs build_runner with --delete-conflicting-outputs across the two manager packages, the format target uses dart format with a line length of 120, and analyze runs fvm flutter analyze. The all target chains pub-get, build-runner, format and analyze together.

There is also a gif-generation pipeline that takes the .mov files in doc/videos and produces the .gif files used in the readme, with ffmpeg and a filter expression, plus a target that scales a full video to a 4K version. The publish_all target patches the readme to swap the video placeholders for a YouTube link before publishing, and the comment in it notes that some patches in README.md have to be changed first.

For a contributor, that justfile is the whole workflow, and the fact that it is a justfile rather than a set of shell scripts means the commands are discoverable without reading the repository history.

Maturity, licence and what the readme does not tell you

The repository is not archived, and the last push was on 2026-10-08, with releases v1.6.2 on 2026-03-28, v1.6.1 on 2026-01-08 and v1.6.0 on 2025-12-27. The package is published on pub.dev as convenient_test, and the licence is MIT, so there is no obstacle to using it in a commercial application.

The stability claim is personal and specific. The readme says it has been used extensively in the author's own 200 thousand line Flutter app in a production environment, and that he integrates it with his CI infrastructure so it runs every day. That is a real data point about a large app under continuous use, and it is also one app, one author's conventions and one set of test practices.

The author is candid about the state of the documentation, saying the package and especially the doc are not yet perfect, and that you should open an issue if you have problems, which he usually answers quickly.

Two further notes from the readme are worth carrying. The quick demo video only contains features up to 2022.05, so the speedup and the enhanced golden are not in it. And the unreleased features section lists a monkey tester that randomly interacts with tappable and draggable regions of the app to try to find crashes, and a benchmark helper that benchmarks on all devices with one command, uploads to storage and generates reports. The author says he has been using these internally for a long time but has not found time to clean them up to open-source them, and invites requests.

For a reader, that last part is a good signal about where this package is heading, and a caution about which of the advertised capabilities are actually available today.

Editorial conclusion

convenient_test is a good fit for a Flutter team whose integration tests are slow and whose failures are hard to diagnose, because the same test code runs on the host machine and every action is recorded with a screenshot and a video you can scrub back through. It is a poor fit for a small project with three widget tests, since the dev manager and the extra packages cost more to set up than they save, and a poor fit if you need the test suite to run unchanged on a device in CI, since the host execution path is a different runtime. Before adopting, write one existing integration test in the new style and run it on your host, and read the section on flaky test awareness, because the automatic retry behaviour changes how a red build should be interpreted.

Frequently asked questions

Official sources

1. fzyzcjy/flutter_convenient_test on GitHub
2. Issues
3. License: MIT
4. README
5. Releases