How to filter a run

A run covers every charm in the charms directory unless you narrow it. Use --repo, --framework, --from-results, and --limit to check a single charm, a group of them, or just the first few — for a quick sanity-check, or to debug one failure without waiting for a full fleet run.

These instructions assume the charms directory is already populated. See How to run against the charm list if it is not.

Run one named charm

--repo accepts a case-insensitive regular expression matched against the directory name of each charm, so anchor the pattern to pin it to exactly one charm:

hyrum check unit --no-patch --repo '^charm-apt-mirror$'

Match a group of charms

Without the anchors, the same flag selects every charm whose name matches:

# Any charm whose directory name contains "apt":
hyrum check unit --no-patch --repo apt

# Any charm whose directory name begins with "mysql":
hyrum check unit --no-patch --repo '^mysql'

Filter by testing framework

If you only care about charms that use a particular testing framework, use --framework:

# Only charms that use the Scenario testing framework:
hyrum check unit --no-patch --framework scenario

Supported values for --framework: scenario, jubilant.

Rerun the charms that failed last time

To go back over only the charms that failed in an earlier run, point --from-results at that run’s saved results file:

hyrum check unit --from-results ~/.cache/hyrum/results/unit.auto.json

By default this selects the charms whose saved outcome was failed, timeout, runner_error, or patcher_error. Use --status to pick other outcomes; it is repeatable and comma-separated, and accepts not-passing for everything except passed:

# Rerun only the charms that timed out:
hyrum check unit --from-results ~/.cache/hyrum/results/unit.auto.json --status timeout

A run narrowed this way does not update the rolling results, since it would record every charm it did not run as skipped. Pass --save PATH to keep its results.

Run only the charms that passed a baseline

Many charms fail for reasons that predate the change under test. To run a patched check against only the charms that pass on your machine, first save a baseline:

hyrum check unit --no-patch --save ~/hyrum-runs/baseline.json

Then run a patched check using only the charms that passed in the baseline:

hyrum check unit --patch 'ops @ canonical:fix/my-change' \
    --from-results ~/hyrum-runs/baseline.json --status passed

Limit by count

--limit N stops once N charms have been selected to run, taken in the order hyrum discovers them, which is alphabetical:

# Run only the first runnable charm found:
hyrum check unit --no-patch --limit 1

Charms that the filters skip — legacy charms, charms with no Python source, charms without the requested target — do not count towards N. They still show up in the skipped tally, so the summary stays honest about what was looked at on the way there.

Combine filters

The filters compose, so you can pin a pattern and cap the count together:

hyrum check unit --no-patch --repo apt --limit 1

For what each status in the summary means, see the output reference.