envoy.testing¶
envoy.testing ¶
envoy.testing -- Test helpers for code that calls the envoy Python API.
Provides lightweight context managers for patching the bundle discovery
environment inside unit tests without touching the live filesystem or the
real ENVOY_BNDL_ROOTS variable.
Carried over unchanged from the pre-Rust-migration implementation
(py/envoy/testing.py): this module only manipulates process
environment variables via :mod:os and :mod:pathlib, with no dependency
on any envoy-core internals, so there is nothing to port -- it works
identically whether the compiled envoy._envoy extension or the pure
Python implementation backs the rest of the package.
Usage example::
import envoy.testing as envoy_testing
def test_my_tool():
with envoy_testing.patchBundleRoots(['/test/fixtures/my_bundle']):
result = my_code_that_calls_envoy()
assert result == expected
# Patch a bare commands.json instead of full bundles
def test_with_commands_file(tmp_path):
commands = {'python': {'environment': ['python_env.json']}}
cf = tmp_path / '.envoy' / 'commands.json'
cf.parent.mkdir()
cf.write_text(json.dumps(commands))
with envoy_testing.patchCommandsFile(cf):
...
patchBundleRoots ¶
Context manager that temporarily overrides ENVOY_BNDL_ROOTS.
All bundle discovery performed inside the block (by :mod:envoy.proc
or direct calls to :func:~envoy._discovery.discoverBundlesAuto) will
search roots instead of whatever ENVOY_BNDL_ROOTS is set to in the
real environment.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
roots
|
list[str | Path]
|
Sequence of directory paths to use as bundle search roots.
Each path should contain at least one subdirectory with a
|
required |
Example::
with envoy_testing.patchBundleRoots(['/test/bundles']):
rc = proc.call(['my_tool', '--help'])
Source code in envoy/testing.py
patchCommandsFile ¶
Context manager that temporarily points envoy at a specific commands.json file.
Useful when your test fixture provides a bare commands.json rather
than a full bundle directory tree. Under the hood this clears
ENVOY_BNDL_ROOTS and sets ENVOY_COMMANDS_FILE so that
:func:~envoy._commands.findCommandsFile resolves to the given path.
.. note::
This helper is complementary to :func:patchBundleRoots. Use
:func:patchBundleRoots when your fixture looks like a real bundle
(my_bundle/.envoy/commands.json), and use this helper when you
only have a standalone JSON file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
commands_file
|
str | Path
|
Path to the |
required |
Example::
with envoy_testing.patchCommandsFile(tmp_path / 'commands.json'):
rc = proc.call(['my_cmd'])