dirigent-testing 0.9.0__tar.gz

dirigent_testing-0.9.0/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2026 Morten Olav Hansen <morten@winterop.com>. All rights reserved.
+
+This source code and accompanying documentation are the property of
+Morten Olav Hansen. No license, express or implied, is granted to use, copy,
+modify, merge, publish, distribute, sublicense, or sell copies of this
+software or its derivatives.
+
+The source is published for reference only. Any use beyond reading
+requires written permission from the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES,
+OR OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.
+
+Third-party components redistributed with this software, and the licences they
+carry, are listed in THIRD_PARTY_NOTICES.md.

dirigent_testing-0.9.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: dirigent-testing
+Version: 0.9.0
+Summary: Test doubles and pytest fixtures for writing and testing dirigent blocks.
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+Requires-Dist: dirigent-common
+Requires-Dist: dirigent-plugin
+Requires-Dist: httpx2>=2.12.0
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: pytest>=9.1.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# dirigent-testing
+
+Test doubles and pytest fixtures for writing and testing dirigent blocks.
+
+Installing it registers the fixtures by entry point, so a block author writes no conftest.
+`block_ctx` is a step context with a recording log and real storage behind it, and
+`call_block` validates a config the way the engine does before making the block's first call.
+
+`check_pack_examples` checks a pack's own example documents against its own `Contribution`
+-- format, code, blocks, config schemas, and carried connections -- without importing
+dirigent-core, and `assert_contribution_conforms` checks the blocks a contribution provides
+are well-formed. Both return a list of human-readable issues; an empty list means it passed.

dirigent_testing-0.9.0/README.md

@@ -0,0 +1,12 @@
+# dirigent-testing
+
+Test doubles and pytest fixtures for writing and testing dirigent blocks.
+
+Installing it registers the fixtures by entry point, so a block author writes no conftest.
+`block_ctx` is a step context with a recording log and real storage behind it, and
+`call_block` validates a config the way the engine does before making the block's first call.
+
+`check_pack_examples` checks a pack's own example documents against its own `Contribution`
+-- format, code, blocks, config schemas, and carried connections -- without importing
+dirigent-core, and `assert_contribution_conforms` checks the blocks a contribution provides
+are well-formed. Both return a list of human-readable issues; an empty list means it passed.

dirigent_testing-0.9.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "dirigent-testing"
+version = "0.9.0"
+description = "Test doubles and pytest fixtures for writing and testing dirigent blocks."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+dependencies = [
+    "dirigent-common",
+    "dirigent-plugin",
+    "httpx2>=2.12.0",
+    "pydantic>=2.13.5",
+    "pytest>=9.1.1",
+    "pyyaml>=6.0.3",
+]
+
+[project.entry-points.pytest11]
+dirigent_testing = "dirigent_testing.fixtures"
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources.dirigent-common]
+workspace = true
+
+[tool.uv.sources.dirigent-plugin]
+workspace = true

dirigent_testing-0.9.0/pyproject.toml.orig

@@ -0,0 +1,27 @@
+[project]
+name = "dirigent-testing"
+version = "0.9.0"
+description = "Test doubles and pytest fixtures for writing and testing dirigent blocks."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+dependencies = [
+    "dirigent-common",
+    "dirigent-plugin",
+    "httpx2>=2.12.0",
+    "pydantic>=2.13.5",
+    "pytest>=9.1.1",
+    "pyyaml>=6.0.3",
+]
+
+[project.entry-points.pytest11]
+dirigent_testing = "dirigent_testing.fixtures"
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+dirigent-common = { workspace = true }
+dirigent-plugin = { workspace = true }

dirigent_testing-0.9.0/src/dirigent_testing/__init__.py

@@ -0,0 +1,21 @@
+"""Test doubles and pytest fixtures for writing and testing dirigent blocks."""
+
+from dirigent_testing.conformance import assert_contribution_conforms, check_pack_examples
+from dirigent_testing.doubles import FakeContext, FakeRuns, FakeSink, FakeStorage, RecordingLogger
+from dirigent_testing.environment import CONFIGURING_PREFIXES, TEST_WIDTH, pin_terminal, scrub_configuration
+from dirigent_testing.running import call_block
+
+__all__ = [
+    "CONFIGURING_PREFIXES",
+    "TEST_WIDTH",
+    "FakeContext",
+    "FakeRuns",
+    "FakeSink",
+    "FakeStorage",
+    "RecordingLogger",
+    "assert_contribution_conforms",
+    "call_block",
+    "check_pack_examples",
+    "pin_terminal",
+    "scrub_configuration",
+]

dirigent_testing-0.9.0/src/dirigent_testing/conformance.py

@@ -0,0 +1,195 @@
+"""Checking a pack's own examples against its own contribution, without the engine.
+
+An out-of-repo pack cannot import dirigent-core to reuse ``validate_against_catalog``: the
+plugin contract stops at dirigent-plugin, and a pack must not reach past it. So the pack-side
+conformance check re-derives the structural half here, over the pack's own ``Contribution``
+and its own example documents. It is deliberately lighter than the engine's preflight: it
+proves an example is a well-formed ``dirigent/v1`` pipeline coded after its file, that every
+block it names is one the pack contributes, that each config fits that block's published
+schema, and that a named connection is carried by the document. It does not resolve
+references, run blocks, or reach for an instance.
+"""
+
+import re
+from pathlib import Path
+from typing import Any, Final, cast
+
+import yaml
+from jsonschema import Draft202012Validator
+from jsonschema import ValidationError as SchemaValidationError
+from jsonschema.validators import extend as extend_validator  # pyright: ignore[reportUnknownVariableType]
+from pydantic import JsonValue
+
+from dirigent_common import BlockModel, HumaneJsonSchema, JsonMap
+from dirigent_plugin import AnyOperator, AnySensor, Contribution
+
+#: A ``${...}`` reference, matched the way the engine matches one.
+_REFERENCE: Final = re.compile(r"\$\{[^{}]+\}")
+
+
+class _Deferred:
+    """A config value that is only a ``${...}`` reference, opaque until a run resolves it."""
+
+    def __repr__(self) -> str:
+        """Render the sentinel for an error message."""
+        return "${...}"
+
+
+_DEFERRED: Final = _Deferred()
+
+
+def _skip_deferred(keyword: Any) -> Any:
+    """Wrap one jsonschema keyword so it passes over a value that is only known at run time."""
+
+    def validate(validator: Any, value: Any, instance: Any, schema: Any) -> Any:
+        if instance is _DEFERRED:
+            return
+        yield from keyword(validator, value, instance, schema)
+
+    return validate
+
+
+#: A validator that checks everything an example states literally and defers a reference.
+_ConfigValidator: Any = extend_validator(  # pyright: ignore[reportUnknownVariableType]
+    Draft202012Validator,
+    {name: _skip_deferred(keyword) for name, keyword in Draft202012Validator.VALIDATORS.items()},
+)
+
+
+def _defer_references(value: JsonValue) -> object:
+    """Replace every value that is a ``${...}`` reference with the deferred sentinel."""
+    match value:
+        case str():
+            return _DEFERRED if _REFERENCE.search(value) else value
+        case list():
+            return [_defer_references(item) for item in value]
+        case dict():
+            return {key: _defer_references(item) for key, item in value.items()}
+        case _:
+            return value
+
+
+def check_pack_examples(contribution: Contribution, examples_dir: Path) -> list[str]:
+    """List everything wrong with a pack's example documents, checked against its own catalog.
+
+    Reads every ``*.yaml`` under ``examples_dir`` (recursively) and, for each, checks that it
+    is a ``dirigent/v1`` pipeline coded after its file with a description, that every block a
+    step names is one ``contribution`` provides, that each step's config fits that block's
+    published ``config_schema`` (a ``${...}`` value is left for the run), and that a connection
+    a step names is carried by the document's own ``connections`` block. Every issue is a
+    human-readable line prefixed with the file it was found in; an empty list means the
+    examples conform.
+    """
+    blocks = _blocks_by_id(contribution)
+    issues: list[str] = []
+    for path in sorted(examples_dir.rglob("*.yaml")):
+        issues.extend(_check_document(path, path.relative_to(examples_dir), blocks))
+    return issues
+
+
+def _every_block(contribution: Contribution) -> list[AnyOperator | AnySensor]:
+    """List every operator and then every sensor a contribution provides."""
+    blocks: list[AnyOperator | AnySensor] = [*contribution.operators, *contribution.sensors]
+    return blocks
+
+
+def _blocks_by_id(contribution: Contribution) -> dict[str, AnyOperator | AnySensor]:
+    """Index every operator and sensor a contribution provides by its block id."""
+    return {block.spec.id: block for block in _every_block(contribution)}
+
+
+def _check_document(path: Path, label: Path, blocks: dict[str, AnyOperator | AnySensor]) -> list[str]:
+    """Check one example document, prefixing every issue with the file it was found in."""
+    try:
+        loaded: object = yaml.safe_load(path.read_text())
+    except yaml.YAMLError as error:
+        return [f"{label}: is not valid YAML ({error})"]
+    if not isinstance(loaded, dict):
+        return [f"{label}: is not a mapping"]
+    document = cast("JsonMap", loaded)
+
+    issues: list[str] = []
+    if document.get("format") != "dirigent/v1":
+        issues.append(f"{label}: format is {document.get('format')!r}, not 'dirigent/v1'")
+    if document.get("kind") != "pipeline":
+        issues.append(f"{label}: kind is {document.get('kind')!r}, not 'pipeline'")
+    if document.get("code") != path.stem:
+        issues.append(f"{label}: code is {document.get('code')!r}, but the file is named {path.stem!r}")
+    if not document.get("description"):
+        issues.append(f"{label}: has no description")
+
+    connections = document.get("connections")
+    known = set(cast("JsonMap", connections)) if isinstance(connections, dict) else set[str]()
+    steps = document.get("steps")
+    if isinstance(steps, dict):
+        for name, step in cast("JsonMap", steps).items():
+            issues.extend(_check_step(label, str(name), step, blocks, known))
+    return issues
+
+
+def _check_step(
+    label: Path,
+    name: str,
+    step: Any,
+    blocks: dict[str, AnyOperator | AnySensor],
+    connections: set[str],
+) -> list[str]:
+    """Check one step: the block it names, the config it carries, the connection it references."""
+    if not isinstance(step, dict):
+        return [f"{label}: step {name!r} is not a mapping"]
+    step_map = cast("JsonMap", step)
+    issues: list[str] = []
+    block_id = step_map.get("block")
+    raw_config = step_map.get("config")
+    config = cast("JsonMap", raw_config) if isinstance(raw_config, dict) else cast("JsonMap", {})
+
+    block = blocks.get(block_id) if isinstance(block_id, str) else None
+    if block is None:
+        issues.append(f"{label}: step {name!r} names block {block_id!r}, which this pack does not contribute")
+    else:
+        schema = block.config_model.model_json_schema(schema_generator=HumaneJsonSchema)
+        issues.extend(_config_issues(label, name, config, schema))
+
+    named = config.get("connection")
+    if isinstance(named, str) and not _REFERENCE.search(named) and named not in connections:
+        issues.append(f"{label}: step {name!r} names connection {named!r}, which the document does not carry")
+    return issues
+
+
+def _config_issues(label: Path, name: str, config: JsonMap, schema: JsonMap) -> list[str]:
+    """List the ways a step's config violates its block's schema, deferring every reference."""
+    deferred = _defer_references(config)
+    raised: Any = _ConfigValidator(schema).iter_errors(deferred)  # pyright: ignore[reportUnknownMemberType]
+    found = cast("list[SchemaValidationError]", list(raised))
+    issues: list[str] = []
+    for error in sorted(found, key=lambda item: [str(part) for part in item.absolute_path]):
+        location = ".".join(str(part) for part in error.absolute_path)
+        where = f"config.{location}" if location else "config"
+        issues.append(f"{label}: step {name!r} {where}: {error.message}")
+    return issues
+
+
+def assert_contribution_conforms(contribution: Contribution) -> list[str]:
+    """List the ways a contribution's blocks are malformed, beyond what constructing it enforces.
+
+    A ``Contribution`` already rejects colliding ids when it is built, and a block id is a
+    pattern that forbids an empty one, so a valid contribution passes those. This adds the
+    check the contract cannot make on its own: that every operator's and sensor's
+    ``config_model`` and ``output_model`` is a :class:`BlockModel`. An empty list means the
+    contribution's blocks are well-formed.
+    """
+    issues: list[str] = []
+    seen: set[str] = set()
+    for block in _every_block(contribution):
+        label = type(block).__name__
+        block_id = block.spec.id
+        if not block_id:
+            issues.append(f"{label} has an empty spec.id")
+        elif block_id in seen:
+            issues.append(f"duplicate block id {block_id!r}")
+        seen.add(block_id)
+        for role in ("config_model", "output_model"):
+            model = getattr(block, role)
+            if not (isinstance(model, type) and issubclass(model, BlockModel)):
+                issues.append(f"{block_id or label} {role} is not a BlockModel")
+    return issues

