Skip to content

Commit 7d859ed

Browse files
authored
[api_summary] Add expectApiSummaryClean and --write/--check CLI flags (#2603)
Adds a `build_verify`-style one-liner test helper (`expectApiSummaryClean`) and companion `--write` (`-w`), `--check` (`-c`), and `--output` (`-o`) CLI flags to `package:api_summary` (`v1.1.0`). - **Programmatic Tear-Off (`expectApiSummaryClean`)**: - Verifies that a package's generated `ApiSummary` matches its checked-in golden file (`api.txt`, `api.json`, or `api.yaml`). - Because all parameters are optional and named (`packagePath` defaults to `Directory.current`), it can be passed directly as a tear-off to `test()`: ```dart import 'package:api_summary/api_summary.dart'; import 'package:test/scaffolding.dart'; void main() { test('api_summary', expectApiSummaryClean); } ``` - Throws `ApiSummaryVerificationException` with a compact line diff and copy-pasteable remediation command (`dart run api_summary --write`) without requiring `package:test` in `api_summary`'s runtime `dependencies`. - **CLI Enhancements (`bin/api_summary.dart`)**: - `-w, --write`: Writes the summary to the default golden file (`api.txt`, `api.json`, or `api.yaml`) in the package root. - `-c, --check`: Verifies that the existing golden file matches the current public API, exiting with code `1` on mismatch. - `-o, --output <file>`: Writes the summary to a custom file path instead of `stdout` (relative paths resolve relative to `--package-path`). - Enforces mutual exclusivity between `--write`, `--check`, and `--output` via an exhaustive record switch (exiting with code `64` on invalid combinations or unexpected positional arguments). - **Self-Dogfooding & Tests (`test/app_test.dart`)**: - Dogfoods `expectApiSummaryClean` for `api.txt`, `api.json`, and `api.yaml` and pre-compiles `bin/api_summary.dart` to a kernel `.dill` in `setUpAll` (cutting `test/app_test.dart` execution time from ~105s to ~44s).
1 parent d87eaf7 commit 7d859ed

10 files changed

Lines changed: 1038 additions & 116 deletions

File tree

‎pkgs/api_summary/CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
## 1.1.0
2+
3+
- Added `expectApiSummaryClean`, `ApiSummaryFormat`, and
4+
`ApiSummaryVerificationException` to support one-liner golden file verification
5+
in `dart test` (e.g. `test('api_summary', expectApiSummaryClean);`).
6+
- Added `--write` (`-w`), `--check` (`-c`), and `--output` (`-o`) flags to the
7+
`api_summary` CLI executable.
8+
19
## 1.0.0
210

311
- Initial stable release.

‎pkgs/api_summary/README.md‎

Lines changed: 26 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,16 @@ dart run api_summary
5151
(defaults to the current working directory).
5252
* `-f, --format`: The output format for the summary (`text`, `json`, or
5353
`yaml`). Defaults to `text`.
54+
* `-o, --output`: Write the summary to a file path instead of `stdout`
55+
(relative paths resolve relative to `--package-path`).
56+
* `-w, --write`: Write the summary to the default golden file (`api.txt`,
57+
`api.json`, or `api.yaml`, based on `--format`) in the package directory.
58+
* `-c, --check`: Verify that the golden file (`api.txt`, `api.json`, or
59+
`api.yaml`) matches the current public API, exiting with code `1` on mismatch.
5460
* `-h, --help`: Prints usage instructions.
5561

62+
Note: `--output`, `--write`, and `--check` are mutually exclusive.
63+
5664
## Programmatic Usage
5765

5866
You can also use this package programmatically inside your Dart projects, such
@@ -61,8 +69,8 @@ as in automated testing or continuous integration scripts.
6169
Add `api_summary` to your `pubspec.yaml`:
6270

6371
```yaml
64-
dependencies:
65-
api_summary: ^1.0.0
72+
dev_dependencies:
73+
api_summary: ^1.1.0
6674
```
6775
6876
### Basic Example
@@ -71,7 +79,6 @@ Call the `apiSummary` function to generate a package's public API
7179
representation:
7280

7381
```dart
74-
import 'dart:io';
7582
import 'package:api_summary/api_summary.dart';
7683
7784
void main() async {
@@ -125,38 +132,28 @@ base class MyCustomizer extends ApiSummaryCustomizer {
125132
```
126133

127134

128-
## Golden File / Diff Testing
135+
## Golden File / Diff Testing (`expectApiSummaryClean`)
136+
137+
A recommended practice is to verify in a unit test that your package's public
138+
API matches a checked-in `api.txt` golden file.
139+
140+
First, generate `api.txt` in your package root:
129141

130-
A common best practice with `api_summary` is to verify in a unit test that the
131-
generated summary matches a checked-in golden file (e.g. `api.txt`). If a
132-
developer introduces an accidental breaking change or adds a new public API
133-
element, the test will fail on the `diff`, prompting them to audit and
134-
intentionally update the golden file.
142+
```bash
143+
dart run api_summary --write
144+
```
135145

136-
Below is an example of such a test (available in the
137-
[test/app_test.dart](test/app_test.dart) file):
146+
Then wire up `expectApiSummaryClean` as a one-liner in `test/api_test.dart`:
138147

139148
```dart
140-
import 'dart:io';
141-
import 'package:path/path.dart' as p;
142-
import 'package:test/test.dart';
143149
import 'package:api_summary/api_summary.dart';
150+
import 'package:test/scaffolding.dart';
144151
145152
void main() {
146-
test('public API has not changed unexpectedly', () async {
147-
final packageDir = Directory.current.path;
148-
final goldenFile = File(p.join(packageDir, 'api.txt'));
149-
150-
final actualOutput = await apiSummary(packageDir);
151-
152-
if (!goldenFile.existsSync()) {
153-
// In a new setup or after updates, generate the golden file first
154-
goldenFile.writeAsStringSync(actualOutput.toString());
155-
fail('Golden file api.txt did not exist and has been generated. Please review and commit it.');
156-
}
157-
158-
final expectedOutput = goldenFile.readAsStringSync();
159-
expect(actualOutput.toString(), equals(expectedOutput));
160-
});
153+
test('api_summary', expectApiSummaryClean);
161154
}
162155
```
156+
157+
If a developer introduces a breaking change or adds a new public API element,
158+
`expectApiSummaryClean` fails the test with a compact line diff and instructs
159+
them to run `dart run api_summary --write` to update `api.txt`.

0 commit comments

Comments
 (0)