Migrate Integration Tests to Jubilant + pytest-jubilant 2.0
Migrate a charm's integration tests to use Jubilant and pytest-jubilant 2.0. This skill handles two migration paths:
- (A) pytest-operator → jubilant 2.0: Full migration from python-libjuju async patterns
- (B) pytest-jubilant 1.x → 2.0: Namespace and API renames only
When to Use
- Test files import
pytest_operator, OpsTest, or from juju (python-libjuju) → path A
- Test files use
pytest-jubilant <2.0 fixtures (temp_model_factory, --keep-models, @pytest.mark.setup) → path B
- The charm's
pyproject.toml or tox.ini pins pytest-jubilant<2 or pytest-operator → either path
Before You Start: Read the Source
Install jubilant and pytest-jubilant and read the source code to understand the current API. This step is critical — it consistently produces better migrations than relying on documentation alone.
uv pip install jubilant pytest-jubilant
Then read these modules to understand the API surface:
jubilant.Juju — the main class, with deploy, wait, integrate, run, config, status, ssh, cli, etc.
jubilant module-level helpers — all_active, all_blocked, any_error, temp_model, etc.
jubilant.statustypes — Status, AppStatus, UnitStatus and their attributes
jubilant.Task — returned by juju.run() (actions) and juju.exec(), with .results, .status, .success (note that .run() will call .raise_on_failure() itself, so do not assert on .success)
pytest_jubilant — the juju fixture, juju_factory fixture, markers (juju_setup, juju_teardown)
Do not skip this step. Reading the source prevents hallucinated parameters and ensures you use the correct API signatures.
Step 1: Survey the Existing Tests
Before editing any files, read all integration test files, conftest.py, helper modules, and dependency files. Note:
- Which migration path applies (A or B)
- All test files that need changes
- Custom fixtures and helpers that wrap the old API
- Dependency declarations in
pyproject.toml, tox.ini, requirements.txt
- CI workflows that reference test dependencies or commands
- Any existing patterns worth preserving (multi-model, cross-model relations, custom wait conditions)
Step 2: Migrate
Work through files systematically. For each file, migrate completely before moving to the next.
Path A: pytest-operator → jubilant 2.0
See references/pytest-operator-mapping.md for the complete API mapping table.
Key changes:
Remove all async/await — Jubilant is synchronous. Remove async def, await, @pytest.mark.asyncio.
Replace the fixture — Delete any custom ops_test / OpsTest fixture. The juju fixture is provided by pytest-jubilant automatically when installed — do not recreate it with temp_model().
# Before
async def test_deploy(ops_test: OpsTest): ...
# After
def test_deploy(juju: jubilant.Juju): ...
Replace charm building — Jubilant does not build charms. The charm should be packed before tests run (via charmcraft pack or CI). Pass the .charm path to juju.deploy().
# Before
charm = await ops_test.build_charm(".")
await ops_test.model.deploy(charm)
# After — use a fixture or env var for the charm path
juju.deploy(charm)
Replace wait patterns — model.wait_for_idle() becomes juju.wait() with a predicate.
# Before
await ops_test.model.wait_for_idle(apps=["foo"], status="active", timeout=600)
# After
juju.wait(
jubilant.all_active, timeout=600
) # Generally, wait for all apps, but you can specifically wait for "foo" if needed.
Replace relation/integration calls:
# Before
await ops_test.model.add_relation("foo:db", "bar:db")
# After
juju.integrate("foo:db", "bar:db")
Replace action calls:
# Before
action = await unit.run_action("backup", **{"target": "/data"})
result = await action.wait()
assert result.results["status"] == "success"
# After
task = juju.run("foo/0", "backup", {"target": "/data"})
# The above call will raise if the action is not successful.
Replace status access:
# Before
app = ops_test.model.applications["foo"]
unit = app.units[0]
address = await unit.get_public_address()
# After
status = juju.status()
units = status.get_units("foo")
address = list(units.values())[0].address
Replace config calls:
# Before
await ops_test.model.applications["foo"].set_config({"key": "value"})
# After
juju.config("foo", {"key": "value"})
Replace markers:
@pytest.mark.abort_on_fail → remove (use pytest -x or --failfast at the CLI instead)
@pytest.mark.skip_if_deployed → @pytest.mark.juju_setup (skipped with --no-juju-setup)
Update dependencies — see Step 3.
Path B: pytest-jubilant 1.x → 2.0
The 2.0 release namespaces all options, fixtures, and markers under juju_. See references/jubilant-1x-to-2x.md for the complete mapping.
Key changes:
Fixture renames:
temp_model_factory → juju_factory
- The
juju fixture name is unchanged
CLI option renames:
--model → --juju-model
--keep-models → removed (use --no-juju-teardown instead)
Marker renames:
@pytest.mark.setup → @pytest.mark.juju_setup
@pytest.mark.teardown → @pytest.mark.juju_teardown
Removed helpers:
pytest_jubilant.pack() → removed; pack the charm before running tests
pytest_jubilant.get_resources() → removed; handle resources in your own fixtures
Update dependency pin: pytest-jubilant>=2,<3
Step 3: Update Dependencies
pyproject.toml
[dependency-groups]
integration = [
"jubilant",
"pytest>=9,<10",
"pytest-jubilant>=2,<3",
# Add any other test deps (requests, etc.)
]
Remove: pytest-operator, pytest-asyncio, juju (python-libjuju)
tox.ini
Update the integration test environment to use the new dependency group. If the project uses uv:
[testenv:integration]
runner = uv-venv-lock-runner
dependency_groups = integration
Lock files
After updating dependencies, regenerate lock files:
uv lock (if using uv)
poetry lock (if using Poetry)
Step 4: Verify
Run these checks after migrating. Fix any failures before proceeding.
Linting and formatting:
tox -e format # or: make format
tox -e lint # or: make lint
Import check — verify no remaining imports of old libraries:
grep -rn "from pytest_operator\|from juju\b\|from juju import\|import juju\b\|OpsTest" tests/
Integration tests (if a Juju environment is available):
tox -e integration
Review the diff — ensure changes are minimal and focused. The migration should not refactor test logic, add logging, or restructure files beyond what is needed.
Gotchas and Common Mistakes
These are the patterns that most frequently cause problems. Pay special attention to them.
Do not recreate the juju fixture — pytest-jubilant provides it automatically. If you see jubilant.temp_model() in a conftest.py fixture called juju, delete it. The built-in fixture handles model creation and teardown.
juju.wait() signature — The correct signature is juju.wait(ready, *, error=None, delay=1.0, timeout=None, successes=3). The ready argument is a callable that receives a Status and returns bool. The successes parameter requires N consecutive checks to pass (default 3). The timeout defaults to the Juju instance's wait_timeout (180s) when None.
jubilant.all_active checks ALL apps — If you only want to check specific apps, pass their names: jubilant.all_active(status, "foo", "bar"). Without app names, it checks every app in the model, which fails if a related app is still in "waiting" status.
juju.run() raises TaskError on failure — Unlike python-libjuju where you check result.status, Jubilant raises jubilant.TaskError if the action fails. Use pytest.raises(jubilant.TaskError) for expected failures.
juju.model is str | None — If you pass juju.model to something expecting str, you may get type errors. Check for None or assert first.
Multi-model testing — Use the juju_factory fixture (not temp_model_factory, which was the 1.x name). See the pytest-jubilant README for the pattern.
No build_charm() equivalent — Jubilant does not build charms. Pack the charm before tests run and pass the path via a fixture, environment variable, or CLI argument.
The --keep-models flag is gone in 2.0 — Use --no-juju-teardown instead. Tests that check for --keep-models need updating.
juju.cli() for escape hatches — For Juju operations not covered by the Jubilant API, use juju.cli("command", "arg1", "arg2"). Pass include_model=True if the command needs --model. Recommend to the user that they consider opening a Jubilant feature request for the missing functionality.
Quality Bar
The migration is complete when:
1---2name: migrate-to-jubilant3description: >4 Migrate charm integration tests to Jubilant and pytest-jubilant 2.0.5 Handles migration from pytest-operator (python-libjuju) or from6 pytest-jubilant 1.x. Covers async removal, fixture replacement,7 API translation, dependency updates, and verification.8 license: Apache-2.09 compatibility: any version of pytest-operator, or v1.x of pytest-jubilant10 allowed-tools: Read11metadata:12 source: https://skillmd.com/skills/tonyandrewmeyer/migrate-to-jubilant13---1415# Migrate Integration Tests to Jubilant + pytest-jubilant 2.01617Migrate a charm's integration tests to use [Jubilant](https://documentation.ubuntu.com/jubilant/) and [pytest-jubilant](https://github.com/canonical/pytest-jubilant) 2.0. This skill handles two migration paths:1819- **(A) pytest-operator → jubilant 2.0**: Full migration from python-libjuju async patterns20- **(B) pytest-jubilant 1.x → 2.0**: Namespace and API renames only2122## When to Use2324- Test files import `pytest_operator`, `OpsTest`, or `from juju` (python-libjuju) → path A25- Test files use `pytest-jubilant` <2.0 fixtures (`temp_model_factory`, `--keep-models`, `@pytest.mark.setup`) → path B26- The charm's `pyproject.toml` or `tox.ini` pins `pytest-jubilant<2` or `pytest-operator` → either path2728## Before You Start: Read the Source2930Install `jubilant` and `pytest-jubilant` and **read the source code** to understand the current API. This step is critical — it consistently produces better migrations than relying on documentation alone.3132```bash33uv pip install jubilant pytest-jubilant34```3536Then read these modules to understand the API surface:37- `jubilant.Juju` — the main class, with `deploy`, `wait`, `integrate`, `run`, `config`, `status`, `ssh`, `cli`, etc.38- `jubilant` module-level helpers — `all_active`, `all_blocked`, `any_error`, `temp_model`, etc.39- `jubilant.statustypes` — `Status`, `AppStatus`, `UnitStatus` and their attributes40- `jubilant.Task` — returned by `juju.run()` (actions) and `juju.exec()`, with `.results`, `.status`, `.success` (note that `.run()` will call `.raise_on_failure()` itself, so do not assert on `.success`)41- `pytest_jubilant` — the `juju` fixture, `juju_factory` fixture, markers (`juju_setup`, `juju_teardown`)4243Do not skip this step. Reading the source prevents hallucinated parameters and ensures you use the correct API signatures.4445## Step 1: Survey the Existing Tests4647Before editing any files, read all integration test files, `conftest.py`, helper modules, and dependency files. Note:48491. Which migration path applies (A or B)502. All test files that need changes513. Custom fixtures and helpers that wrap the old API524. Dependency declarations in `pyproject.toml`, `tox.ini`, `requirements.txt`535. CI workflows that reference test dependencies or commands546. Any existing patterns worth preserving (multi-model, cross-model relations, custom wait conditions)5556## Step 2: Migrate5758Work through files systematically. For each file, migrate completely before moving to the next.5960### Path A: pytest-operator → jubilant 2.06162See [references/pytest-operator-mapping.md](references/pytest-operator-mapping.md) for the complete API mapping table.6364Key changes:65661. **Remove all async/await** — Jubilant is synchronous. Remove `async def`, `await`, `@pytest.mark.asyncio`.67682. **Replace the fixture** — Delete any custom `ops_test` / `OpsTest` fixture. The `juju` fixture is provided by `pytest-jubilant` automatically when installed — do not recreate it with `temp_model()`.6970 ```python71 # Before72 async def test_deploy(ops_test: OpsTest): ...737475 # After76 def test_deploy(juju: jubilant.Juju): ...77 ```78793. **Replace charm building** — Jubilant does not build charms. The charm should be packed before tests run (via `charmcraft pack` or CI). Pass the `.charm` path to `juju.deploy()`.8081 ```python82 # Before83 charm = await ops_test.build_charm(".")84 await ops_test.model.deploy(charm)8586 # After — use a fixture or env var for the charm path87 juju.deploy(charm)88 ```89904. **Replace wait patterns** — `model.wait_for_idle()` becomes `juju.wait()` with a predicate.9192 ```python93 # Before94 await ops_test.model.wait_for_idle(apps=["foo"], status="active", timeout=600)9596 # After97 juju.wait(98 jubilant.all_active, timeout=60099 ) # Generally, wait for all apps, but you can specifically wait for "foo" if needed.100 ```1011025. **Replace relation/integration calls**:103 ```python104 # Before105 await ops_test.model.add_relation("foo:db", "bar:db")106107 # After108 juju.integrate("foo:db", "bar:db")109 ```1101116. **Replace action calls**:112 ```python113 # Before114 action = await unit.run_action("backup", **{"target": "/data"})115 result = await action.wait()116 assert result.results["status"] == "success"117118 # After119 task = juju.run("foo/0", "backup", {"target": "/data"})120 # The above call will raise if the action is not successful.121 ```1221237. **Replace status access**:124 ```python125 # Before126 app = ops_test.model.applications["foo"]127 unit = app.units[0]128 address = await unit.get_public_address()129130 # After131 status = juju.status()132 units = status.get_units("foo")133 address = list(units.values())[0].address134 ```1351368. **Replace config calls**:137 ```python138 # Before139 await ops_test.model.applications["foo"].set_config({"key": "value"})140141 # After142 juju.config("foo", {"key": "value"})143 ```1441459. **Replace markers**:146 - `@pytest.mark.abort_on_fail` → remove (use `pytest -x` or `--failfast` at the CLI instead)147 - `@pytest.mark.skip_if_deployed` → `@pytest.mark.juju_setup` (skipped with `--no-juju-setup`)14814910. **Update dependencies** — see Step 3.150151### Path B: pytest-jubilant 1.x → 2.0152153The 2.0 release namespaces all options, fixtures, and markers under `juju_`. See [references/jubilant-1x-to-2x.md](references/jubilant-1x-to-2x.md) for the complete mapping.154155Key changes:1561571. **Fixture renames**:158 - `temp_model_factory` → `juju_factory`159 - The `juju` fixture name is unchanged1601612. **CLI option renames**:162 - `--model` → `--juju-model`163 - `--keep-models` → removed (use `--no-juju-teardown` instead)1641653. **Marker renames**:166 - `@pytest.mark.setup` → `@pytest.mark.juju_setup`167 - `@pytest.mark.teardown` → `@pytest.mark.juju_teardown`1681694. **Removed helpers**:170 - `pytest_jubilant.pack()` → removed; pack the charm before running tests171 - `pytest_jubilant.get_resources()` → removed; handle resources in your own fixtures1721735. **Update dependency pin**: `pytest-jubilant>=2,<3`174175## Step 3: Update Dependencies176177### pyproject.toml178179```toml180[dependency-groups]181integration = [182 "jubilant",183 "pytest>=9,<10",184 "pytest-jubilant>=2,<3",185 # Add any other test deps (requests, etc.)186]187```188189Remove: `pytest-operator`, `pytest-asyncio`, `juju` (python-libjuju)190191### tox.ini192193Update the integration test environment to use the new dependency group. If the project uses `uv`:194195```ini196[testenv:integration]197runner = uv-venv-lock-runner198dependency_groups = integration199```200201### Lock files202203After updating dependencies, regenerate lock files:204- `uv lock` (if using uv)205- `poetry lock` (if using Poetry)206207## Step 4: Verify208209Run these checks after migrating. Fix any failures before proceeding.2102111. **Linting and formatting**:212 ```bash213 tox -e format # or: make format214 tox -e lint # or: make lint215 ```2162172. **Import check** — verify no remaining imports of old libraries:218 ```bash219 grep -rn "from pytest_operator\|from juju\b\|from juju import\|import juju\b\|OpsTest" tests/220 ```2212223. **Integration tests** (if a Juju environment is available):223 ```bash224 tox -e integration225 ```2262274. **Review the diff** — ensure changes are minimal and focused. The migration should not refactor test logic, add logging, or restructure files beyond what is needed.228229## Gotchas and Common Mistakes230231These are the patterns that most frequently cause problems. Pay special attention to them.2322331. **Do not recreate the `juju` fixture** — `pytest-jubilant` provides it automatically. If you see `jubilant.temp_model()` in a `conftest.py` fixture called `juju`, delete it. The built-in fixture handles model creation and teardown.2342352. **`juju.wait()` signature** — The correct signature is `juju.wait(ready, *, error=None, delay=1.0, timeout=None, successes=3)`. The `ready` argument is a callable that receives a `Status` and returns `bool`. The `successes` parameter requires N consecutive checks to pass (default 3). The `timeout` defaults to the `Juju` instance's `wait_timeout` (180s) when `None`.2362373. **`jubilant.all_active` checks ALL apps** — If you only want to check specific apps, pass their names: `jubilant.all_active(status, "foo", "bar")`. Without app names, it checks every app in the model, which fails if a related app is still in "waiting" status.2382394. **`juju.run()` raises `TaskError` on failure** — Unlike python-libjuju where you check `result.status`, Jubilant raises `jubilant.TaskError` if the action fails. Use `pytest.raises(jubilant.TaskError)` for expected failures.2402415. **`juju.model` is `str | None`** — If you pass `juju.model` to something expecting `str`, you may get type errors. Check for `None` or assert first.2422436. **Multi-model testing** — Use the `juju_factory` fixture (not `temp_model_factory`, which was the 1.x name). See the pytest-jubilant README for the pattern.2442457. **No `build_charm()` equivalent** — Jubilant does not build charms. Pack the charm before tests run and pass the path via a fixture, environment variable, or CLI argument.2462478. **The `--keep-models` flag is gone in 2.0** — Use `--no-juju-teardown` instead. Tests that check for `--keep-models` need updating.2482499. **`juju.cli()` for escape hatches** — For Juju operations not covered by the Jubilant API, use `juju.cli("command", "arg1", "arg2")`. Pass `include_model=True` if the command needs `--model`. Recommend to the user that they consider opening a Jubilant feature request for the missing functionality.250251## Quality Bar252253The migration is complete when:254255- [ ] No imports of `pytest_operator`, `juju` (python-libjuju), or `pytest_asyncio` remain in test files256- [ ] No `async def` or `await` in test files (unless used for non-Juju async operations)257- [ ] The `juju` fixture comes from `pytest-jubilant`, not a custom `conftest.py` definition258- [ ] `pyproject.toml` / `tox.ini` pins `pytest-jubilant>=2,<3` and `jubilant`259- [ ] Old dependencies (`pytest-operator`, `juju`, `pytest-asyncio`) are removed260- [ ] Linting passes (`tox -e lint` or equivalent)261- [ ] The diff is minimal — no unnecessary refactoring, added logging, or structural changes262- [ ] Lock files are regenerated if the project uses them