From 46ffe4302630e4cf22a6c3857bcfab51380050c7 Mon Sep 17 00:00:00 2001 From: Tony Meyer Date: Wed, 25 Sep 2024 20:08:13 +1200 Subject: [PATCH] feat: optionally install Scenario with `ops[testing]` and expose the names in ops.testing (#1381) Add a new optional install `testing`, e.g. `pip install ops[testing]`. This pulls in a compatible version of `ops-scenario`, and exposes the Scenario names in the `ops.testing` namespace, alongside Harness. `pip install ops[harness]` is also supported to ease the (far off, presumably 3.0) transition to Harness being moved out of the base install. It currently installs no extra dependencies, so is the same as `pip install ops` but a forward-looking charm would use `pip install ops[harness]` (or `pip install ops[harness, testing]`) if using Harness. Requires ops-scenario 7.0.5, which has the required adjustments to support insertion into `ops.testing`. The `ActionFailed` name exists in both `ops._private.harness` and `scenario.context`. This is handled by adjusting the Harness class to support the functionality of both and monkeypatching that into Scenario until Scenario starts using it. It's compatible with both Harness and Scenario, but will have empty data in an attribute (which attribute depends on which framework is used). The `Container` name in `ops.testing`, which is only present for backwards compatibility, is also overwritten if ops-scenario is installed. If anyone is actually using `ops.testing.Container` instead of `ops.Container` then they'll need to fix their code before using `ops[testing]` (or ops-scenario combined with the release of ops with this change). A very basic unit test is added to make sure that Scenario tests work (all the actual Scenario tests are in the ops-scenario repo) if ops-scenario/ops[testing] is installed (this is the case for `tox -e unit`). A test is also added to ensure that all of the Scenario names are documented, since `automodule` isn't used any more. Also adjusts the documentation to include the new framework in ops.testing. --------- Co-authored-by: Ben Hoyt Co-authored-by: Dima Tisnek --- docs/index.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 2860bdf61..687c0c258 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -29,19 +29,25 @@ The `ops` library is a Python framework for writing and testing Juju charms. See more: `Charm SDK documentation `_ -The library provides: +The library (`available on PyPI`_) provides: -- :ref:`ops_main_entry_point`, used to initialise and run your charm; - :ref:`ops_module`, the API to respond to Juju events and manage the application; +- :ref:`ops_main_entry_point`, used to initialise and run your charm; - :ref:`ops_pebble_module`, the Pebble client, a low-level API for Kubernetes containers; -- :ref:`ops_testing_module`, the framework for unit testing charms in a simulated environment; +- the APIs for unit testing charms in a simulated environment: + + - :doc:`State-transition testing `. This is the + recommended approach (it was previously known as 'Scenario'). + - :doc:`Harness `. This is a deprecated framework, and has issues, + particularly with resetting the charm state between Juju events. You can structure your charm however you like, but with the `ops` library, you get a framework that promotes consistency and readability by following best practices. It also helps you organise your code better by separating different -aspects of the charm, such as managing the application’s state, handling +aspects of the charm, such as managing the application's state, handling integrations with other services, and making the charm easier to test. +.. _available on PyPI: https://pypi.org/project/ops/ .. toctree:: :hidden: