spltz-viur-testing 0.1.0__py3-none-any.whl

spltz_viur_testing-0.1.0.dist-info/METADATA

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: spltz-viur-testing
+Version: 0.1.0
+Summary: Safe test-mode for ViUR core projects — Playwright e2e ready.
+Author: Andreas H. Kelch
+License: MIT License
+        
+        Copyright © 2026 Andreas H. Kelch
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        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
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/sprengplatz/viur-testing
+Project-URL: Documentation, https://sprengplatz.github.io/viur-testing/
+Project-URL: Repository, https://github.com/sprengplatz/viur-testing.git
+Project-URL: Bug Tracker, https://github.com/sprengplatz/viur-testing/issues
+Project-URL: Changelog, https://github.com/sprengplatz/viur-testing/blob/main/CHANGELOG.md
+Keywords: viur,e2e,testing,playwright
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: viur-core<4,>=3.7
+Provides-Extra: test
+Requires-Dist: pytest~=8.0; extra == "test"
+Requires-Dist: pytest-cov~=5.0; extra == "test"
+Requires-Dist: coverage[toml]~=7.0; extra == "test"
+Requires-Dist: spltz-viur-light-mock>=0.1; extra == "test"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material~=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]~=0.26; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: spltz-viur-testing[docs,test]; extra == "dev"
+Requires-Dist: build~=1.2; extra == "dev"
+Dynamic: license-file
+
+# viur-testing
+
+[![Tests](https://github.com/sprengplatz/viur-testing/actions/workflows/test.yml/badge.svg)](https://github.com/sprengplatz/viur-testing/actions/workflows/test.yml)
+[![Docs](https://github.com/sprengplatz/viur-testing/actions/workflows/docs.yml/badge.svg)](https://sprengplatz.github.io/viur-testing/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Safe test-mode for ViUR core projects — primarily for Playwright
+end-to-end tests. Swaps the default datastore database out for a
+dedicated named database (default: `viur-tests`), with a bilateral
+handshake that refuses to let any test or endpoint run unless both the
+server **and** the runner agree they are talking to the test instance.
+
+## Bilateral guarantee in six lines
+
+1. **`activate()` refuses outside `conf.instance.is_dev_server`** —
+   read from viur-core's canonical flag.
+2. **Synchronous datastore probe** in the target database has to
+   succeed before the client swap is applied.
+3. **`TestModule` *and* `ConfigModule` both refuse to instantiate**
+   outside the dev server *or* without a prior `activate()` call —
+   both `__init__`s raise in either case. Even a host that bypasses
+   the `TestModule` container and mounts `ConfigModule` directly is
+   subject to the same checks, so a forgotten activate or a stray
+   production mount fails loudly at boot.
+4. **Per-request token validator** (`X-Viur-Test-Token`) blocks every
+   request that does not carry the session token, except the two
+   bootstrap endpoints.
+5. **`protect()` installs a production-side header guard** that 403s
+   any request carrying the test token header outside dev, regardless
+   of its value. Installed in every environment.
+6. **Runner preflight** calls `/json/_test/config/status` and refuses to run
+   any test if the server's reply (database, project_id, token hash)
+   does not match.
+
+The session token is stored only in the test database itself
+(kind `viur-tests`, entity `auth-token`) — never on disk. App Engine
+file-system writes are not needed.
+
+## Module layout
+
+```
+/_test/                    TestModule (container, refuses outside dev mode)
+  /_test/config/status     ConfigModule.status — issues/returns token
+  /_test/config/finish     ConfigModule.finish — deletes token entity
+```
+
+Future test flavours (load test, integration helpers, …) go in as
+sibling submodules under the same `_test` container.
+
+## Requirements
+
+- Python ≥ 3.12
+- viur-core ≥ 3.7, < 4
+- A named Datastore database (default name: `viur-tests`) created in
+  your GCP project alongside `(default)`.
+
+## Install
+
+The PyPI distribution name is `spltz-viur-testing` (experimental
+prefix); the Python import path stays `viur.testing`:
+
+```sh
+pip install spltz-viur-testing
+```
+
+```python
+import viur.testing
+viur.testing.setup()
+```
+
+## Server-side wiring
+
+Two one-liners. `main.py` — **as the first lines, before any
+`viur.core` import**:
+
+```python
+import viur.testing
+viur.testing.setup()
+
+# Only now may viur.core be imported by your own code.
+from viur.core import setup as core_setup
+import modules
+import render
+
+core_setup(modules, render)
+```
+
+`viur.testing.setup()` checks the `VIUR_TESTING_ENABLE` env var; if
+truthy it calls `activate()` (datastore client swap + key-factory
+patch + closed-system whitelist + state priming + validator install)
+and always installs the production header guard via `protect()`.
+
+In `modules/__init__.py` register the test endpoints — idempotent and
+safe to leave in place for production deployments (no-op when test
+mode isn't armed):
+
+```python
+# modules/__init__.py
+import viur.testing
+viur.testing.register_modules(globals())
+```
+
+That exposes `POST /json/_test/config/status` and `POST /json/_test/config/finish`.
+Both endpoints re-verify `conf.instance.is_dev_server` and the active
+datastore database before performing any work — defence in depth on
+top of the `TestModule.__init__` guard.
+
+If you need more control, the two functions wrap underlying primitives
+you can call yourself: `viur.testing.activate(database=...)`,
+`viur.testing.protect()`, plus direct mounting via
+`from viur.testing._test import TestModule`.
+
+## Running the dev server with test mode
+
+Toggle test mode at boot by setting the env var that `setup()` reads:
+
+```sh
+VIUR_TESTING_ENABLE=1 viur run
+```
+
+Without the env var, `setup()` skips `activate()` and the process boots
+against the default database as if the package were not installed.
+
+When test mode is active, the dev-server boot banner gains two extra
+lines — `database = …` and `namespace = …` — so the running slice is
+visible at a glance. The namespace line is rendered unconditionally;
+without `VIUR_TESTING_NAMESPACE` it falls back to `(default)`, making
+it obvious that test mode is armed but namespace isolation is **not**
+in effect:
+
+```
+# With VIUR_TESTING_NAMESPACE=alice
+################## LOCAL DEVELOPMENT SERVER IS UP AND RUNNING ##################
+#                          project = my-viur-project                           #
+#                               python = 3.13.0                                #
+#                                viur = 3.8.25                                 #
+#                            database = viur-tests                             #
+#                              namespace = alice                               #
+################################################################################
+
+# Without VIUR_TESTING_NAMESPACE (or with empty value)
+################## LOCAL DEVELOPMENT SERVER IS UP AND RUNNING ##################
+#                          project = my-viur-project                           #
+#                               python = 3.13.0                                #
+#                                viur = 3.8.25                                 #
+#                            database = viur-tests                             #
+#                            namespace = (default)                             #
+################################################################################
+```
+
+## Concurrency: sharing one test database across multiple testers
+
+The `viur-tests` database is a shared GCP resource. If two engineers
+both boot a dev server with the same database and run tests at the
+same time, their entities will collide — Person A's seed wipes
+Person B's user, Person B's test queries find leftovers from Person A.
+
+The fix is the optional `namespace` argument. ViUR-testing passes it
+to `google.cloud.datastore.Client(database=…, namespace=…)` and rewires
+`viur.core.db.Key` so every read and write in the process is scoped
+to that namespace. Different namespaces in the same database are
+fully isolated — no separate DB provisioning needed.
+
+Boot each dev server with its own namespace:
+
+```sh
+# Alice's machine
+VIUR_TESTING_ENABLE=1 VIUR_TESTING_NAMESPACE=alice viur run
+
+# Bob's machine
+VIUR_TESTING_ENABLE=1 VIUR_TESTING_NAMESPACE=bob viur run
+
+# CI for PR #42
+VIUR_TESTING_ENABLE=1 VIUR_TESTING_NAMESPACE=ci-pr-42 viur run
+```
+
+The runner-side `require_test_mode` can assert the expected namespace
+to fail fast when somebody points at the wrong slice::
+
+    from viur.testing import require_test_mode
+
+    status = require_test_mode(
+        "http://localhost:8080",
+        expected_namespace="alice",  # omit to skip; pass None for default
+    )
+
+`VIUR_TESTING_NAMESPACE` may be empty or unset — both mean "no
+namespace, use the Datastore default". This is the existing behaviour
+when no namespaces are needed (e.g. single-developer setup).
+
+## Runner-side wiring (pytest + Playwright)
+
+```python
+# tests/conftest.py
+import pytest
+from viur.testing import require_test_mode, finish
+
+_BASE_URL = "http://localhost:8080"
+
+
+@pytest.fixture(scope="session")
+def test_session():
+    status = require_test_mode(_BASE_URL)
+    yield status
+    finish(_BASE_URL, status.token)
+```
+
+If the server is not in test mode, points at the wrong database, or
+the token hash does not match the returned token, `require_test_mode`
+raises `TestModePreflightError` and no test ever runs.
+
+For Playwright, inject the token as a default header on the browser
+context:
+
+```python
+@pytest.fixture
+def context(browser, test_session):
+    return browser.new_context(
+        extra_http_headers={"X-Viur-Test-Token": test_session.token},
+    )
+```
+
+## Naming
+
+The Python package keeps its repository name `viur-testing` for stability,
+but everything inside it speaks the generic *test* vocabulary so future
+test flavours can be added under the same `TestModule` umbrella
+without churn. The `_test` URL prefix's leading underscore signals
+"system-internal, not for production callers".
+
+## Development
+
+```bash
+git clone git@github.com:sprengplatz/viur-testing.git
+cd viur-testing
+pip install -e ".[dev]"
+pytest                  # 100% coverage required
+mkdocs serve            # docs at http://localhost:8000
+```
+
+## Documentation
+
+See [sprengplatz.github.io/viur-testing](https://sprengplatz.github.io/viur-testing/).
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

spltz_viur_testing-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+spltz_viur_testing-0.1.0.dist-info/licenses/LICENSE,sha256=xbdB0-3osMyjq6qSugjP0wbJx20IIMB2w_qj-HhvnXE,1072
+viur/testing/__init__.py,sha256=0olAfnZdCkYJD5fUzKeB6kpdm_bu_YcM5_l2FD2ogQQ,12639
+viur/testing/activation.py,sha256=x7Uo15BjSfbOuzEoYO6Gtj-QHKzH4oLinzUhk2wK0KY,14408
+viur/testing/banner.py,sha256=LDzRLZ2ZLBE4x3Cn3VDcBR7rH7FABgVJDxxnO8ZP7xY,5934
+viur/testing/constants.py,sha256=8n9vqS9k6LYbh7LbRgi4UGZrqmoc9djmd5idpbfNCB8,1561
+viur/testing/protection.py,sha256=zfljUGeM-OGBoiJHSsEi5flIHDAajopNll9_EQa74OQ,1664
+viur/testing/runner.py,sha256=Cd-vzM2z5MD-HeiOppVwFTNp92CGoxHPGLVrBWnouFM,7383
+viur/testing/validator.py,sha256=bkUvBKB0ZmPlpznuRCd8MHZdPM9-oauxUxIaMQjaP5w,4810
+viur/testing/_test/__init__.py,sha256=HFEiBlWmuY4akpf55kqGXv7L7Qo4uvHc0wDg-ermvtc,5990
+viur/testing/_test/config.py,sha256=vG2nRIt174Y3w9W6zTZ55lc6m2FhGnhB3YU7WR5BOkQ,13126
+spltz_viur_testing-0.1.0.dist-info/METADATA,sha256=lAcjL57ksq4reeFJb338nb_9Q2VKzEODX0pT_neI2_k,11905
+spltz_viur_testing-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+spltz_viur_testing-0.1.0.dist-info/top_level.txt,sha256=UpXSoS_clIJYncMZKAppy3WNRScHSjarTabKBOa8OeI,5
+spltz_viur_testing-0.1.0.dist-info/RECORD,,

spltz_viur_testing-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

spltz_viur_testing-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2026 Andreas H. Kelch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spltz_viur_testing-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+viur

viur/testing/__init__.py

@@ -0,0 +1,321 @@
+"""
+viur-testing — safe test-mode for viur-core projects.
+
+The package implements a bilateral guarantee for end-to-end tests
+(typically Playwright): the server refuses to boot unless it is wired
+to a dedicated test database, and the runner refuses to start tests
+unless the server confirms that state back. The session token lives
+only in the test database itself — no on-disk handoff.
+
+Server side
+~~~~~~~~~~~
+
+- :func:`activate` swaps the datastore client to the target test
+  database, runs a synchronous probe roundtrip, primes the in-process
+  state on :class:`~viur.testing._test.config.ConfigModule`, and installs
+  the request validator. Must be called before any ``viur.core``
+  import.
+- :class:`~viur.testing._test.TestModule` is the host-mountable container
+  under ``/_test``. It refuses to instantiate outside a local dev
+  server — the structural last line of defence against an accidental
+  production mount. It carries
+  :class:`~viur.testing._test.config.ConfigModule` as a submodule under
+  ``config``, exposing ``POST /json/_test/config/status`` and
+  ``POST /json/_test/config/finish``.
+- :class:`~viur.testing.validator.TokenValidator` rejects every
+  non-bootstrap request that lacks the matching ``X-Viur-Test-Token``
+  header.
+
+Runner side
+~~~~~~~~~~~
+
+- :func:`require_test_mode` is the preflight check.
+- :func:`finish` tells the server to drop the token entity.
+
+Importing the heavy classes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:class:`TestModule`, :class:`ConfigModule`, :class:`TokenValidator` and
+:class:`ProductionGuardValidator` all inherit from viur-core base
+classes at class-definition time — importing any of them triggers the
+full ``viur.core/__init__.py`` chain, which loads
+``viur.core.db.transport`` and instantiates the default
+``datastore.Client``. That is exactly what :func:`activate` is trying
+to swap *before* it ever runs.
+
+This top-level package therefore deliberately does **not** re-export
+those classes. Import them from their concrete submodules, and only
+*after* :func:`activate` has finished:
+
+- :class:`~viur.testing._test.TestModule` →
+  ``from viur.testing._test import TestModule``
+- :class:`~viur.testing.validator.TokenValidator`,
+  :class:`~viur.testing.validator.ProductionGuardValidator` →
+  used internally by :func:`activate` / :func:`protect`; the host
+  rarely needs to touch them.
+"""
+
+import os as _os
+
+from .activation import activate
+from .constants import DEFAULT_DATABASE, TOKEN_HEADER
+from .protection import protect
+from .runner import ServerStatus, TestModePreflightError, finish, require_test_mode
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_DATABASE",
+    "ServerStatus",
+    "TOKEN_HEADER",
+    "TestModePreflightError",
+    "activate",
+    "finish",
+    "protect",
+    "register_finish_hook",
+    "register_modules",
+    "register_status_hook",
+    "register_test_submodule",
+    "require_test_mode",
+    "setup",
+]
+
+
+def register_status_hook(hook) -> None:
+    """Register a project callback that runs inside ``/_test/config/status``.
+
+    The hook is invoked after the session token has been issued and
+    in-process state primed; if it returns a dict, the entries are
+    merged into the response payload. Use this to inject
+    project-specific configuration that the e2e runner needs to know
+    about (feature flags, generated IDs, seed data references, …).
+
+    Thin wrapper around
+    :meth:`viur.testing._test.config.ConfigModule.register_status_hook`.
+    Typical wiring lives in ``deploy/test/__init__.py``.
+
+    :param hook: ``() -> dict | None`` callable.
+    """
+    from ._test.config import ConfigModule  # noqa: PLC0415
+
+    ConfigModule.register_status_hook(hook)
+
+
+def register_finish_hook(hook) -> None:
+    """Register a project callback that runs inside ``/_test/config/finish``.
+
+    Same shape as :func:`register_status_hook`: optional dict return
+    is merged into the finish response. Useful for cleanup
+    confirmation, summary info, or project-specific shutdown hooks.
+
+    :param hook: ``() -> dict | None`` callable.
+    """
+    from ._test.config import ConfigModule  # noqa: PLC0415
+
+    ConfigModule.register_finish_hook(hook)
+
+
+def register_test_submodule(name: str, module_cls: type) -> None:
+    """Mount a host-provided submodule under ``/_test/<name>/...``.
+
+    Use this to attach project-specific test fixtures (setup,
+    teardown, seed data, …) to the same ``/_test`` container that
+    carries the built-in :class:`~viur.testing._test.config.ConfigModule`.
+
+    Recommended convention: one submodule per e2e spec file, named
+    after the spec — ``tests/auth/userLogin.spec.ts`` ↔ ``/_test/userLogin/``
+    with methods ``setup`` and ``teardown``. This keeps test fixtures
+    co-located with the tests that need them.
+
+    The registration is stored on :class:`~viur.testing._test.TestModule`
+    and consumed at mount time. Call this **before** ``viur.core.setup()``
+    runs — typically right after ``register_modules`` in your host's
+    ``modules/__init__.py``.
+
+    Production-safe: if test mode is not armed (``VIUR_TESTING_ENABLE``
+    unset), ``TestModule`` is never mounted and the registration has
+    no observable effect.
+
+    :param name: URL segment under ``/_test/``. Must not collide with
+        viur-testing's reserved names (currently ``config``).
+    :param module_cls: A ``viur.core.Module`` subclass with the
+        endpoints the test needs.
+    :raises ValueError: when ``name`` is reserved or empty.
+    """
+    from ._test import TestModule  # noqa: PLC0415
+
+    TestModule.register_submodule(name, module_cls)
+
+
+def setup(
+    *,
+    enable_env_var: str = "VIUR_TESTING_ENABLE",
+    database: str = DEFAULT_DATABASE,
+    namespace: str | None = None,
+    namespace_env_var: str = "VIUR_TESTING_NAMESPACE",
+    api_dir: str | None = "testing",
+) -> None:
+    """One-call host-side wiring for ``main.py``.
+
+    Must be the **first** line of code in ``main.py`` — before any
+    ``from viur.core ...`` import. Internally:
+
+    1. Reads ``os.environ[enable_env_var]`` (default
+       ``VIUR_TESTING_ENABLE``). If truthy, calls :func:`activate`
+       which swaps the datastore client to ``database`` (default
+       ``viur-tests``) and the optional ``namespace``, runs the probe
+       and installs the request validator.
+    2. Calls :func:`protect` unconditionally to install the
+       production header guard.
+
+    Namespace resolution: if ``namespace`` is not given to this call,
+    ``os.environ[namespace_env_var]`` is consulted. An empty string is
+    treated as "no namespace" — the host can clear an inherited env
+    var by exporting ``VIUR_TESTING_NAMESPACE=``. This makes it easy
+    to give different testers their own slice of the same
+    ``viur-tests`` database without changing ``main.py``::
+
+        $ VIUR_TESTING_ENABLE=1 VIUR_TESTING_NAMESPACE=ak viur run
+
+    Use the env var, **not** ``conf.instance.is_dev_server``, as the
+    gate — reading ``conf.instance`` triggers the full ``viur.core``
+    import chain (including ``viur.core.db.transport``), which would
+    leave :func:`activate` with no chance to patch the singleton.
+
+    Typical host wiring::
+
+        # main.py
+        import viur.testing
+        viur.testing.setup()
+
+        from viur.core import setup as core_setup
+        import modules, render
+        app = core_setup(modules, render)
+
+    :param enable_env_var: Name of the env var that gates
+        :func:`activate`. Default ``VIUR_TESTING_ENABLE``.
+    :param database: Name of the test database to swap to. Default
+        ``viur-tests``.
+    :param namespace: Optional Datastore namespace. When ``None``, the
+        env var named in ``namespace_env_var`` is consulted as
+        fallback.
+    :param namespace_env_var: Name of the env var to read when
+        ``namespace`` is not given. Default ``VIUR_TESTING_NAMESPACE``.
+    :param api_dir: Name of the wrapper directory (relative to the
+        caller's parent dir) that contains an ``api/`` subfolder
+        with the project test API package. ``setup()`` loads
+        ``<api_dir>/api/__init__.py`` and registers it as the
+        top-level Python package ``api`` via ``importlib`` — no
+        ``sys.path`` manipulation, no sibling-directory exposure.
+
+        Default: ``"testing"`` — resolves to
+        ``<dirname(main.py)>/../testing/api/`` and matches the
+        convention ``testing/api/`` (backend fixtures) +
+        ``testing/e2e/`` (Playwright). Pass any other string to
+        relocate the wrapper, or ``None`` to skip the project
+        test API entirely.
+
+        If the resolved ``__init__.py`` does not exist, a one-line
+        info message is printed and setup continues — that helps
+        spot misconfigurations early (you'd otherwise see mysterious
+        ``404 /_test/<spec>/setup`` errors from the runner side).
+    """
+    if _os.environ.get(enable_env_var):
+        if namespace is None:
+            namespace = _os.environ.get(namespace_env_var) or None
+        activate(database=database, namespace=namespace)
+        if api_dir is not None:
+            _load_project_api(api_dir)
+    protect()
+
+
+def _load_project_api(api_dir: str, caller_file: str | None = None) -> None:
+    """Resolve ``<caller_parent>/<api_dir>/api/__init__.py`` and
+    register it as top-level Python package ``api``.
+
+    The relative path is anchored at the host's ``main.py``; when
+    invoked from :func:`setup` we walk the stack via
+    ``inspect.stack`` to find that file. Tests can pass
+    ``caller_file`` directly to bypass the stack walk.
+
+    :param api_dir: Wrapper directory name (e.g. ``"testing"``).
+    :param caller_file: Override for the host file used to anchor the
+        relative path. When ``None``, walks the call stack.
+    """
+    if caller_file is None:
+        import inspect  # noqa: PLC0415
+        # stack[0]=this fn, stack[1]=setup, stack[2]=caller of setup
+        caller_file = inspect.stack()[2].filename
+    api_init = _os.path.abspath(_os.path.join(
+        _os.path.dirname(caller_file), "..", api_dir, "api", "__init__.py",
+    ))
+    _load_api_package(api_init)
+
+
+def _load_api_package(api_init: str) -> None:
+    """Register the package at ``api_init`` as the top-level Python
+    package ``api``.
+
+    ``api_init`` is the absolute path to an ``__init__.py``. Uses
+    ``importlib.util.spec_from_file_location`` so only the one
+    package is exposed — ``sys.path`` is left untouched. If the file
+    is missing, prints a clear info line and returns; the rest of
+    test-mode setup keeps running.
+    """
+    import importlib.util  # noqa: PLC0415
+    import sys  # noqa: PLC0415
+
+    if not _os.path.isfile(api_init):
+        print(
+            f"[viur-testing] no api package found at {api_init!r} — "
+            "project-specific test fixtures will not be loaded. "
+            "Pass `api_dir=<wrapper>` to viur.testing.setup() pointing "
+            "at a wrapper directory that contains an api/ subfolder.",
+        )
+        return
+
+    spec = importlib.util.spec_from_file_location(
+        "api", api_init,
+        submodule_search_locations=[_os.path.dirname(api_init)],
+    )
+    if spec is None or spec.loader is None:  # pragma: no cover — only happens on a corrupted file system
+        print(f"[viur-testing] could not build import spec for {api_init!r}")
+        return
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["api"] = module
+    spec.loader.exec_module(module)
+    print(f"[viur-testing] loaded project api package from {api_init!r}")
+
+
+def register_modules(target: dict) -> None:
+    """Inject :class:`~viur.testing._test.TestModule` into the host's
+    ``modules/`` namespace if test mode is active.
+
+    Call from ``modules/__init__.py`` after the auto-discovery loop —
+    typically::
+
+        # modules/__init__.py
+        from viur.testing import register_modules
+        register_modules(globals())
+
+    Idempotent: if :func:`activate` has not run (test mode not armed)
+    this is a no-op, so the same line stays in place for both dev and
+    production deployments.
+
+    ``TestModule`` is registered as a **class**, not an instance, so
+    viur-core's ``__build_app`` (which scans ``vars(modules)`` for
+    Module subclasses) picks it up and routes ``/_test/config/*``
+    through it.
+
+    :param target: The ``modules/__init__.py`` global namespace dict,
+        typically ``globals()``.
+    """
+    from ._test.config import ConfigModule  # noqa: PLC0415
+
+    if not ConfigModule.is_active():
+        return  # test mode not armed — nothing to mount
+
+    from ._test import TestModule  # noqa: PLC0415
+
+    target["_test"] = TestModule