⌚ Add deffered shed fixture

Author: bdsoha

README.md

@@ -1,16 +1,14 @@
 # KloudKIT TestShed
 
-> Meet **KloudKIT TestShed**, a tidy home for your integration-testing power tools.
->
-> It snap-fits into `pytest`, auto-provisions Docker, runs Playwright, and cleans up after itself
-> so you can focus on building sharp tests.
+A pytest plugin for integration testing with Docker and Playwright.
+It handles container lifecycle, browser provisioning, and cleanup automatically.
 
 ## Features
 
-- **Automated Docker management:** Spin up and control containers from tests.
-- **Playwright integration:** Run browser tests in isolated Docker environments.
-- **Configurable via markers & CLI:** Tune environments per test or suite.
-- **Automatic resource cleanup:** Ensures a clean state after tests.
+- **Docker management:** provision and control containers from tests.
+- **Playwright integration:** browser testing in isolated Docker environments.
+- **Configurable via markers & CLI:** tune environments per test or suite.
+- **Automatic cleanup:** containers and volumes are removed after tests.
 
 ## Installation
 
@@ -40,9 +38,44 @@ from kloudkit.testshed.fixtures.playwright import playwright_browser
 
 TestShed provides fixtures to manage containers inside your tests.
 
-#### High-level `shed` fixtures
+#### Configure containers with decorators
+
+Configure containers using `pytest` markers:
 
-Use the `shed` fixture for smart container management with configurable defaults:
+- **`@shed_config(**kwargs)`:** pass arguments to the container factory (e.g. `publish`, `networks`).
+- **`@shed_env(**envs)`:** set environment variables.
+- **`@shed_volumes(*mounts)`:** mount volumes as `(source, dest)` tuples or `BaseVolume` instances.
+- **`@shed_mutable()`:** force a dedicated container for tests that mutate state (bypasses the shared default).
+
+```python
+from kloudkit.testshed.docker import InlineVolume, RemoteVolume
+
+@shed_config(publish=[(8080, 80)])
+@shed_env(MY_ENV_VAR="hello")
+@shed_volumes(
+  ("/path/to/host/data", "/app/data"),
+  InlineVolume("/app/config.txt", "any content you want", mode=0o644),
+  RemoteVolume("/app/remote-config.json", "https://api.example.com/config.json", mode=0o644),
+)
+def test_configured_docker_app(shed):
+  # ... test logic ...
+```
+
+Use `@shed_mutable()` when your test writes data, installs packages, or otherwise changes the container.
+
+This ensures it gets its own instance instead of reusing the shared default:
+
+```python
+@shed_mutable()
+def test_install_package(shed):
+  shed.execute("apt-get install -y curl")
+
+  assert "curl" in shed.execute("which curl")
+```
+
+#### High-level `shed` fixture
+
+Use the `shed` fixture for container management with configurable defaults:
 
 ```python
 import pytest
@@ -73,55 +106,55 @@ def test_my_app_with_debug(shed):
   assert shed.execute("echo $APP_PORT") == "3000"
 ```
 
-You can also use the factory directly:
+#### Deferred deployment with `shed_deferred`
+
+Use `shed_deferred` when you need to control *when* the container starts, for pre-deployment
+setup, runtime parameterization, or spinning up multiple containers in a single test:
 
 ```python
-def test_custom_setup(shed_factory):
-  container = shed_factory(envs={"CUSTOM_VAR": "value"})
-  # ... test logic ...
+@shed_env(APP_PORT="3000")
+def test_deferred_deployment(shed_deferred):
+  # Container is NOT running yet — do setup here
+  # ...
+
+  # Deploy with optional call-time overrides
+  container = shed_deferred(envs={"DEBUG": "true"})
+  # envs are merged: APP_PORT=3000 + DEBUG=true
+
+  assert container.execute("echo $DEBUG") == "true"
+  assert container.execute("echo $APP_PORT") == "3000"
+
+
+def test_multiple_containers(shed_deferred):
+  primary = shed_deferred(envs={"ROLE": "primary"})
+  replica = shed_deferred(envs={"ROLE": "replica"})
+  # Each call spins up a new container
 ```
 
+Call-time parameters merge with decorator config:
+
+- **`envs`:** dict merge *(call-time values override decorator values)*.
+- **`volumes`:** concatenated *(call-time volumes added after decorator volumes)*.
+- **`**kwargs`:** passed as config args *(override decorator `@shed_config` values)*.
+
 #### Basic Docker container
 
-For a lower-level API, use the `docker_sidecar` fixture to create containers:
+For a lower-level API, use the `docker_sidecar` fixture:
 
 ```python
-import pytest
-
 def test_my_docker_app(docker_sidecar):
-  # Launch a simple Nginx container
+  # Launch a container
   nginx = docker_sidecar("nginx:latest", publish=[(8080, 80)])
 
   # Execute a command inside the container
-  assert "nginx version" in nginx.execute(["nginx", "-v"])
+  hostname = nginx.execute("cat /etc/hostname")
+  assert len(hostname) > 0
 
   # Access the container's IP
-  print(f"Nginx container IP: {nginx.ip()}")
+  print(f"Container IP: {nginx.ip()}")
 
   # Interact with the file system
-  assert "/usr/share/nginx/html" in nginx.fs.ls("/usr/share/nginx")
-```
-
-#### Configure containers with decorators
-
-Configure containers using `pytest` markers/decorators:
-
-- **`@shed_config(**kwargs)`:** Generic container args.
-- **`@shed_env(**envs)`:** Environment variables.
-- **`@shed_volumes(*mounts)`:** Volume mounts as `(source, dest)` or `BaseVolume`.
-- **`@shed_mutable()`:** Force non-default shed for tests that perform mutable operations.
-
-```python
-from kloudkit.testshed.docker import InlineVolume, RemoteVolume
-
-@shed_env(MY_ENV_VAR="hello")
-@shed_volumes(
-  ("/path/to/host/data", "/app/data"),
-  InlineVolume("/app/config.txt", "any content you want", mode=0o644),
-  RemoteVolume("/app/remote-config.json", "https://api.example.com/config.json", mode=0o644),
-)
-def test_configured_docker_app(shed):
-  # ... test logic ...
+  assert "html" in nginx.fs.ls("/usr/share/nginx")
 ```
 
 ### Playwright browser testing
@@ -140,13 +173,13 @@ def test_example_website(playwright_browser):
 
 TestShed extends `pytest` with options to control the Docker environment:
 
-- **`--shed`:** Enable TestShed for the current test suite *(default: disabled)*.
-- **`--shed-image IMAGE`:** Base image *(e.g., `ghcr.io/acme/app`)*.
-- **`--shed-tag TAG|SHA`:** Image tag or digest *(default: `tests`)*.
+- **`--shed`:** enable TestShed for the current test suite *(default: disabled)*.
+- **`--shed-image IMAGE`:** base image *(e.g., `ghcr.io/acme/app`)*.
+- **`--shed-tag TAG|SHA`:** image tag or digest *(default: `tests`)*.
 - **`--shed-build-context DIR`:** Docker build context *(default: `pytest.ini` directory)*.
-- **`--shed-image-policy POLICY`:** Image acquisition policy for building or pulling *(default: `pull`)*.
-- **`--shed-skip-bootstrap`:** Skip Docker bootstrapping *(useful for unit tests)*.
-- **`--shed-container-logs`:** Print container logs on failure *(default: disabled)*.
+- **`--shed-image-policy POLICY`:** image acquisition policy *(default: `pull`)*.
+- **`--shed-skip-bootstrap`:** skip Docker bootstrapping *(useful for unit tests)*.
+- **`--shed-container-logs`:** print container logs on failure *(default: disabled)*.
 
 > [!NOTE]
 > When TestShed is installed globally, you must explicitly enable it per suite with
@@ -157,10 +190,10 @@ TestShed extends `pytest` with options to control the Docker environment:
 
 The `--shed-image-policy` option controls how TestShed acquires Docker images:
 
-- **`pull`** *(default)***:** Pull image if not found locally, build as fallback.
-- **`build`:** Build only if image doesn't exist locally.
-- **`require`:** Require existing local image *(fails if not found)*.
-- **`rebuild`:** Always rebuild the image.
+- **`pull`** *(default)*: pull image if not found locally, build as fallback.
+- **`build`:** build only if image doesn't exist locally.
+- **`require`:** require existing local image *(fails if not found)*.
+- **`rebuild`:** always rebuild the image.
 
 #### Examples
 

