feat: optionally install Scenario with ops[testing] and expose the names in ops.testing

docs/harness.rst

@@ -1,9 +1,7 @@
-:orphan:
-
 .. _harness:
 
-Harness Unit Test Framework
-===========================
+Harness (legacy unit testing)
+=============================
 
 .. deprecated:: 2.17
     The Harness framework is deprecated and will be moved out of the base
@@ -23,6 +21,11 @@ The Harness framework includes:
   - :attr:`~ops.testing.Harness.model` attribute, which exposes e.g. the
     :attr:`~ops.Model.unit` attribute for detailed assertions on the unit's state.
 
+.. note::
+    Unit testing is only one aspect of a comprehensive testing strategy. For more
+    on testing charms, see `Charm SDK | Testing <https://juju.is/docs/sdk/testing>`_.
+
+
 .. autoclass:: ops.testing.ActionFailed
    :noindex:
 .. autoclass:: ops.testing.ActionOutput

docs/index.rst

@@ -7,10 +7,18 @@ The `ops` library is a Python framework for writing and testing Juju charms.
 
 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` frameworks 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.
+  - :doc:`Harness </harness>`. This is a deprecated framework, and has issues,
+    particularly with resetting the charm state between Juju events. It will be
+    moved out of the base ``ops`` install in an ops release in the future. Charm
+    authors that don't want to upgrade will still be able to use it with
+    ``pip install ops[harness]``.
 
 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
@@ -60,25 +68,6 @@ ops.pebble
 
 .. _ops_testing_module:
 
-Testing
--------
-
-Two frameworks for unit testing charms in a simulated Juju environment are
-available:
-
-* :doc:`State-transition testing </state-transition-testing>`, which tests the charm's state transitions in response
-  to events. This is the recommended approach. Install ops with the ``testing``
-  extra to use this framework; for example: ``pip install ops[testing]``
-* :doc:`Harness </harness>`, which provides an API reminiscent of the Juju CLI. This is a
-  deprecated framework, and has issues, particularly with resetting the charm
-  state between Juju events. It will be moved out of the base ``ops`` install in
-  a future release.
-
-
-.. note::
-    Unit testing is only one aspect of a comprehensive testing strategy. For more
-    on testing charms, see `Charm SDK | Testing <https://juju.is/docs/sdk/testing>`_.
-
 
 Indices
 =======

docs/state-transition-testing.rst

@@ -1,22 +1,23 @@
-:orphan:
-
 .. _state-transition-tests:
 
-Unit Test Framework
-===================
+Unit testing (was: Scenario)
+============================
+
+Install ops with the ``testing`` extra to use this API; for example:
+``pip install ops[testing]``
 
-State-transition tests expect you to define the Juju state all at once, define
-the Juju context against which to test the charm, and fire a single event on the
-charm to execute its logic. The tests can then assert that the Juju state has
-changed as expected.
+State-transition tests, previously known as 'Scenario', expect you to define the
+Juju state all at once, define the Juju context against which to test the charm,
+and fire a single event on the charm to execute its logic. The tests can then
+assert that the Juju state has changed as expected.
 
 A very simple test, where the charm has no config, no integrations, the unit
 is the leader, and has a `start` handler that sets the status to active might
 look like this:
 
 .. code-block:: python
 
-   from ops import testing
+    from ops import testing
 
     def test_base():
         ctx = testing.Context(MyCharm)
@@ -63,6 +64,11 @@ A test consists of three broad steps:
     - verify that the output state is what you expect it to be
     - verify that the charm has seen a certain sequence of statuses, events, and `juju-log` calls
 
+.. note::
+    Unit testing is only one aspect of a comprehensive testing strategy. For more
+    on testing charms, see `Charm SDK | Testing <https://juju.is/docs/sdk/testing>`_.
+
+
 ..
    _The list here is manually maintained, because the `automodule` directive
    expects to document names defined in the module, and not imported ones, and

ops/__init__.py

@@ -14,7 +14,7 @@
 
 """The API to respond to Juju events and manage the application.
 
-This module provides code features to your charm, including:
+This module provides core features to your charm, including:
 
 - :class:`~ops.CharmBase`, the base class for charms and :class:`~ops.Object`,
   the base class for charm libraries.

ops/_private/harness.py

@@ -199,7 +199,7 @@ def __init__(
         state: typing.Optional['State'] = None,
     ):
         self.message = message
-        self.output = ActionOutput([], {}) if output is None else output
+        self.output = output or ActionOutput([], {})
         self.state = state
 
     def __str__(self):
@@ -314,6 +314,13 @@ def __init__(
             juju_debug_at=self._juju_context.debug_at,
         )
 
+        warnings.warn(
+            'Harness is deprecated; we recommend using state transition testing '
+            "(previously known as 'Scenario') instead",
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
+
     def _event_context(self, event_name: str):
         """Configures the Harness to behave as if an event hook were running.
 

pyproject.toml

@@ -41,6 +41,9 @@ docs = [
 testing = [
     "ops-scenario>=7.0.5,<8",
 ]
+# Empty for now, because Harness is bundled with the base install, but allow
+# specifying the extra to ease transition later.
+harness = []
 
 [project.urls]
 "Homepage" = "https://juju.is/docs/sdk"