# 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.

- [Basic Usage](#basic-usage)
- [Synopsis](#synopsis)
- [What It Writes](#what-it-writes)
- [Shards and Lone Files](#shards-and-lone-files)
- [Refusals](#refusals)
- [Gotchas](#gotchas)
- [Related Documentation](#related-documentation)

## Basic Usage

```bash
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](#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
// 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](https://anilcancakir.com/dowel/docs/commands/index.md): every builtin command, grouped by intent.
