docs: update tutorials and how-tos to use pytest-jubilant#2406
docs: update tutorials and how-tos to use pytest-jubilant#2406james-garner-canonical wants to merge 9 commits intocanonical:mainfrom
Conversation
| You can use Jubilant with several models, in the same cloud or in | ||
| different clouds. This way you can, for example, integrate machine charms | ||
| with Kubernetes charms easily. | ||
| If you need multiple Juju models in a single test module, use the `juju_factory` fixture provided by `pytest-jubilant`: | ||
|
|
||
| ```python | ||
| model_a = jubilant.Juju("some-model") | ||
| model_b = jubilant.Juju("another-controller:a-model") | ||
| new_model = jubilant.Juju().add_model("a-model", "some-cloud", controller=..., config=..., credential=...) |
There was a problem hiding this comment.
I'm not entirely sure what to do here.
The workflow described here originally suggests that pytest-jubilant might benefit from the following:
JujuFactory.get_jujumight benefit from the addition of keyword arguments that are forward toJuju.add_model, likecloud,controller,config,crediential.- Maybe we'd also want a CLI option like
--juju-cloudto set the default cloud operated in explicitly, and perhaps--juju-controlleras well
Or should we document a simpler workflow for now and see if we get a feature request to support models in different clouds in pytest-jubilant (current approach)?
I'm thinking this might be enough of an oversight on our part to warrant adding the feature preemptively.
| | Option | Description | | ||
| |---|---| | ||
| | `--juju-model PREFIX` | Use a custom model name prefix instead of a random one. Required if using `--no-juju-setup`. Model names are formed as `PREFIX-MODULE` (or `PREFIX-MODULE-SUFFIX` for extra models created via `juju_factory`), where `MODULE` is derived from the test file name. For example, running `tests/integration/test_charm.py` with `--juju-model mytest` creates a model called `mytest-test-charm`. | | ||
| | `--no-juju-teardown` | Keep models after the tests finish, instead of destroying them. Also skips tests marked with `@pytest.mark.juju_teardown`. | | ||
| | `--no-juju-setup` | Skip tests marked with `@pytest.mark.juju_setup` (for example, deployment tests). The model must already exist. Requires `--juju-model`. | | ||
| | `--juju-switch` | Switch to the active test model, so you can monitor it with `juju status` in another terminal. | | ||
| | `--juju-dump-logs [PATH]` | Dump `juju debug-log` output to disk for each model. Defaults to `.logs/`. | |
There was a problem hiding this comment.
This is like a little slice of reference docs embedded in the relevant part of the how-to (running your tests -- here are the CLI options you can use). I wonder if we should just link out to pytest-jubilant directly here. It feels a little odd since it doesn't have a proper docs site, just the repository readme.
There was a problem hiding this comment.
Per discussion with @dwilding, we'll drop this table and link out.
| If any tests fail, `pytest-jubilant` automatically prints the last 1000 lines of `juju debug-log` to stderr, even without `--juju-dump-logs`. | ||
|
|
||
| ````{tip} | ||
| Use `--juju-dump-logs` in CI with `actions/upload-artifact` to make debug logs available as build artifacts: | ||
|
|
||
| ```yaml | ||
| # In your integration test job | ||
| - run: tox -e integration -- --juju-dump-logs | ||
| - name: Upload logs | ||
| if: ${{ !cancelled() }} | ||
| uses: actions/upload-artifact@v4 | ||
| with: | ||
| name: juju-dump-logs | ||
| path: .logs | ||
| ``` | ||
| ```` | ||
|
|
There was a problem hiding this comment.
Highlighting this section for reference in #2405.
1 participant
Following the release of
pytest-jubilant2.0 and its official adoption by Charm Tech, this PR updates our docs to recommend its use. This includes updating the tutorials and example charms to use thejujufixture it provides instead of rolling our own, updating the relevant how-to guides in the same way, and expanding the integration testing how-to guide to coverpytest-jubilantfeatures and the recommended local integration testing workflow.Preview build: