pytest-jubilant is a pytest plugin for Jubilant.
Jubilant is a Python library that wraps the Juju CLI, primarily for use in charm integration tests. pytest-jubilant provides additional pytest-specific functionality on top of Jubilant.
Read more: pytest-jubilant's design goals
pytest-jubilant's features are available to use as long as it's installed in the Python environment where you're invoking pytest. The best way to ensure this is to add both pytest and pytest-jubilant to your dependencies like this.
# pyproject.toml
[dependency-groups]
integration = [
"pytest>=9,<10",
"pytest-jubilant>=2,<3",
]And ensure that the integration dependency group is installed when running your integration tests, for example with:
uv run --group integration pytest tests/integrationGet started writing your own Jubilant integration tests with the how-to guide in the Ops docs.
Read on for an explanation of the fixtures, CLI options, and markers provided by pytest-jubilant.
pytest-jubilant's fixtures are available as long as pytest-jubilant is installed. You can request a fixture by declaring it as an argument for the test that needs it.
This is a module-scoped fixture that creates a temporary Juju model and tears it down when the tests in the module have finished.
You can use combinations of the --juju-model, --no-juju-setup, and --no-juju-teardown options to reuse models across multiple integration test runs.
Tip
Use jubilant.Juju as the type annotation for the juju fixture in your tests for better linting and IDE autocompletions.
Usage:
# test_smoke.py
"""Test that the charm can be deployed and go to active status."""
import jubilant
def test_deploy(juju: jubilant.Juju):
juju.deploy("./foo.charm", "foo")
juju.wait(lambda status: jubilant.all_active(status, "foo"), timeout=1000)This test will spin up a temporary model named jubilant-<randomhex>-test-smoke. It will be torn down when the module-scoped juju fixture context exits.
This is a module-scoped fixture that you can use to manage multiple temporary Juju models. It's what the juju fixture is using behind the scenes. It's useful if you have test cases that require multiple models, for example testing cross-model relations.
Tip
Use pytest_jubilant.JujuFactory as the type annotation for the juju_factory fixture in your tests for better linting and IDE autocompletions.
Note that the exposed JujuFactory type is just a protocol, and can't be used to directly create a Juju factory. Whenever you need one, request the juju_factory fixture.
Usage:
# test_cmr.py
"""Test cross model relations."""
import jubilant
import pytest
import pytest_jubilant
@pytest.fixture(scope="module")
def istio(juju_factory: pytest_jubilant.JujuFactory):
yield juju_factory.get_juju(suffix="istio")
def test_offer_consume_relate(juju: jubilant.Juju, istio: jubilant.Juju):
istio.deploy("istio-k8s", "istio")
istio.wait(lambda status: all_active(status, "istio"), timeout=1000)
juju.deploy("./foo.charm", "foo")
juju.wait(lambda status: jubilant.all_active(status, "foo"), timeout=1000)
juju.cli("offer", "foo:bar")
istio.cli("consume", f"{juju.model}:foo")
istio.cli("relate", "istio", "foo:bar")This test will spin up two temporary models, one called jubilant-<randomhex>-test-cmr, and one called jubilant-<randomhex>-test-cmr-istio. They'll be torn down when the module context exits.
pytest tests/integration --juju-model hello will use hello instead of jubilant-<randomhex>. The module names combined with the suffixes you defined in the fixtures will give all generated models predictable names. The tests will reuse the existing models (if found) or create new ones with those names.
You can optionally pass controller and cloud to juju_factory.get_juju to deploy individual models on specific controllers or clouds. This is useful for testing cross-model relations between different deployment types, such as machine and Kubernetes models on separate controllers.
pytest-jubilant extends pytest with several commandline arguments that you can add directly to your pytest invocation.
Skip all tests marked with juju_setup and don't create any new models. This option is for re-running a test on an existing model which is already set up. Since setup can be very lengthy, it's often helpful to avoid re-running it when iterating on tests that assume the charm is up and running, for example when testing actions.
Warning
It's an error to pass --no-juju-setup without also specifying --juju-model.
Usage:
pytest tests/integration --no-juju-teardown
# Check the last line of output for the <model prefix>!
pytest tests/integration --no-juju-setup --juju-model <model prefix>Skip all tests marked with juju_teardown and skip destroying the models.
Useful to inspect the state of a model after a (failed) test run.
Warning
The --keep-models flag used by pytest-operator is unsupported as of pytest-jubilant 2.0!
Be sure to use --no-juju-teardown instead.
Usage:
pytest tests/integration --no-juju-teardownTip
The last line of output will tell you the --juju-model value to use if you want to rerun your tests using the same models. Be sure to pass --no-juju-setup as well to avoid failures when trying to perform setup steps that are already done.
By default, created Juju model names are prefixed with jubilant-<randomhex>, where <randomhex> is randomly generated each pytest run. Set --juju-model on the commandline to use a fixed prefix instead.
Warning
Note that models created with this prefix will be torn down at the end of the test run just like any other, so if you're targeting existing models you care about, don't forget the --no-juju-teardown flag!
Usage:
pytest tests/integration/test_foo.py --juju-model hello
# Runs the test on new 'hello-test-foo' model and tears it down afterwards.
pytest tests/integration/test_foo.py --juju-model hello --no-juju-teardown
# Runs the test on new 'hello-test-foo' model and keeps it.
pytest tests/integration/test_foo.py --juju-model hello --no-juju-setup --no-juju-teardown
# Runs the test on the existing 'hello-test-foo' model and keeps it.
# Note that we don't want to run the setup tests since they already ran.juju add-model hello-test-bar # A whole new model.
pytest tests/integration/test_bar.py --juju-model hello --no-juju-teardown
# Runs the test on the existing 'hello-test-bar' model and keeps it.
# Note that we want to run the setup tests to deploy the charm(s) etc.
# since this is a new model.Set the default Juju controller to use when creating new models. This is equivalent to passing --controller to juju add-model. It can be overridden by passing the controller argument to JujuFactory.get_juju. If neither is specified, Juju falls back to the currently active controller.
Usage:
pytest tests/integration --juju-controller my-controllerSet the default Juju cloud (or cloud/region) to use when creating new models. This is equivalent to passing the cloud argument to juju add-model. It can be overridden by passing the cloud argument to JujuFactory.get_juju. If neither is specified, Juju falls back to the currently active cloud.
Usage:
pytest tests/integration --juju-cloud localhost
pytest tests/integration --juju-cloud aws/us-east-1Switch to the model that is currently in scope, so you can keep an eye on the juju status as the tests progress. This won't be very helpful if you're running multiple test modules in parallel!
Only switches to models created by the juju fixture, not those created by juju_factory.
Usage:
pytest tests/integration -k test_something --juju-switch
# will switch you to the 'jubilant-<randomhex>-<module>' model as soon as it's created
pytest tests/integration -k test_something --juju-model hello --juju-switch
# will switch you to the 'hello-<module>' model as soon as it's createdWhen all the tests in a module have completed, but prior to tearing down the models owned by a juju_factory, dump the juju debug-log for each managed model into the specified directory.
- By default, logs aren't dumped, and
juju debug-logis only executed if tests failed, so that the last log lines can be sent to stderr. - If
--juju-dump-logsis passed, logs are dumped to<CWD>/.logs/. - If
--juju-dump-logs <target dir>is passed, logs are dumped to<target dir>/.
The file naming scheme is:
<module prefix>-<module name>[-<suffix>]-juju-debug.log
Usage:
pytest tests/integration/test_ingress.py --juju-dump-logs=debug_logs
# Once the tests are done, you'll find the logs in:
# ./debug_logs/jubilant-abcd1234-test-ingress-juju-debug.log
pytest tests/integration/test_ingress.py --juju-model foo --juju-dump-logs
# Once the tests are done, you'll find the logs in the default directory:
# ./.logs/foo-test-ingress-juju-debug.log
pytest integration/test_ingress.py
# No logs will be saved.Tip
Use --juju-dump-logs in combination with actions/upload-artifact to make your logs available in CI.
For example:
# In your integration test job
- run: tox -e integration -- --juju-dump-logs logs
- name: Upload logs
if: ${{ !cancelled() }}
uses: actions/upload-artifact@v4
with:
name: juju-dump-logs
path: logsNote that dumping to the default location .logs/ will require you to set include-hidden-files: true.
pytest-jubilant declares markers that you can apply to your tests with @pytest.mark.<marker>.
Marker for tests that prepare a model for use in later tests.
The --no-juju-setup option will skip any tests marked with juju_setup, in addition to not destroying the Juju models themselves.
Tip
To run only your juju_setup tests and leave the models set up for manual interaction, try:
pytest tests/integration -m juju_setup --no-juju-teardown
Usage:
import jubilant
import pytest
@pytest.mark.juju_setup
def test_deploy(juju: jubilant.Juju):
juju.deploy("A")
juju.deploy("B")
@pytest.mark.juju_setup
def test_relate(juju: jubilant.Juju):
juju.integrate("A", "B")Marker for tests that perform destructive actions on a model.
The --no-juju-teardown option will skip any tests marked with juju_teardown, in addition to not destroying the Juju models themselves.
Usage:
import jubilant
import pytest
@pytest.mark.juju_teardown
def test_disintegrate(juju: jubilant.Juju):
juju.remove_relation("A", "B")
@pytest.mark.juju_teardown
def test_destroy(juju: jubilant.Juju):
juju.remove_application("A")
juju.remove_application("B")pytest-jubilant is an open source project that warmly welcomes community contributions, suggestions, fixes and constructive feedback.
For support, join Charm Development on Matrix.
To follow along with updates and tips about charm development, join our Discourse forum.