From d703efcb468162e93577287f64682c178c2fd737 Mon Sep 17 00:00:00 2001 From: Tobias Mayer Date: Wed, 27 May 2026 14:33:47 +0200 Subject: [PATCH 1/2] Document inline dependency controls Document inline Python dependency handling for test fixtures and list the environment variable that disables runtime installation when callers manage dependencies themselves. Assisted-by: GPT-5 (Codex) --- .../docs/guides/testing/create-fixtures.mdx | 23 +++++++++++++++++++ .../docs/reference/test-framework/index.mdx | 3 +++ 2 files changed, 26 insertions(+) diff --git a/src/content/docs/guides/testing/create-fixtures.mdx b/src/content/docs/guides/testing/create-fixtures.mdx index 9e331a275..440ce4854 100644 --- a/src/content/docs/guides/testing/create-fixtures.mdx +++ b/src/content/docs/guides/testing/create-fixtures.mdx @@ -50,6 +50,29 @@ The harness calls the generator once per fixture activation. Everything before also receive a per-test scratch directory via `TENZIR_TMP_DIR` for temporary files. +## Declare Python dependencies + +Fixture modules can declare Python package dependencies with PEP 723 script +metadata. Put the metadata block at the top of the fixture file: + +```python +# /// script +# dependencies = ["boto3"] +# /// + +from tenzir_test import fixture +``` + +When fixture modules declare dependencies, `tenzir-test` installs missing +packages into the active Python environment with `uv` before it imports the +fixtures. If a bare dependency name, such as `boto3`, is already installed, the +harness reuses it instead of running `uv pip install`. + +Set `TENZIR_TEST_DISABLE_INLINE_DEPENDENCY_INSTALL=1` when another tool, such +as Nix, provisions all fixture dependencies and `tenzir-test` should not install +packages at runtime. The harness still reads dependency metadata, but fixture +imports can fail if the dependency is not actually available. + ## Use the fixture in a test Request a fixture by name in the test's frontmatter. The harness starts it diff --git a/src/content/docs/reference/test-framework/index.mdx b/src/content/docs/reference/test-framework/index.mdx index fc9f2fc88..c95d78de2 100644 --- a/src/content/docs/reference/test-framework/index.mdx +++ b/src/content/docs/reference/test-framework/index.mdx @@ -1229,6 +1229,9 @@ walks through the full implementation. `--debug`). - `TENZIR_TEST_DISABLE_HOOKS` – Disable project hook loading and invocation (equivalent to `--no-hooks`). +- `TENZIR_TEST_DISABLE_INLINE_DEPENDENCY_INSTALL` – Disable runtime + installation for inline Python dependencies declared by tests or fixtures. + Use this when another tool provisions the Python environment. ### Binary resolution From 98cc6c39ddd6e8a710b3c08355bb4201e6bbe225 Mon Sep 17 00:00:00 2001 From: Tobias Mayer Date: Wed, 27 May 2026 14:46:43 +0200 Subject: [PATCH 2/2] Document inline dependency install flag Merge the fixture dependency notes into the existing guide section so the anchor remains stable. Document the new CLI flag alongside the environment variable for pre-provisioned Python environments. Assisted-by: GPT-5 (Codex) --- .../docs/guides/testing/create-fixtures.mdx | 38 +++++++------------ .../docs/reference/test-framework/index.mdx | 5 ++- 2 files changed, 17 insertions(+), 26 deletions(-) diff --git a/src/content/docs/guides/testing/create-fixtures.mdx b/src/content/docs/guides/testing/create-fixtures.mdx index 440ce4854..6cfd60781 100644 --- a/src/content/docs/guides/testing/create-fixtures.mdx +++ b/src/content/docs/guides/testing/create-fixtures.mdx @@ -50,29 +50,6 @@ The harness calls the generator once per fixture activation. Everything before also receive a per-test scratch directory via `TENZIR_TMP_DIR` for temporary files. -## Declare Python dependencies - -Fixture modules can declare Python package dependencies with PEP 723 script -metadata. Put the metadata block at the top of the fixture file: - -```python -# /// script -# dependencies = ["boto3"] -# /// - -from tenzir_test import fixture -``` - -When fixture modules declare dependencies, `tenzir-test` installs missing -packages into the active Python environment with `uv` before it imports the -fixtures. If a bare dependency name, such as `boto3`, is already installed, the -harness reuses it instead of running `uv pip install`. - -Set `TENZIR_TEST_DISABLE_INLINE_DEPENDENCY_INSTALL=1` when another tool, such -as Nix, provisions all fixture dependencies and `tenzir-test` should not install -packages at runtime. The harness still reads dependency metadata, but fixture -imports can fail if the dependency is not actually available. - ## Use the fixture in a test Request a fixture by name in the test's frontmatter. The harness starts it @@ -193,13 +170,18 @@ def localstack(): ... ``` -When a fixture file declares dependencies, `tenzir-test` installs them with -`uv` before importing project fixtures: +When a fixture file declares dependencies, `tenzir-test` installs missing +packages into the active Python environment with `uv` before importing project +fixtures: ```sh uv pip install --python boto3 ``` +If a bare dependency name, such as `boto3`, is already installed, the harness +reuses it instead of running `uv pip install`. Versioned requirements, such as +`boto3>=1.34`, still use `uv` so the requested version is enforced. + This works for `fixtures.py` and for any Python module under `fixtures/`, including nested modules imported by `fixtures/__init__.py`. The feature also applies in standalone fixture mode, such as `uvx tenzir-test --fixture @@ -210,6 +192,12 @@ fixture imports an undeclared package, `tenzir-test` still reports the missing dependency and suggests running the harness from a project environment or with `uvx --with`. +Pass `--disable-inline-dependency-install`, or set +`TENZIR_TEST_DISABLE_INLINE_DEPENDENCY_INSTALL=1`, when another tool, such as +Nix, provisions all fixture dependencies and `tenzir-test` should not install +packages at runtime. The harness still reads dependency metadata, but fixture +imports can fail if the dependency is not actually available. + ## Use container runtime helpers When a fixture manages a single container directly rather than orchestrating diff --git a/src/content/docs/reference/test-framework/index.mdx b/src/content/docs/reference/test-framework/index.mdx index c95d78de2..136f25ed0 100644 --- a/src/content/docs/reference/test-framework/index.mdx +++ b/src/content/docs/reference/test-framework/index.mdx @@ -204,6 +204,9 @@ Useful options: - `--no-hooks`: Disable project hook loading and invocation. Use this when you need to recover from a broken hook or compare behavior without hook side effects. +- `--disable-inline-dependency-install`: Disable runtime installation for + inline Python dependencies declared by tests or fixtures. Use this when + another tool provisions the Python environment. Set `TENZIR_TEST_DEBUG=1` in CI when you want the same diagnostics without passing `--debug` on the command line. @@ -1231,7 +1234,7 @@ walks through the full implementation. (equivalent to `--no-hooks`). - `TENZIR_TEST_DISABLE_INLINE_DEPENDENCY_INSTALL` – Disable runtime installation for inline Python dependencies declared by tests or fixtures. - Use this when another tool provisions the Python environment. + Equivalent to `--disable-inline-dependency-install`. ### Binary resolution