A sample command-line application with an entrypoint in bin/, library code
in lib/, and example unit test in test/.
AI agent skills
This package bundles agent skills
under skills/. Projects that depend on dart_test_tools can install them into
their agent with:
dart run skills@ get dart_test_tools
| Skill | Purpose |
|---|---|
dart-test-tools-renovate-fix |
Check out a red Renovate pull request, re-run its post-upgrade step locally, validate the package the way CI does and help fix it. |
dart-test-tools-native-update |
Regenerate the native platform projects of a flutter app from the current Flutter templates, keep the template updates and restore the project's own identifiers and customisations. |
dart-test-tools-cli-help |
Answer questions about the command line tools in bin/ by running them with --help. |
To add a new skill, scaffold it with dart run skills@ create — the directory
name must be prefixed with dart-test-tools-.
Dependency updates with Renovate
Dependencies and SDK constraints are updated by self-hosted Renovate, run weekly by the
reusable renovate.yml workflow with the job's own GITHUB_TOKEN. All updates of a
week land in one pull request by github-actions[bot]. Its single commit also contains
the resolved lockfile, analyzer plugin pins, build_runner output, formatting,
dart fix and a changelog entry with a patch release. Your CI checks the pull request,
and a finish job at its end merges it when CI is green.
Setting up a repository
These steps also migrate a repository that used the former auto-update.yml workflow.
-
In the repository settings, enable Actions → General → Allow GitHub Actions to create and approve pull requests.
-
Replace the caller of
auto-update.yml(if any) with.github/workflows/renovate.yml:name: Automatic dependency updates on: workflow_dispatch: schedule: - cron: "15 3 * * 1" issues: types: - edited jobs: renovate: name: Renovate uses: Skycoder42/dart_test_tools/.github/workflows/renovate.yml@main permissions: contents: write pull-requests: write issues: write statuses: writeThe
issuestrigger runs Renovate as soon as you tick a checkbox in the Dependency Dashboard issue. Input:flutterSdkChannel(defaultstable). Non-breaking updates are held back at the newest version that resolves together with all other dependencies; with the library preset also together with the dependencies the Flutter SDK pins (see Flutter compatibility). With the library preset this applies to breaking updates as well; with the application preset they are never held back. The held back updates are listed at the bottom of the Dependency Dashboard. -
Add a
renovate.jsonwith one of the two presets:{ "$schema": "https://docs.renovatebot.com/renovate-schema.json", "extends": ["github>Skycoder42/dart_test_tools//renovate/library"] }library— for packages without a committedpubspec.lock. All updates in one pull request, raising the lower bounds. Majors (and minors of0.xdependencies) are only offered up to the newest version that resolves, so they need no approval and go into the same pull request.analyzeris the exception: its constraint is widened instead of bumped (^13.3.0becomes>=13.3.0 <15.0.0), so older analyzer versions stay allowed. A package is only released (changelog entry and patch bump) if an SDK constraint was raised or the upper bound of an entry underdependencieschanged; otherwise its version and changelog stay untouched.application— for repositories with a committedpubspec.lock. All minor and patch updates in one pull request, plus a fullpub upgrade. Majors (and minors of0.xdependencies) get one pull request per dependency, without approval. Every update is released.
Pub workspaces are supported; Renovate finds every member on its own.
-
Add the finish job as the last job of your CI workflow, and make sure the workflow has a
workflow_dispatchtrigger:on: workflow_dispatch: # ... jobs: # ... renovate: name: Renovate needs: - ci # every job of the workflow if: ${{ !cancelled() }} uses: Skycoder42/dart_test_tools/.github/workflows/renovate-finish.yml@main permissions: contents: write pull-requests: write actions: write with: needs: ${{ toJSON(needs) }}The job only acts on pull requests opened by Renovate. On green CI it merges the pull request (
mergeMethod, defaultsquash), but only the commit whose CI run was approved. Then it dispatches the CI workflow on the default branch: a merge made withGITHUB_TOKENtriggers nopushrun, so without the dispatch nothing would be released. SetdispatchWorkflowto dispatch a different workflow. On red CI, or when the merge fails, it comments on the pull request and mentions the repository owner. -
Remove the
pubentry from.github/dependabot.yml. Keepgithub-actions; security alerts stay with Dependabot in the repository settings. -
Recommended: a ruleset on the default branch that requires pull requests and your status checks, but no approving reviews. A required review blocks the finish job's merge unless you also approve the pull request itself. Protect release tags with a tag ruleset and publishing workflows with an environment approval.
A Dependency Dashboard issue left over from an earlier Renovate setup under another identity (an app, a token) is not reused — Renovate opens a new one. Close the old one by hand.
Day-to-day
- Renovate opens the pull request and requests your review, so you get a notification.
- Look at the diff, then Approve workflows to run — every push to a Renovate branch needs this approval before CI runs, also from the GitHub mobile app.
- Green CI: the pull request is merged and released automatically. Red CI: you get a
comment with a mention. The
dart-test-tools-renovate-fixskill reproduces and repairs it locally.
Renovate does not rebase its pull request when the default branch moves, only on conflicts. After a fix landed on the default branch, tick the rebase checkbox in the pull request and run the Renovate workflow by hand (or wait for the schedule), then approve the new runs. If you push a fix onto the Renovate branch instead, CI runs without approval and the pull request is merged when green. Renovate stops updating an edited branch; ticking the rebase checkbox rebuilds it and drops your commit.
Customising
Your own packageRules in renovate.json are applied after the preset's. Use them to
ignore, pin or delay pub packages, or to move some of them into their own group. Keep in
mind:
- Other managers you enable (
enabledManagers) put their updates into the samerenovate/allbranch. The post-upgrade step ignores them, so a pull request with only such updates gets no changelog entry and no version bump. - Your own
postUpgradeTasksare refused: the workflow only allows Renovate to run the post-upgrade step of dart_test_tools. - Do not set
automerge(the finish job merges),schedule(the caller's cron decides — both together can turn runs into no-ops) orreviewers(the workflow sets them). - Do not add rules for the
dart-versionorflutter-versiondatasources that changeversioning,allowedVersionsoroverrideDatasource. They would bring back Dart patch versions that never shipped with Flutter, or bare-version SDK constraints. - Every pub group gets its own pull request with its own patch release. Once one is
merged, the others conflict on
CHANGELOG.mdand the version, Renovate rebuilds them, and they need a new approval.
Pre-build command
Some repositories may need to run custom code to cleanup the repository. Set a
pre-build command in the pubspec.yaml of the repository root (the workspace
root, for pub workspaces):
renovate:
pre_build_command: echo "my command"
The post-upgrade step runs it in the directory of that pubspec, after dependency
resolution and before build_runner. A non-zero exit code fails the
post-upgrade step.
By default, the command only runs for pub updates. If files that the command
works on are updated by other Renovate managers (e.g. a custom regex manager),
list those managers as well. Use the manager name Renovate reports in the
upgrade, i.e. regex or jsonata for custom managers, not custom.regex:
renovate:
pre_build_extra_managers: regex # or a list: [regex, npm]
pre_build_command: dart run tool/regenerate.dart
For an update of only these managers, the post-upgrade step runs pub get and
the command in the repository root, and nothing else: no pub upgrade, no
build_runner, no formatting or fixes, no changelog entry or release. Updates
of managers that are not listed are ignored.
The command is a single string for all platforms, run with /bin/sh -c (or
cmd.exe /c on Windows). Platform specific commands are not supported.
Git hooks
setup_hooks installs two git hooks that check your changes before they leave your
machine. They need no configuration. Add dart_test_tools as dev dependency, then run
once per checkout:
dart run dart_test_tools:setup_hooks
- pre-commit formats the staged Dart files with
dart format. If that changed anything, the commit is aborted: review the changes, stage them and commit again. - pre-push runs
dart analyze --fatal-infosand the flutter compatibility check (dart run dart_test_tools:flutter_compat, see below) in parallel and fails if one of them fails. While they run, a progress indicator counts the completed checks. Each check prints one result line as soon as it finished, and its output only if it failed.
Options:
--no-flutter-compatleaves the compatibility check out of the pre-push hook. Use it for packages that are deliberately not usable from Flutter apps, and for repositories without apubspec.yamlat the root.--forcereplaces existing hooks thatsetup_hooksdid not generate, for example the ones ofdart_pre_commit. Without it,setup_hooksrefuses to overwrite them.
Rerun setup_hooks after updating dart_test_tools to get the current version of the
hooks. To skip them once, use git commit --no-verify or git push --no-verify; CI still
runs the same checks.
Flutter compatibility
flutter-compat (or dart run dart_test_tools:flutter_compat) checks that a Dart package
can be used from a Flutter app: its SDK constraints must allow the Dart and Flutter
versions of the installed Flutter SDK, and its dependencies must resolve together with
the packages the Flutter SDK pins.