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.

  1. In the repository settings, enable Actions → General → Allow GitHub Actions to create and approve pull requests.

  2. 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: write
    

    The issues trigger runs Renovate as soon as you tick a checkbox in the Dependency Dashboard issue. Input: flutterSdkChannel (default stable). 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.

  3. Add a renovate.json with 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 committed pubspec.lock. All updates in one pull request, raising the lower bounds. Majors (and minors of 0.x dependencies) are only offered up to the newest version that resolves, so they need no approval and go into the same pull request. analyzer is the exception: its constraint is widened instead of bumped (^13.3.0 becomes >=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 under dependencies changed; otherwise its version and changelog stay untouched.
    • application — for repositories with a committed pubspec.lock. All minor and patch updates in one pull request, plus a full pub upgrade. Majors (and minors of 0.x dependencies) get one pull request per dependency, without approval. Every update is released.

    Pub workspaces are supported; Renovate finds every member on its own.

  4. Add the finish job as the last job of your CI workflow, and make sure the workflow has a workflow_dispatch trigger:

    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, default squash), but only the commit whose CI run was approved. Then it dispatches the CI workflow on the default branch: a merge made with GITHUB_TOKEN triggers no push run, so without the dispatch nothing would be released. Set dispatchWorkflow to dispatch a different workflow. On red CI, or when the merge fails, it comments on the pull request and mentions the repository owner.

  5. Remove the pub entry from .github/dependabot.yml. Keep github-actions; security alerts stay with Dependabot in the repository settings.

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

  1. Renovate opens the pull request and requests your review, so you get a notification.
  2. 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.
  3. Green CI: the pull request is merged and released automatically. Red CI: you get a comment with a mention. The dart-test-tools-renovate-fix skill 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 same renovate/all branch. The post-upgrade step ignores them, so a pull request with only such updates gets no changelog entry and no version bump.
  • Your own postUpgradeTasks are 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) or reviewers (the workflow sets them).
  • Do not add rules for the dart-version or flutter-version datasources that change versioning, allowedVersions or overrideDatasource. 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.md and 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-infos and 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-compat leaves 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 a pubspec.yaml at the root.
  • --force replaces existing hooks that setup_hooks did not generate, for example the ones of dart_pre_commit. Without it, setup_hooks refuses 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.