feat: optionally install Scenario with ops[testing] and expose the …

…names in ops.testing (canonical#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 <benhoyt@gmail.com>
Co-authored-by: Dima Tisnek <dimaqq@gmail.com>

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 <https://juju.is/docs/sdk>`_
 
-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 </state-transition-testing>`. This is the
+    recommended approach (it was previously known as 'Scenario').
+  - :doc:`Harness </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: