test:bundle
Generate test/bundle_<n>.g.dart entries that group every *_test.dart under test/, so flutter test compiles a few entries instead of every file on its own.
On this page
Basic Usage#
dart run dowel test:bundle \
&& flutter test --concurrency=3 test/bundle_[0-9]*.g.dart \
&& { [ ! -f test/bundle_alone.g.dart ] || flutter test test/bundle_alone.g.dart; }
The && chain stops when generation is refused, so a failed run never tests the entries of an earlier layout; bundle_alone.g.dart exists only when a file carries a // shard: alone line. The glob also matches any other bundle_<digit>...g.dart file you keep in test/, so name those differently, and an empty --only list writes no entry at all, so skip the run then.
flutter test compiles each test file on its own; with 120 files that is most of the run. One entry per shard compiles once per shard. The entries do not end in _test.dart, so a plain flutter test does not discover them and run every test twice. Add test/bundle*.g.dart to .gitignore and regenerate them wherever the tests run; test:bundle does not run flutter test itself.
Synopsis#
test:bundle {--shards=3} {--only=}
| Option | Default | Description |
|---|---|---|
--shards=N |
3 |
How many entries the dealt files are spread over. A positive integer; capped at the number of files left to deal. Anything else exits 1. |
--only=LISTFILE |
none | Bundle only the files in LISTFILE: one project-relative path per line (test/app/foo_test.dart), blank lines ignored. A relative LISTFILE resolves against the working directory. |
Every listed path must start with test/, hold no empty, . or .. segment, end in _test.dart, exist, and appear once; each file meets the same refusals as a full run. A list that names only lone files writes no shard, and an empty list writes no entry, removes the earlier ones and exits 0.
Exit codes: 0 when the entries are written (or an empty --only list cleared them), 1 on an invalid option or a refusal.
What It Writes#
Each entry is staged as <name>.tmp first, so a failed write leaves the earlier entries in place and removes what it staged. Then every earlier test/bundle_<n>.g.dart and test/bundle_alone.g.dart is removed (a leftover shard from a larger count would run its files twice; any other bundle*.g.dart is left alone) and the staged entries are renamed into place. A rename that fails after the old entries were removed can leave only some of the new ones, with the rest as .tmp files: fix the I/O error and run test:bundle again before running any entry. An entry imports each file under its own prefix and runs it inside a group named after its path:
// dart format width=80
// GENERATED by dowel test:bundle; do not edit, do not commit.
import 'package:flutter_test/flutter_test.dart';
import 'app/home_test.dart' as t0;
import 'widgets/text_test.dart' as t1;
void main() {
group('app/home_test.dart', t0.main);
group('widgets/text_test.dart', t1.main);
}
The file is laid out the way dart format writes it at language version 3.7 and later, so a dart format --set-exit-if-changed gate passes on it. Because every file shares one isolate per entry, a test must restore any process state it changes (a channel handler, a static); a single file still runs alone with flutter test <path>.
Shards and Lone Files#
Files are sorted bytewise, weighed by their line count, and dealt heaviest first onto whichever shard is lightest (ties by path, then by the lowest shard), so the same tree always deals the same way. Inside an entry the files are sorted by path again. Shards land in test/bundle_0.g.dart up to test/bundle_<N-1>.g.dart.
A file with a line that reads exactly // shard: alone (a latency budget that a busy neighbour makes flaky) goes to test/bundle_alone.g.dart instead, to run after the shards. A full run where every file is marked alone is refused; with --only it writes only test/bundle_alone.g.dart.
Refusals#
A file a bundle cannot run as written is refused, never skipped: a skipped file is coverage lost without a word. test:bundle names every offending file and the rule it breaks, exits 1 and writes nothing, so the earlier entries stay as they were.
| Rule | Why |
|---|---|
A path with a character outside [A-Za-z0-9_./-] |
The path lands inside a single-quoted Dart string. |
A line starting with @TestOn, @Tags, @Timeout, @Skip, @Retry or @OnPlatform |
A library annotation binds the file as a suite and means nothing inside a group. |
Not exactly one line starting void main() { |
A group body is synchronous; void main() async, Future<void> main (named in the message, as is FutureOr<void> main), two mains and no main are all refused. |
A flutter_test_config.dart below test/ |
Flutter looks the config up from each test file's directory upwards and stops at pubspec.yaml, so a bundle in test/ never sees it and the files beside it lose their wrapper. test/flutter_test_config.dart itself is allowed: it wraps a bundle the way it wraps every file. |
A path listed twice in --only |
The file would run twice. |
Gotchas#
| Mistake | Fix |
|---|---|
Committing test/bundle*.g.dart |
Ignore them and run test:bundle before flutter test; a committed entry drifts from the file list. |
Running flutter test with no paths after bundling |
It runs only the original *_test.dart files and gets no compile saving; pass the entries. |
| A golden test in a bundle | Flutter's default comparator resolves a golden image next to the entry file, test/, not next to the test's own directory; keep a golden test out of the bundle (an --only list of every other file) and run it on its own as well with flutter test <path>. |
| A test that leaves a static or a channel handler set | It now leaks into the files after it in the same entry; restore it in tearDown. |
| Expecting a refused file to be skipped | Fix the file: move the annotation into group or test arguments, make main synchronous, or move a nested config's setup into test/flutter_test_config.dart. |
Related Documentation#
- Commands: every builtin command, grouped by intent.