dirigent_testing-0.9.0/src/dirigent_testing/doubles.py

@@ -0,0 +1,273 @@
+"""The engine's side of a block call, faked: a step context, storage, logs, and runs."""
+
+import tempfile
+from collections.abc import AsyncGenerator, AsyncIterator, Callable, Mapping
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, cast
+from uuid import UUID, uuid4
+
+import httpx2
+from jsonschema import FormatChecker
+from pydantic import BaseModel, JsonValue
+
+from dirigent_common import format_checker_with
+from dirigent_plugin import (
+    ByteSink,
+    FormatCheck,
+    RunRefused,
+    RunSnapshot,
+    RunState,
+    StartedRun,
+    StatResult,
+    StepContext,
+)
+
+
+class RecordingLogger:
+    """Keeps every entry a block wrote, so tests can assert on what it reported."""
+
+    def __init__(self) -> None:
+        """Start with an empty log."""
+        self.entries: list[tuple[str, str, dict[str, JsonValue]]] = []
+
+    def debug(self, message: str, **fields: JsonValue) -> None:
+        """Record a debug entry."""
+        self.entries.append(("debug", message, dict(fields)))
+
+    def info(self, message: str, **fields: JsonValue) -> None:
+        """Record an info entry."""
+        self.entries.append(("info", message, dict(fields)))
+
+    def warning(self, message: str, **fields: JsonValue) -> None:
+        """Record a warning entry."""
+        self.entries.append(("warning", message, dict(fields)))
+
+    def error(self, message: str, **fields: JsonValue) -> None:
+        """Record an error entry."""
+        self.entries.append(("error", message, dict(fields)))
+
+    def messages(self) -> list[str]:
+        """List just the messages, which is what most assertions want."""
+        return [message for _, message, _ in self.entries]
+
+
+class FakeSink:
+    """The write end of a local file, standing in for a storage backend's sink."""
+
+    def __init__(self, path: Path) -> None:
+        """Open the file for writing."""
+        self.path = path
+        self._handle = path.open("wb")
+
+    async def write(self, data: bytes) -> int:
+        """Append bytes."""
+        return self._handle.write(data)
+
+    def close(self) -> None:
+        """Finish the file."""
+        self._handle.close()
+
+
+class FakeStorage:
+    """A storage facade over one directory, backing the storage blocks in a test."""
+
+    def __init__(self, root: Path) -> None:
+        """Root the facade at a throwaway directory."""
+        self.root = root
+
+    def path_for(self, uri: str) -> Path:
+        """Map a URI onto a local path: absolute as given, relative under the root."""
+        _, _, location = uri.partition("://")
+        path = Path(location)
+        return path if path.is_absolute() else self.root / location
+
+    async def open_read(self, uri: str) -> AsyncGenerator[bytes]:
+        """Stream an object in two chunks, so callers cannot assume one."""
+        payload = self.path_for(uri).read_bytes()
+        middle = max(len(payload) // 2, 1)
+        yield payload[:middle]
+        if payload[middle:]:
+            yield payload[middle:]
+
+    def open_write(self, uri: str) -> AbstractAsyncContextManager[ByteSink]:
+        """Open a writer for a URI, creating the directories it needs."""
+
+        @asynccontextmanager
+        async def writer() -> AsyncGenerator[ByteSink]:
+            path = self.path_for(uri)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            sink = FakeSink(path)
+            try:
+                yield sink
+            finally:
+                sink.close()
+
+        return writer()
+
+    async def stat(self, uri: str) -> StatResult | None:
+        """Describe an object, or report that it is not there."""
+        path = self.path_for(uri)
+        if not path.is_file():
+            return None
+        info = path.stat()
+        return StatResult(uri=uri, size=info.st_size, modified_at=datetime.fromtimestamp(info.st_mtime, tz=UTC))
+
+    async def list(self, uri: str) -> AsyncIterator[StatResult]:
+        """List the objects matching a pattern, in a stable order."""
+        scheme, _, pattern = uri.partition("://")
+        for path in sorted(self.root.glob(pattern.lstrip("/"))):
+            if not path.is_file():
+                continue
+            info = path.stat()
+            yield StatResult(
+                uri=f"{scheme}://{path.relative_to(self.root)}",
+                size=info.st_size,
+                modified_at=datetime.fromtimestamp(info.st_mtime, tz=UTC),
+            )
+
+    async def delete(self, uri: str) -> None:
+        """Remove an object."""
+        self.path_for(uri).unlink(missing_ok=True)
+
+
+class FakeRuns:
+    """The runs facade, faked: an in-memory instance a composition block can drive."""
+
+    def __init__(self) -> None:
+        """Start with no pipelines and no runs."""
+        self.pipelines: set[str] = set()
+        self.snapshots: dict[UUID, RunSnapshot] = {}
+        self.started: list[tuple[str, dict[str, JsonValue], int]] = []
+        self.cancelled: list[UUID] = []
+        self.skip: set[str] = set()
+        self.refusal: str | None = None
+
+    def hold(
+        self,
+        pipeline: str,
+        state: RunState = RunState.QUEUED,
+        *,
+        total_steps: int = 0,
+        finished_steps: int = 0,
+    ) -> UUID:
+        """Install a run this instance holds, and return the id a handle would name."""
+        run_id = uuid4()
+        self.pipelines.add(pipeline)
+        self.snapshots[run_id] = RunSnapshot(
+            run_id=run_id,
+            pipeline=pipeline,
+            state=state,
+            total_steps=total_steps,
+            finished_steps=finished_steps,
+        )
+        return run_id
+
+    async def start(self, pipeline: str, params: Mapping[str, JsonValue], *, max_depth: int) -> StartedRun:
+        """Record the start and answer with a run, a skip, or the refusal the test installed."""
+        self.started.append((pipeline, dict(params), max_depth))
+        if self.refusal is not None:
+            raise RunRefused(self.refusal)
+        if pipeline in self.skip:
+            return StartedRun(pipeline=pipeline)
+        run_id = self.hold(pipeline)
+        return StartedRun(pipeline=pipeline, run_id=run_id, state=RunState.QUEUED)
+
+    async def snapshot(self, run_id: UUID) -> RunSnapshot | None:
+        """Describe a run this fake instance holds."""
+        return self.snapshots.get(run_id)
+
+    async def cancel(self, run_id: UUID, *, reason: str) -> bool:
+        """Cancel a run, unless it had already settled or was never here."""
+        self.cancelled.append(run_id)
+        held = self.snapshots.get(run_id)
+        if held is None or held.state.settled:
+            return False
+        self.snapshots[run_id] = held.model_copy(update={"state": RunState.CANCELLED, "error": reason})
+        return True
+
+
+class FakeContext:
+    """The engine's side of the bargain, faked: real storage, a recording log, a fake client."""
+
+    def __init__(self, storage: FakeStorage, scratch: str, work: Path | None = None) -> None:
+        """Bind the context to a storage root, a scratch prefix, and a local work directory."""
+        self.run_id: UUID = uuid4()
+        self.step = "step"
+        self.run_item_id: UUID | None = None
+        self.attempt = 1
+        self.started_at = datetime.now(UTC)
+        self.inline_capture = 8 * 1024
+        self.cursor: dict[str, JsonValue] | None = None
+        """What the last committed ``NotYet`` returned, which a test sets to poke again."""
+        self.params: dict[str, JsonValue] = {}
+        self.log = RecordingLogger()
+        self.connections: dict[str, BaseModel] = {}
+        self.storage_connections: dict[str, str] = {}
+        """Which connection code serves each storage scheme, as ``storage_connections`` maps them."""
+        self.schemas: dict[str, Any] = {}
+        self.formats: dict[str, FormatCheck] = {}
+        """Contributed format checkers a test installs, so a block can exercise ``format: <name>``."""
+        self.handler: Callable[[httpx2.Request], httpx2.Response] | None = None
+        self.scratch_uri = scratch
+        self.work_dir = work if work is not None else Path(tempfile.mkdtemp(prefix="dirigent-work-"))
+        self._storage = storage
+        self._runs = FakeRuns()
+
+    @property
+    def storage(self) -> FakeStorage:
+        """The storage facade."""
+        return self._storage
+
+    @property
+    def scratch(self) -> str:
+        """The run-scoped URI prefix."""
+        return self.scratch_uri
+
+    @property
+    def work(self) -> Path:
+        """The run's directory on this worker's own filesystem, made on first read.
+
+        Absolute whatever it was set to, as the engine's own is: a child process is given
+        both a working directory and the paths it is to touch.
+        """
+        directory = self.work_dir.absolute()
+        directory.mkdir(parents=True, exist_ok=True)
+        return directory
+
+    @property
+    def runs(self) -> FakeRuns:
+        """The instance's own runs, as a composition block reaches them."""
+        return self._runs
+
+    def as_context(self) -> StepContext:
+        """Present the fake as the protocol a block is typed against.
+
+        The fake keeps its own logger and its own params dictionary so a test can assert on
+        them, and a protocol's mutable attribute matches neither of those narrower types.
+        """
+        return cast("StepContext", self)
+
+    def connection(self, ref: str, model: type[Any]) -> Any:
+        """Resolve a named connection the test installed."""
+        return self.connections[ref]
+
+    def storage_connection(self, scheme: str, model: type[Any]) -> Any:
+        """Resolve the connection the test bound to a storage scheme, or None where it bound none."""
+        ref = self.storage_connections.get(scheme)
+        return None if ref is None else self.connections[ref]
+
+    def schema(self, code: str) -> Any:
+        """Resolve a named schema the test installed; an unknown code fails as the engine's does."""
+        return self.schemas[code]
+
+    def format_checker(self) -> FormatChecker:
+        """The base formats plus any the test installed on ``formats``."""
+        return format_checker_with(self.formats)
+
+    def http(self, ref: str) -> httpx2.AsyncClient:
+        """Build a client whose transport is the test's own handler."""
+        if self.handler is None:
+            raise AssertionError("this test asked for an HTTP client but installed no handler")
+        return httpx2.AsyncClient(base_url="http://service.test", transport=httpx2.MockTransport(self.handler))

dirigent_testing-0.9.0/src/dirigent_testing/environment.py

@@ -0,0 +1,48 @@
+"""Putting a test suite in a known environment: dirigent's own variables, colour, and width.
+
+Both are explicit calls rather than import side effects, so installing the plugin never
+rewrites the environment of a suite that did not ask for it.
+"""
+
+import os
+import shutil
+
+import pytest
+
+#: Prefixes of variables that configure dirigent at runtime.
+CONFIGURING_PREFIXES = ("DIRIGENT_", "DG_", "OTEL_")
+
+#: Width rich renders at under test, so an assertion never depends on the terminal.
+TEST_WIDTH = "200"
+
+_real_width: int | None = None
+
+
+def pin_terminal() -> int:
+    """Fix width and colour for everything built afterwards, and return the real width.
+
+    A console reads both when it is built, which happens at import, so this belongs at the
+    top of a conftest rather than in a fixture. The width returned is the one the terminal
+    reported the first time, which the pinning then hides.
+    """
+    global _real_width
+    if _real_width is None:
+        _real_width = shutil.get_terminal_size().columns
+    os.environ["COLUMNS"] = TEST_WIDTH
+    os.environ["TERMINAL_WIDTH"] = TEST_WIDTH  # typer renders help at this width
+    # A test that reads what a command printed must see the same text whether or not a
+    # terminal is attached, and rich decides colour when a console is built.
+    os.environ["NO_COLOR"] = "1"
+    return _real_width
+
+
+def scrub_configuration(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Take every variable configuring dirigent out of one test's environment.
+
+    A developer with DIRIGENT_ENABLED_UNSAFE_BLOCKS set for manual testing would otherwise
+    turn the tests that prove the guard refuses into passes.
+    """
+    for name in list(os.environ):
+        if name.startswith(CONFIGURING_PREFIXES):
+            monkeypatch.delenv(name, raising=False)
+    monkeypatch.setenv("COLUMNS", TEST_WIDTH)

dirigent_testing-0.9.0/src/dirigent_testing/fixtures.py

@@ -0,0 +1,58 @@
+"""The pytest plugin: the fixtures a block author gets from installing this package.
+
+Registered by entry point, so the names live in every consumer's suite. They are prefixed
+to say what they are handed by, because a consumer's own fixtures got there first.
+"""
+
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Final
+
+import pytest
+
+from dirigent_testing.doubles import FakeContext, FakeStorage
+from dirigent_testing.environment import scrub_configuration
+
+#: The server the lanes that need a real PostgreSQL start for themselves.
+POSTGRES_IMAGE: Final = "postgres:17-alpine"
+
+
+@pytest.fixture(scope="session")
+def postgres_url() -> Iterator[str]:
+    """Start a real PostgreSQL for the session, and hand back an asyncpg URL.
+
+    Session-scoped, so every lane that asks for it shares one container.
+    """
+    postgres = pytest.importorskip("testcontainers.community.postgres")
+    with postgres.PostgresContainer(POSTGRES_IMAGE, driver="asyncpg") as container:
+        yield container.get_connection_url()
+
+
+@pytest.fixture
+def block_storage(tmp_path: Path) -> FakeStorage:
+    """A storage facade over a throwaway directory."""
+    return FakeStorage(tmp_path)
+
+
+@pytest.fixture
+def block_ctx(block_storage: FakeStorage, tmp_path: Path) -> FakeContext:
+    """A context wired to that storage, with a scratch prefix inside it."""
+    return FakeContext(block_storage, "file://scratch", work=tmp_path / "work" / "runs" / "one")
+
+
+@pytest.fixture
+def local_block_ctx(tmp_path: Path) -> FakeContext:
+    """A context whose scratch is a real file:// prefix, for a block that reads it as files."""
+    root = tmp_path / "artifacts"
+    root.mkdir()
+    return FakeContext(FakeStorage(root), f"file://{root}/runs/one", work=tmp_path / "work" / "runs" / "one")
+
+
+@pytest.fixture
+def defaults_only_environment(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Run a test against defaults, whatever the shell exports.
+
+    Requested rather than autouse: a distributed plugin must not strip the environment of a
+    suite that never asked it to, so a consumer opts in -- once, from its own conftest.
+    """
+    scrub_configuration(monkeypatch)

dirigent_testing-0.9.0/src/dirigent_testing/running.py

@@ -0,0 +1,27 @@
+"""Making one block call from a test, through the validation the engine puts in front of it."""
+
+from collections.abc import Mapping
+from typing import Any
+
+from pydantic import BaseModel
+
+from dirigent_plugin import AnyOperator, AnySensor, Operator, StepContext
+from dirigent_testing.doubles import FakeContext
+
+
+async def call_block(
+    block: AnyOperator | AnySensor,
+    config: Mapping[str, Any],
+    ctx: StepContext | FakeContext,
+) -> BaseModel:
+    """Validate the config the way the engine would, then make the block's first call.
+
+    An operator's execute or a sensor's poke, with the validated config -- so a test
+    exercises the same validation path a real run does, and a config the schema refuses
+    fails here rather than silently succeeding with defaults.
+    """
+    context = ctx.as_context() if isinstance(ctx, FakeContext) else ctx
+    validated = block.config_model.model_validate(config)
+    if isinstance(block, Operator):
+        return await block.execute(validated, context)
+    return await block.poke(validated, context)