pyproject.toml

@@ -18,7 +18,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-  "playwright>=1.57.0,<2.0.0",
+  "playwright>=1.58.0,<2.0.0",
   "pytest>=9.0.2",
   "python-on-whales>=0.80.0,<1.0.0",
   "PyYAML>=6.0.3,<7.0.0",
@@ -34,8 +34,8 @@ dynamic = ["readme", "version"]
 [project.optional-dependencies]
 dev = [
   "pre-commit>=4.5.1",
-  "ruff>=0.14.11",
-  "coverage>=7.13.1",
+  "ruff>=0.15.5",
+  "coverage>=7.13.4",
   "pytest-cov>=7.0.0",
 ]
 

src/kloudkit/testshed/__init__.py

@@ -1 +1 @@
-__version__ = "0.0.9"
+__version__ = "0.0.10"

src/kloudkit/testshed/docker/container_config.py

@@ -27,6 +27,22 @@ def to_dict(self) -> dict:
       **self.args,
     )
 
+  def merge(
+    self,
+    *,
+    envs: dict | None = None,
+    volumes: tuple | None = None,
+    args: dict | None = None,
+  ) -> Self:
+    """Return a new config with call-time overrides merged in."""
+
+    return type(self)(
+      envs={**self.envs, **(envs or {})},
+      volumes=self.volumes + tuple(volumes or ()),
+      args={**self.args, **(args or {})},
+      test_name=self.test_name,
+    )
+
   @classmethod
   def create(cls, request: pytest.FixtureRequest) -> Self:
     """Create configs from a pytest request of the current node."""

src/kloudkit/testshed/fixtures/shed.py

@@ -62,6 +62,21 @@ def _wrapper(**kwargs):
   return _wrapper
 
 
+@pytest.fixture
+def shed_deferred(request: pytest.FixtureRequest):
+  """Callable that deploys a container when invoked."""
+
+  config = ContainerConfig.create(request)
+  shed_factory = request.getfixturevalue("shed_factory")
+
+  def _deploy(*, envs=None, volumes=None, **kwargs):
+    return shed_factory(
+      **config.merge(envs=envs, volumes=volumes, args=kwargs).to_dict()
+    )
+
+  return _deploy
+
+
 @pytest.fixture
 def shed(request: pytest.FixtureRequest):
   """Reuses default or creates new based on markers."""

tests/unit/docker/test_container_config.py

@@ -83,3 +83,56 @@ def test_create_with_all_markers():
   assert config.volumes == ("/vol1",)
   assert config.args == {"image": "test:latest"}
   assert config.test_name == "test_module::test_function"
+
+
+def test_merge_with_no_overrides():
+  config = ContainerConfig(
+    envs={"A": "1"}, volumes=("/v1",), args={"x": "y"}, test_name="test_fn"
+  )
+
+  merged = config.merge()
+
+  assert merged.envs == {"A": "1"}
+  assert merged.volumes == ("/v1",)
+  assert merged.args == {"x": "y"}
+  assert merged.test_name == "test_fn"
+
+
+def test_merge_envs_override_and_add():
+  config = ContainerConfig(
+    envs={"A": "1", "B": "2"}, volumes=(), args={}, test_name="test_fn"
+  )
+
+  merged = config.merge(envs={"B": "overridden", "C": "3"})
+
+  assert merged.envs == {"A": "1", "B": "overridden", "C": "3"}
+
+
+def test_merge_volumes_concatenate():
+  config = ContainerConfig(
+    envs={}, volumes=("/v1",), args={}, test_name="test_fn"
+  )
+
+  merged = config.merge(volumes=("/v2", "/v3"))
+
+  assert merged.volumes == ("/v1", "/v2", "/v3")
+
+
+def test_merge_args_override():
+  config = ContainerConfig(
+    envs={}, volumes=(), args={"a": "1", "b": "2"}, test_name="test_fn"
+  )
+
+  merged = config.merge(args={"b": "overridden", "c": "3"})
+
+  assert merged.args == {"a": "1", "b": "overridden", "c": "3"}
+
+
+def test_merge_preserves_test_name():
+  config = ContainerConfig(
+    envs={}, volumes=(), args={}, test_name="original::test"
+  )
+
+  merged = config.merge(envs={"X": "1"})
+
+  assert merged.test_name == "original::test"