Charm Linting and Testing Command Standardisation
Charms must provide a consistent, minimal set of named commands for formatting, linting, type checking, and testing. This makes it easier to work across charming teams and enables ecosystem-wide compatibility testing.
Based on spec OP061.
Required Commands
| Command |
Definition |
| (no args) |
Running the tool with no arguments must execute the lint and unit commands |
format |
Automatically format code (including tests) according to project style |
lint |
Report linting errors (ruff, pylint, flake8, isort, pydocstyle, bandit, etc.) and static type checking issues (pyright, ty, mypy). Must include Charmhub hosted charm libraries that this charm provides, if any; should include test code |
unit |
Run unit tests for the charm and its libs. Includes both deprecated Harness and state-transition (Scenario) framework tests |
integration |
Run integration tests against a real Juju controller. Includes pytest-operator, python-libjuju, and Jubilant tests |
docs |
Build documentation (if docs are in the repository). Should run make run in the docs directory |
Note: we use format (not the Go-style fmt) — this has been the charmcraft profile standard and aligns with other full-word commands.
Optional Commands
Charms may include additional commands as needed:
- Lib-specific commands (e.g.
static-lib)
- Combined commands (e.g.
static = static-charm + static-lib)
- Aliases (e.g.
fmt as alias for format)
functional tests — validate workload interactions without Juju (especially for machine charms)
Command Runners
Commands must be run with one of these tools:
| Tool |
Examples |
| tox |
tox, tox -e lint, tox -e unit -- -k test_foo |
| make |
make, make lint, make unit ARGS='-k test_foo' |
| just |
just, just lint, just unit |
The most highly recommended tool is the one used in charmcraft profiles — tox at present. Commands must work without additional arguments.
Monorepo Conventions
For repositories containing more than one charm:
format, lint, unit, integration must be available in each charm folderformat should be available at the top level, formatting all charmslint is ideally at the top level (may need to run per-charm for conflicting dependencies)unit and integration are ideally at the top level, running all testsdocs: at the top level if one set of docs; in each charm folder if separate docs
Documentation
Requirements for running commands (e.g. installing uv or tox) must be clearly documented in a CONTRIBUTING or HACKING file at the top level of the repository.
1---2name: charm-development-commands3description: Standard linting and testing commands for Juju charms. Use when setting up a charm project's test infrastructure, CI, or tox/make configuration. Defines the required command names and their meanings.4license: default5---67# Charm Linting and Testing Command Standardisation89Charms must provide a consistent, minimal set of named commands for formatting, linting, type checking, and testing. This makes it easier to work across charming teams and enables ecosystem-wide compatibility testing.1011Based on spec OP061.1213---1415## Required Commands1617| Command | Definition |18|---------|-----------|19| *(no args)* | Running the tool with no arguments must execute the `lint` and `unit` commands |20| `format` | Automatically format code (including tests) according to project style |21| `lint` | Report linting errors (ruff, pylint, flake8, isort, pydocstyle, bandit, etc.) **and** static type checking issues (pyright, ty, mypy). Must include Charmhub hosted charm libraries that this charm provides, if any; should include test code |22| `unit` | Run unit tests for the charm and its libs. Includes both deprecated Harness and state-transition (Scenario) framework tests |23| `integration` | Run integration tests against a real Juju controller. Includes pytest-operator, python-libjuju, and Jubilant tests |24| `docs` | Build documentation (if docs are in the repository). Should run `make run` in the docs directory |2526**Note**: we use `format` (not the Go-style `fmt`) — this has been the charmcraft profile standard and aligns with other full-word commands.2728---2930## Optional Commands3132Charms may include additional commands as needed:33- Lib-specific commands (e.g. `static-lib`)34- Combined commands (e.g. `static` = `static-charm` + `static-lib`)35- Aliases (e.g. `fmt` as alias for `format`)36- `functional` tests — validate workload interactions without Juju (especially for machine charms)3738---3940## Command Runners4142Commands must be run with one of these tools:4344| Tool | Examples |45|------|---------|46| **tox** | `tox`, `tox -e lint`, `tox -e unit -- -k test_foo` |47| **make** | `make`, `make lint`, `make unit ARGS='-k test_foo'` |48| **just** | `just`, `just lint`, `just unit` |4950The most highly recommended tool is the one used in charmcraft profiles — `tox` at present. Commands must work **without additional arguments**.5152---5354## Monorepo Conventions5556For repositories containing more than one charm:5758- `format`, `lint`, `unit`, `integration` must be available in **each charm folder**59- `format` should be available at the **top level**, formatting all charms60- `lint` is ideally at the top level (may need to run per-charm for conflicting dependencies)61- `unit` and `integration` are ideally at the top level, running all tests62- `docs`: at the top level if one set of docs; in each charm folder if separate docs6364---6566## Documentation6768Requirements for running commands (e.g. installing `uv` or `tox`) must be clearly documented in a **CONTRIBUTING** or **HACKING** file at the top level of the repository.
tonyandrewmeyer