refactor!: rename Container.exec_mocks to Container.execs and extend mocking

README.md

@@ -496,7 +496,7 @@ If you want to, you can override any of these relation or extra-binding associat
 
 ```python
 state = scenario.State(networks={
-  scenario.Network("foo", [BindAddress([Address('192.0.2.1')])])
+  scenario.Network("foo", [scenario.BindAddress([scenario.Address('192.0.2.1')])])
 })
 ```
 
@@ -639,17 +639,19 @@ class MyCharm(ops.CharmBase):
     def _on_start(self, _):
         foo = self.unit.get_container('foo')
         proc = foo.exec(['ls', '-ll'])
-        stdout, _ = proc.wait_output()
+        stdout, _ = proc.wait_output("...")
         assert stdout == LS_LL
 
 
 def test_pebble_exec():
     container = scenario.Container(
         name='foo',
-        exec_mock={
-            ('ls', '-ll'):  # this is the command we're mocking
-                scenario.ExecOutput(return_code=0,  # this data structure contains all we need to mock the call.
-                                    stdout=LS_LL)
+        execs={
+            scenario.Exec(
+                command_prefix=['ls', '-ll'],
+                return_code=0,
+                stdout=LS_LL,
+            ),
         }
     )
     state_in = scenario.State(containers={container})
@@ -661,8 +663,27 @@ def test_pebble_exec():
         ctx.on.pebble_ready(container),
         state_in,
     )
+    assert state_out.containers["foo"].get_exec(['ls', '-ll']).stdin == "..."
 ```
 
+Scenario will attempt to find the right `Exec` object by matching the provided
+command prefix against the command used in the ops `container.exec()` call. For
+example if the command is `['ls', '-ll']` then the searching will be:
+
+ 1. an `Exec` with exactly the same as command prefix, `('ls', '-ll')`
+ 2. an `Exec` with the command prefix `('ls', )`
+ 3. an `Exec` with the command prefix `()`
+
+If none of these are found Scenario will raise a `RuntimeError`.
+
+Note that the `return_code`, `stdout`, and `stderr` attributes of an `Exec`
+object are the *output* that the charm will receive when a matching `exec` call
+is made. You'll want to provide these when constructing the input state, and
+will rarely want to assert on them in the output state (they cannot change).
+The `stdin` attribute is ignored in the input state, and in the output
+state will contain any content that the charm wrote to stdin as part of the
+`exec` call, so you'll want to assert that it has the appropriate value.
+
 ### Pebble Notices
 
 Pebble can generate notices, which Juju will detect, and wake up the charm to
@@ -705,9 +726,9 @@ check doesn't have to match the event being generated: by the time that Juju
 sends a pebble-check-failed event the check might have started passing again.
 
 ```python
-ctx = scenario.Context(MyCharm, meta={"name": "foo", "containers": {"my-container": {}}})
+ctx = scenario.Context(MyCharm, meta={"name": "foo", "containers": {"my_container": {}}})
 check_info = scenario.CheckInfo("http-check", failures=7, status=ops.pebble.CheckStatus.DOWN)
-container = scenario.Container("my-container", check_infos={check_info})
+container = scenario.Container("my_container", check_infos={check_info})
 state = scenario.State(containers={container})
 ctx.run(ctx.on.pebble_check_failed(info=check_info, container=container), state=state)
 ```

scenario/__init__.py

@@ -13,7 +13,7 @@
     Container,
     DeferredEvent,
     ErrorStatus,
-    ExecOutput,
+    Exec,
     ICMPPort,
     MaintenanceStatus,
     Model,
@@ -49,7 +49,7 @@
     "SubordinateRelation",
     "PeerRelation",
     "Model",
-    "ExecOutput",
+    "Exec",
     "Mount",
     "Container",
     "Notice",

scenario/consistency_checker.py

@@ -4,7 +4,7 @@
 import marshal
 import os
 import re
-from collections import defaultdict
+from collections import Counter, defaultdict
 from collections.abc import Sequence
 from numbers import Number
 from typing import TYPE_CHECKING, Iterable, List, NamedTuple, Tuple, Union
@@ -186,27 +186,33 @@ def _check_workload_event(
     event: "_Event",
     state: "State",
     errors: List[str],
-    warnings: List[str],  # noqa: U100
+    warnings: List[str],
 ):
     if not event.container:
         errors.append(
             "cannot construct a workload event without the container instance. "
             "Please pass one.",
         )
-    elif not event.name.startswith(normalize_name(event.container.name)):
-        errors.append(
-            f"workload event should start with container name. {event.name} does "
-            f"not start with {event.container.name}.",
-        )
-        if event.container not in state.containers:
+    else:
+        if not event.name.startswith(normalize_name(event.container.name)):
             errors.append(
-                f"cannot emit {event.name} because container {event.container.name} "
-                f"is not in the state.",
+                f"workload event should start with container name. {event.name} does "
+                f"not start with {event.container.name}.",
             )
-        if not event.container.can_connect:
-            warnings.append(
-                "you **can** fire fire pebble-ready while the container cannot connect, "
-                "but that's most likely not what you want.",
+            if event.container not in state.containers:
+                errors.append(
+                    f"cannot emit {event.name} because container {event.container.name} "
+                    f"is not in the state.",
+                )
+            if not event.container.can_connect:
+                warnings.append(
+                    "you **can** fire fire pebble-ready while the container cannot connect, "
+                    "but that's most likely not what you want.",
+                )
+        names = Counter(exec.command_prefix for exec in event.container.execs)
+        if dupes := [n for n in names if names[n] > 1]:
+            errors.append(
+                f"container {event.container.name} has duplicate command prefixes: {dupes}",
             )
 
 
@@ -593,7 +599,7 @@ def check_containers_consistency(
         ):
             errors.append(
                 f"the event being processed concerns check {event.check_info.name}, but that "
-                "check is not the {evt_container_name} container.",
+                f"check is not the {evt_container_name} container.",
             )
 
     # - a container in state.containers is not in meta.containers

scenario/mocking.py

@@ -53,7 +53,7 @@
     from scenario.context import Context
     from scenario.state import Container as ContainerSpec
     from scenario.state import (
-        ExecOutput,
+        Exec,
         Relation,
         Secret,
         State,
@@ -73,26 +73,40 @@ class ActionMissingFromContextError(Exception):
 
 
 class _MockExecProcess:
-    def __init__(self, command: Tuple[str, ...], change_id: int, out: "ExecOutput"):
+    def __init__(
+        self,
+        command: Tuple[str, ...],
+        change_id: int,
+        exec: "Exec",
+    ):
         self._command = command
         self._change_id = change_id
-        self._out = out
+        self._exec = exec
         self._waited = False
-        self.stdout = StringIO(self._out.stdout)
-        self.stderr = StringIO(self._out.stderr)
+        self.stdout = StringIO(self._exec.stdout)
+        self.stderr = StringIO(self._exec.stderr)
+        # You can't pass *in* the stdin, the charm is responsible for that.
+        self.stdin = StringIO()
 
     def wait(self):
         self._waited = True
-        exit_code = self._out.return_code
+        self._exec._update_stdin(self.stdin.getvalue())
+        exit_code = self._exec.return_code
         if exit_code != 0:
             raise ExecError(list(self._command), exit_code, None, None)
 
     def wait_output(self):
-        out = self._out
-        exit_code = out.return_code
+        exec = self._exec
+        self._exec._update_stdin(self.stdin.getvalue())
+        exit_code = exec.return_code
         if exit_code != 0:
-            raise ExecError(list(self._command), exit_code, None, None)
-        return out.stdout, out.stderr
+            raise ExecError(
+                list(self._command),
+                exit_code,
+                self.stdout.read(),
+                self.stderr.read(),
+            )
+        return exec.stdout, exec.stderr
 
     def send_signal(self, sig: Union[int, str]):  # noqa: U100
         raise NotImplementedError()
@@ -727,21 +741,39 @@ def _layers(self) -> Dict[str, pebble.Layer]:
 
     @property
     def _service_status(self) -> Dict[str, pebble.ServiceStatus]:
-        return self._container.service_status
+        return self._container.service_statuses
+
+    # Based on a method of the same name from ops.testing.
+    def _find_exec_handler(self, command) -> Optional["Exec"]:
+        handlers = {exec.command_prefix: exec for exec in self._container.execs}
+        # Start with the full command and, each loop iteration, drop the last
+        # element, until it matches one of the command prefixes in the execs.
+        # This includes matching against the empty list, which will match any
+        # command, if there is not a more specific match.
+        for prefix_len in reversed(range(len(command) + 1)):
+            command_prefix = tuple(command[:prefix_len])
+            if command_prefix in handlers:
+                return handlers[command_prefix]
+        # None of the command prefixes in the execs matched the command, no
+        # matter how much of it was used, so we have failed to find a handler.
+        return None
 
-    def exec(self, *args, **kwargs):  # noqa: U100 type: ignore
-        cmd = tuple(args[0])
-        out = self._container.exec_mock.get(cmd)
-        if not out:
+    def exec(self, command, **kwargs):  # noqa: U100 type: ignore
+        handler = self._find_exec_handler(command)
+        if not handler:
             raise RuntimeError(
-                f"mock for cmd {cmd} not found. Please pass to the Container "
-                f"{self._container.name} a scenario.ExecOutput mock for the "
+                f"mock for cmd {command} not found. Please pass to the Container "
+                f"{self._container.name} a scenario.Exec mock for the "
                 f"command your charm is attempting to run, or patch "
                 f"out whatever leads to the call.",
             )
 
-        change_id = out._run()
-        return _MockExecProcess(change_id=change_id, command=cmd, out=out)
+        change_id = handler._run()
+        return _MockExecProcess(
+            change_id=change_id,
+            command=command,
+            exec=handler,
+        )
 
     def _check_connection(self):
         if not self._container.can_connect:

scenario/state.py

@@ -23,6 +23,7 @@
     List,
     Literal,
     Optional,
+    Sequence,
     Set,
     Tuple,
     Type,
@@ -643,24 +644,35 @@ def _generate_new_change_id():
 
 
 @dataclasses.dataclass(frozen=True)
-class ExecOutput(_max_posargs(0)):
+class Exec(_max_posargs(1)):
     """Mock data for simulated :meth:`ops.Container.exec` calls."""
 
+    command_prefix: Sequence[str]
     return_code: int = 0
     """The return code of the process (0 is success)."""
     stdout: str = ""
     """Any content written to stdout by the process."""
     stderr: str = ""
     """Any content written to stderr by the process."""
+    stdin: Optional[str] = None
+    """Any content written to stdin by the charm."""
 
     # change ID: used internally to keep track of mocked processes
     _change_id: int = dataclasses.field(default_factory=_generate_new_change_id)
 
+    def __post_init__(self):
+        # The command prefix can be any sequence type, and a list is tidier to
+        # write when there's only one string. However, this object needs to be
+        # hashable, so can't contain a list. We 'freeze' the sequence to a tuple
+        # to support that.
+        object.__setattr__(self, "command_prefix", tuple(self.command_prefix))
+
     def _run(self) -> int:
         return self._change_id
 
-
-_ExecMock = Dict[Tuple[str, ...], ExecOutput]
+    def _update_stdin(self, stdin: str):
+        # bypass frozen dataclass
+        object.__setattr__(self, "stdin", stdin)
 
 
 @dataclasses.dataclass(frozen=True)
@@ -803,7 +815,7 @@ class Container(_max_posargs(1)):
     layers: Dict[str, pebble.Layer] = dataclasses.field(default_factory=dict)
     """All :class:`ops.pebble.Layer` definitions that have already been added to the container."""
 
-    service_status: Dict[str, pebble.ServiceStatus] = dataclasses.field(
+    service_statuses: Dict[str, pebble.ServiceStatus] = dataclasses.field(
         default_factory=dict,
     )
     """The current status of each Pebble service running in the container."""
@@ -828,20 +840,23 @@ class Container(_max_posargs(1)):
         }
     """
 
-    exec_mock: _ExecMock = dataclasses.field(default_factory=dict)
+    execs: Iterable[Exec] = frozenset()
     """Simulate executing commands in the container.
 
-    Specify each command the charm might run in the container and a :class:`ExecOutput`
+    Specify each command the charm might run in the container and an :class:`Exec`
     containing its return code and any stdout/stderr.
 
     For example::
 
         container = scenario.Container(
             name='foo',
-            exec_mock={
-                ('whoami', ): scenario.ExecOutput(return_code=0, stdout='ubuntu')
-                ('dig', '+short', 'canonical.com'):
-                    scenario.ExecOutput(return_code=0, stdout='185.125.190.20\\n185.125.190.21')
+            execs={
+                scenario.Exec(['whoami'], return_code=0, stdout='ubuntu'),
+                scenario.Exec(
+                    ['dig', '+short', 'canonical.com'],
+                    return_code=0,
+                    stdout='185.125.190.20\\n185.125.190.21',
+                ),
             }
         )
     """
@@ -853,6 +868,11 @@ class Container(_max_posargs(1)):
     def __hash__(self) -> int:
         return hash(self.name)
 
+    def __post_init__(self):
+        if not isinstance(self.execs, frozenset):
+            # Allow passing a regular set (or other iterable) of Execs.
+            object.__setattr__(self, "execs", frozenset(self.execs))
+
     def _render_services(self):
         # copied over from ops.testing._TestingPebbleClient._render_services()
         services = {}  # type: Dict[str, pebble.Service]
@@ -893,7 +913,7 @@ def services(self) -> Dict[str, pebble.ServiceInfo]:
                 # in pebble, it just returns "nothing matched" if there are 0 matches,
                 # but it ignores services it doesn't recognize
                 continue
-            status = self.service_status.get(name, pebble.ServiceStatus.INACTIVE)
+            status = self.service_statuses.get(name, pebble.ServiceStatus.INACTIVE)
             if service.startup == "":
                 startup = pebble.ServiceStartup.DISABLED
             else:
@@ -915,6 +935,13 @@ def get_filesystem(self, ctx: "Context") -> Path:
         """
         return ctx._get_container_root(self.name)
 
+    def get_exec(self, command_prefix: Sequence[str]):
+        """Get the Exec object from the container with the given command prefix."""
+        for exec in self.execs:
+            if exec.command_prefix == command_prefix:
+                return exec
+        raise KeyError(f"no exec found with command prefix {command_prefix}")
+
 
 _RawStatusLiteral = Literal[
     "waiting",