cocotest 0.1.0__tar.gz

cocotest-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pierre-Louis Nordmann
+
+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.

cocotest-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: cocotest
+Version: 0.1.0
+Summary: Lightweight, opinionated test orchestration framework for cocotb.
+Author: Pierre-Louis Nordmann
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Topic :: Software Development :: Testing
+Requires-Dist: cocotb~=2.0.1
+Requires-Dist: psutil>=7.2.2
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/p-nordmann/cocotest
+Project-URL: Repository, https://github.com/p-nordmann/cocotest
+Project-URL: Issues, https://github.com/p-nordmann/cocotest/issues
+Description-Content-Type: text/markdown
+
+# cocotest
+
+Lightweight, opinionated test orchestration framework for cocotb.
+
+## Quickstart
+
+Cocotest is intended to work in similar fashion to pytest.
+We do not intend to provide as many features as pytest, far from it, but we take a lot of inspiration from it.
+Cocotest should feel familiar for developers with experience in the Python ecosystem.
+
+### Installation
+
+You can install cocotest using pip or uv:
+
+```sh
+pip install cocotest
+
+# Or with uv:
+uv add cocotest
+```
+
+### Getting started
+
+Once cocotest is installed, you can run your tests with the following command:
+
+```sh
+cocotest /path/to/tests
+
+# Or with uv:
+uv run cocotest /path/to/tests
+```
+
+Of course, you need to write your tests in such a way that cocotest knows what to do with them:
+
+```Python
+from cocotb.handle import HierarchyObject
+
+from cocotest import DUTSpec
+
+dut = DUTSpec(
+    simulator="ghdl",
+    sources=["testbench/heartbeat/heartbeat.vhd"],
+    hdl_toplevel="heartbeat",
+    lang="vhdl",
+    build_args=["--std=08"],
+    test_args=["--std=08"],
+)
+
+
+async def test_heartbeat_pass(dut: HierarchyObject):
+    print("Inside test: test_heartbeat_pass")
+    pass
+```
+
+Here there are two important things:
+
+- `dut = DUTSpec(...)`: this is where we tell cocotest about the DUT that we will use, so it knows how to launch cocotb;
+- `async def test_heartbeat_pass(dut: HierarchyObject)`: here we declare a test.
+
+There are 3 conditions for our test to be detected by cocotest:
+
+- `async def`: the test function must be asynchronous, as it will be run inside cocotb and manipulate the DUT;
+- `test_...`: its name must start with "test\_" so cocotest knows how to find it;
+- `dut`: its DUT argument for the cocotb test must have the same name as some `DUTSpec` instance present in the scope. This way, cocotest will know what cocotb test to launch with which DUT.
+
+And... that's it! Just use the `cocotest` command and your test will run.
+No need for fancy makefiles, no need for `@cocotb.test`; you can now define various DUTs to use in various test cases which will be automatically run by cocotest. :)
+
+## Contributing
+
+Before contributing, read [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+Note: contributions are closed for the moment.
+
+## Testing cocotest
+
+Cocotest is made for running cocotb tests, but it must itself be tested so we know it works.
+For this, we rely on good old pytest.
+
+### A word about test dependencies
+
+Most of the tests can be run with the dev dependencies from the uv project.
+However, some tests will try to spawn a cocotest subprocess.
+With this cocotest call, they will try to run ghdl.
+For that reason, you need to install ghdl if you want to be able to run all of the tests.
+
+### Running the tests
+
+Once you have all the dependencies installed, you can run the tests using pytest:
+
+```sh
+pytest tests
+
+# Or with uv:
+uv run pytest tests
+```
+
+## License
+
+This work is distributed under the MIT license, see the LICENSE file for more information.

cocotest-0.1.0/README.md

@@ -0,0 +1,100 @@
+# cocotest
+
+Lightweight, opinionated test orchestration framework for cocotb.
+
+## Quickstart
+
+Cocotest is intended to work in similar fashion to pytest.
+We do not intend to provide as many features as pytest, far from it, but we take a lot of inspiration from it.
+Cocotest should feel familiar for developers with experience in the Python ecosystem.
+
+### Installation
+
+You can install cocotest using pip or uv:
+
+```sh
+pip install cocotest
+
+# Or with uv:
+uv add cocotest
+```
+
+### Getting started
+
+Once cocotest is installed, you can run your tests with the following command:
+
+```sh
+cocotest /path/to/tests
+
+# Or with uv:
+uv run cocotest /path/to/tests
+```
+
+Of course, you need to write your tests in such a way that cocotest knows what to do with them:
+
+```Python
+from cocotb.handle import HierarchyObject
+
+from cocotest import DUTSpec
+
+dut = DUTSpec(
+    simulator="ghdl",
+    sources=["testbench/heartbeat/heartbeat.vhd"],
+    hdl_toplevel="heartbeat",
+    lang="vhdl",
+    build_args=["--std=08"],
+    test_args=["--std=08"],
+)
+
+
+async def test_heartbeat_pass(dut: HierarchyObject):
+    print("Inside test: test_heartbeat_pass")
+    pass
+```
+
+Here there are two important things:
+
+- `dut = DUTSpec(...)`: this is where we tell cocotest about the DUT that we will use, so it knows how to launch cocotb;
+- `async def test_heartbeat_pass(dut: HierarchyObject)`: here we declare a test.
+
+There are 3 conditions for our test to be detected by cocotest:
+
+- `async def`: the test function must be asynchronous, as it will be run inside cocotb and manipulate the DUT;
+- `test_...`: its name must start with "test\_" so cocotest knows how to find it;
+- `dut`: its DUT argument for the cocotb test must have the same name as some `DUTSpec` instance present in the scope. This way, cocotest will know what cocotb test to launch with which DUT.
+
+And... that's it! Just use the `cocotest` command and your test will run.
+No need for fancy makefiles, no need for `@cocotb.test`; you can now define various DUTs to use in various test cases which will be automatically run by cocotest. :)
+
+## Contributing
+
+Before contributing, read [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+Note: contributions are closed for the moment.
+
+## Testing cocotest
+
+Cocotest is made for running cocotb tests, but it must itself be tested so we know it works.
+For this, we rely on good old pytest.
+
+### A word about test dependencies
+
+Most of the tests can be run with the dev dependencies from the uv project.
+However, some tests will try to spawn a cocotest subprocess.
+With this cocotest call, they will try to run ghdl.
+For that reason, you need to install ghdl if you want to be able to run all of the tests.
+
+### Running the tests
+
+Once you have all the dependencies installed, you can run the tests using pytest:
+
+```sh
+pytest tests
+
+# Or with uv:
+uv run pytest tests
+```
+
+## License
+
+This work is distributed under the MIT license, see the LICENSE file for more information.

cocotest-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "cocotest"
+version = "0.1.0"
+description = "Lightweight, opinionated test orchestration framework for cocotb."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Topic :: Software Development :: Testing",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "cocotb~=2.0.1",
+    "psutil>=7.2.2",
+]
+
+[[project.authors]]
+name = "Pierre-Louis Nordmann"
+
+[project.urls]
+Homepage = "https://github.com/p-nordmann/cocotest"
+Repository = "https://github.com/p-nordmann/cocotest"
+Issues = "https://github.com/p-nordmann/cocotest/issues"
+
+[project.scripts]
+cocotest = "cocotest.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.1.1"]
+
+[tool.pytest.ini_options]
+collect_imported_tests = false

cocotest-0.1.0/pyproject.toml.orig

@@ -0,0 +1,34 @@
+[project]
+name = "cocotest"
+version = "0.1.0"
+description = "Lightweight, opinionated test orchestration framework for cocotb."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Pierre-Louis Nordmann" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Topic :: Software Development :: Testing",
+]
+requires-python = ">=3.11"
+dependencies = ["cocotb~=2.0.1", "psutil>=7.2.2"]
+
+[project.urls]
+Homepage = "https://github.com/p-nordmann/cocotest"
+Repository = "https://github.com/p-nordmann/cocotest"
+Issues = "https://github.com/p-nordmann/cocotest/issues"
+
+[project.scripts]
+cocotest = "cocotest.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.1.1"]
+
+[tool.pytest.ini_options]
+# We use the pytest option below to make sure that pytest does not try
+# to interpret Cocotest's TestXxx classes as actual tests.
+collect_imported_tests = false

cocotest-0.1.0/src/cocotest/__init__.py

@@ -0,0 +1,4 @@
+from .core_types import DUTSpec
+from .decorators import mark
+
+__all__ = ["DUTSpec", "mark"]

cocotest-0.1.0/src/cocotest/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

cocotest-0.1.0/src/cocotest/_cocotb_bootstrap.py

@@ -0,0 +1,54 @@
+"""
+This module serves as an entrypoint for cocotb runner.
+
+It makes sure to wrap the target test function into cocotb.test
+"""
+
+import inspect
+import os
+import sys
+
+import cocotb
+from cocotb.handle import HierarchyObject
+
+from .utils import get_module_name, import_from_path
+
+# Retrieve environment variables provided by the runner
+cocotest_import_root = os.environ["COCOTEST_IMPORT_ROOT"]
+module_path = os.environ["COCOTEST_TEST_MODULE"]
+function_name = os.environ["COCOTEST_TEST_FUNCTION"]
+cocotest_cwd = os.environ["COCOTEST_CWD"]
+
+# Make sure to retrieve the expected working directory from the
+# environment variables and change current working directory.
+# Otherwise, we get the current working directory from the simulator,
+# which will most likely not match the expected working directory in
+# the test case.
+# Note: this is important to do that before importing anything dynamically.
+os.chdir(cocotest_cwd)
+
+# Reproduce the same import as cocotest
+sys.path.insert(0, cocotest_import_root)
+module_name = get_module_name(module_path)
+module = import_from_path(module_path, module_name)
+function = getattr(module, function_name)
+
+
+# Wrap the test case into a function marked for cocotb
+# TODO preprocess fixtures here
+@cocotb.test(name=function_name)
+async def test_case(dut: HierarchyObject):
+
+    # Recover the dut name from the function parameters
+    params = inspect.signature(function).parameters
+    if len(params.keys()) != 1:
+        raise AssertionError(f"function {function_name} has too many parameters")
+    dut_name = next(iter(params))
+
+    return await function(**{dut_name: dut})
+
+
+# Hack the module name for display
+module_name_short = os.path.basename(module_path)[:-3]
+test_case.module = module_name_short
+test_case.fullname = f"{module_name_short}.{function_name}"

cocotest-0.1.0/src/cocotest/cli.py

@@ -0,0 +1,109 @@
+import argparse
+import os
+import signal
+import sys
+from contextlib import contextmanager
+from types import FrameType
+from uuid import uuid4
+
+from .decorators import _get_marks
+from .discovery import discover_duts, discover_test_cases, discover_test_modules
+from .execution import ExecutionOptions, run_test
+from .utils import terminate_session
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="cocotest",
+        description="collects and runs cocotb tests",
+    )
+    parser.add_argument(
+        "path",
+        default=".",
+        nargs="?",
+        help="test file or directory",
+    )
+    parser.add_argument(
+        "-m",
+        "--mark",
+        action="append",
+        help="filter tests with the requested mark",
+    )
+    parser.add_argument(
+        "--run-skipped",
+        action="store_true",
+        help="force skipped tests to run",
+    )
+    args = parser.parse_args()
+
+    # Make sure to prepend the current working directory to sys.path
+    sys.path.insert(0, os.getcwd())
+
+    # Discover modules, duts and test cases
+    test_modules = discover_test_modules(args.path)
+    dut_index = discover_duts(test_modules)
+    cases = discover_test_cases(test_modules, dut_index)
+
+    if args.mark is not None:
+        cases = [
+            case
+            for case in cases
+            if any(m in _get_marks(case.function) for m in args.mark)
+        ]
+
+    # We gather execution options for later.
+    options = ExecutionOptions(
+        run_skipped=args.run_skipped,
+    )
+
+    # Note: in the case of some simulators, it seems that SIGINT is ignored by the
+    # subprocesses when cocotb is terminated. This can be painful when developing
+    # testbenches, so we make sure to kill the subprocesses when we receive SIGINT or SIGTERM.
+    with _with_termination_cleanup():
+        # Run test cases and exit with an error code.
+        results = []
+        for case in cases:
+            result = run_test(case, options)
+            print(f"{case.node_id}: {result.status.name}")
+            results.append(result)
+
+        for result in results:
+            if result.is_failure():
+                raise SystemExit(1)
+        raise SystemExit(0)
+
+
+@contextmanager
+def _with_termination_cleanup():
+    """Prepares the environment for running tests and makes sure to terminate
+    subprocesses upon interruption.
+
+    In order to find all the subprocesses that we should kill, we use a trick: we add
+    a COCOTEST_SESSION environment variable before spawning them, so they inherit
+    it automatically. Then, when being terminated, we look for all the processes
+    with the correct COCOTEST_SESSION and kill them.
+
+    Returns an exit code.
+    """
+
+    # We raise a custom exception on SIGINT and SIGTERM
+    class Terminate(Exception):
+        """Used when cocotest is interrupted with SIGTERM or SIGINT."""
+
+    def on_terminate(signum: int, frame: FrameType | None):
+        raise Terminate
+
+    signal.signal(signal.SIGTERM, on_terminate)
+    signal.signal(signal.SIGINT, on_terminate)
+
+    # Here we prepare the environment variable
+    os.environ["COCOTEST_SESSION"] = uuid4().hex
+
+    # Then we wrap the actual logic, except, finally
+    try:
+        yield
+    except Terminate:
+        terminate_session()
+        raise SystemExit(2)
+    finally:
+        os.environ.pop("COCOTEST_SESSION", None)

cocotest-0.1.0/src/cocotest/core_types.py

@@ -0,0 +1,30 @@
+from dataclasses import dataclass
+from types import ModuleType
+from typing import Any, Callable, NamedTuple
+
+
+class TestModule(NamedTuple):
+    module: ModuleType
+    path: str
+
+
+@dataclass
+class DUTSpec:
+    simulator: str
+    sources: list[str]
+    hdl_toplevel: str
+    lang: str
+    build_args: list[str]
+    test_args: list[str]
+
+
+@dataclass(frozen=True)
+class TestCase:
+    module: ModuleType
+    path: str
+    function: Callable[..., Any]
+    dut: DUTSpec
+
+    @property
+    def node_id(self) -> str:
+        return f"{self.path}::{self.function.__name__}"

cocotest-0.1.0/src/cocotest/decorators.py

@@ -0,0 +1,50 @@
+from typing import Awaitable, Callable, ParamSpec, Protocol, TypeVar
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+class _MarkDecorator(Protocol):
+    def __call__(self, fn: Callable[P, Awaitable[T]]) -> Callable[P, Awaitable[T]]: ...
+
+
+def _get_marks(fn: Callable[P, Awaitable[T]]) -> frozenset[str]:
+    marks = getattr(fn, "_cocotest_marks", frozenset())
+    if not isinstance(marks, frozenset):
+        raise ValueError(f"wrong attribute '_cocotest_marks' in '{fn.__name__}'")
+    return marks
+
+
+def _add_mark(fn: Callable[P, Awaitable[T]], mark_name: str):
+    marks = _get_marks(fn)
+    setattr(fn, "_cocotest_marks", marks | {mark_name})
+
+
+class Mark:
+    """Collection of markers."""
+
+    __slots__: tuple[()] = ()
+
+    @staticmethod
+    def skip(fn: Callable[P, Awaitable[T]]) -> Callable[P, Awaitable[T]]:
+        """Notifies cocotest that a test must be skipped."""
+        _add_mark(fn, "skip")
+        return fn
+
+    @staticmethod
+    def xfail(fn: Callable[P, Awaitable[T]]) -> Callable[P, Awaitable[T]]:
+        """Marks a test function as expected to fail."""
+        _add_mark(fn, "xfail")
+        return fn
+
+    def __getattr__(self, name: str) -> _MarkDecorator:
+        """Used for custom marks."""
+
+        def marker(fn: Callable[P, Awaitable[T]]) -> Callable[P, Awaitable[T]]:
+            _add_mark(fn, name)
+            return fn
+
+        return marker
+
+
+mark = Mark()

cocotest-0.1.0/src/cocotest/discovery.py

@@ -0,0 +1,88 @@
+import os
+
+from .core_types import DUTSpec, TestCase, TestModule
+from .errors import DiscoveryError
+from .utils import get_module_name, get_test_dut, import_from_path, is_test_case
+
+ModuleDUTSpecs = dict[str, DUTSpec]
+"""Mapping dut_name->DUTSpec for a single module."""
+
+DUTSpecIndex = dict[str, ModuleDUTSpecs]
+"""Mapping module_name->dut_name->DUTSpec for all modules."""
+
+
+def is_test_file_name(name: str) -> bool:
+    return name.startswith("test_") and name.endswith(".py")
+
+
+def discover_test_files(test_path: str) -> list[str]:
+    """Finds all test files under `test_path`."""
+
+    if not os.path.exists(test_path):
+        raise DiscoveryError(f"test path does not exist: {test_path}")
+
+    if os.path.isfile(test_path) and test_path.endswith(".py"):
+        # In case the user specifies a python file directly,
+        # we consider it a test file in any case.
+        return [test_path]
+
+    if os.path.isfile(test_path):
+        raise DiscoveryError(f"test path is not a python file: {test_path}")
+
+    test_files = []
+    for root, dirs, files in os.walk(test_path):
+        # Note: we make sure that the files are sorted in lexicographic order
+        # by sorting dirs and files here.
+        dirs.sort()
+        files.sort()
+        for name in files:
+            if is_test_file_name(name):
+                test_files.append(os.path.join(root, name))
+
+    return test_files
+
+
+def discover_test_modules(test_path: str) -> list[TestModule]:
+    test_modules: list[TestModule] = []
+    for path in discover_test_files(test_path):
+        module_name = get_module_name(path)
+        module = import_from_path(path, module_name)
+        test_modules.append(TestModule(module, path))
+    return test_modules
+
+
+def discover_duts(test_modules: list[TestModule]) -> DUTSpecIndex:
+    index: DUTSpecIndex = {}
+    for module, path in test_modules:
+        index[module.__name__] = {}
+
+        # Note: we prefer vars(module) to inspect.getmembers(module) because
+        # it preserves module definition/execution order
+        for name, value in vars(module).items():
+            if isinstance(value, DUTSpec):
+                index[module.__name__][name] = value
+    return index
+
+
+def discover_test_cases(
+    test_modules: list[TestModule], dut_index: DUTSpecIndex
+) -> list[TestCase]:
+    cases = []
+    for module, path in test_modules:
+        duts: ModuleDUTSpecs = {}
+        if module.__name__ in dut_index:
+            duts = dut_index[module.__name__]
+
+        # Note: we prefer vars(module) to inspect.getmembers(module) because
+        # it preserves module definition/execution order
+        for name, candidate in vars(module).items():
+            if is_test_case(candidate, module=module, duts=duts):
+                cases.append(
+                    TestCase(
+                        module,
+                        path,
+                        candidate,
+                        get_test_dut(candidate, duts=duts),
+                    )
+                )
+    return cases

cocotest-0.1.0/src/cocotest/errors.py

@@ -0,0 +1,2 @@
+class DiscoveryError(Exception):
+    """Raised when a test module cannot be imported."""

cocotest-0.1.0/src/cocotest/execution.py

@@ -0,0 +1,130 @@
+import os
+from contextlib import contextmanager
+from dataclasses import dataclass
+from enum import StrEnum
+from subprocess import CalledProcessError
+
+from cocotb_tools.runner import get_results, get_runner
+
+from .core_types import TestCase
+from .decorators import _get_marks
+
+
+@dataclass(frozen=True)
+class ExecutionOptions:
+    run_skipped: bool = False
+
+
+class TestStatus(StrEnum):
+    PASS = "pass"
+    FAIL = "fail"
+    BUILD_ERROR = "build_error"
+    RUNTIME_ERROR = "runtime_error"
+    SKIP = "skip"
+    XFAIL = "xfail"
+    XPASS = "xpass"
+
+
+@dataclass(frozen=True)
+class TestResult:
+    status: TestStatus
+    build_log: str | None = None
+    test_log: str | None = None
+
+    def is_failure(self):
+        """Returns True if this result should fail the overall test suite."""
+        return self.status in [
+            TestStatus.FAIL,
+            TestStatus.BUILD_ERROR,
+            TestStatus.RUNTIME_ERROR,
+        ]
+
+
+def run_test(case: TestCase, options: ExecutionOptions | None = None) -> TestResult:
+    if options is None:
+        options = ExecutionOptions()
+    marks = _get_marks(case.function)
+
+    if "skip" in marks and not options.run_skipped:
+        return TestResult(TestStatus.SKIP)
+
+    result = _run_test(case)
+    if "xfail" not in marks:
+        return result
+
+    # In case of xfail, we mark xfail if the test is failure, otherwise xpass.
+    if result.is_failure():
+        return TestResult(TestStatus.XFAIL, result.build_log, result.test_log)
+
+    return TestResult(TestStatus.XPASS, result.build_log, result.test_log)
+
+
+def _run_test(case: TestCase) -> TestResult:
+    build_dir = os.path.join(
+        ".cocotest_cache", case.module.__name__, case.function.__name__
+    )  # TODO: one build dir per dut?
+
+    # cocotb Runner changes its failure semantics when PYTEST_CURRENT_TEST
+    # is present: failed cocotb tests cause SystemExit instead of returning
+    # the results XML. Cocotest needs consistent runner semantics regardless
+    # of whether its caller happens to be pytest.
+    with _without_pytest_context():
+        runner = get_runner(case.dut.simulator)
+
+        try:
+            runner.build(
+                hdl_library="work",
+                sources=case.dut.sources,
+                build_args=case.dut.build_args,
+                hdl_toplevel=case.dut.hdl_toplevel,
+                build_dir=build_dir,
+                log_file=os.path.join(build_dir, "build_logs.log"),
+            )
+        except CalledProcessError:
+            return TestResult(
+                TestStatus.BUILD_ERROR, os.path.join(build_dir, "build_logs.log")
+            )
+
+        try:
+            results_path = runner.test(
+                test_module="cocotest._cocotb_bootstrap",
+                hdl_toplevel=case.dut.hdl_toplevel,
+                hdl_toplevel_library="work",
+                hdl_toplevel_lang=case.dut.lang,
+                test_args=case.dut.test_args,
+                extra_env={
+                    "COCOTEST_IMPORT_ROOT": os.getcwd(),
+                    "COCOTEST_TEST_MODULE": os.path.abspath(case.path),
+                    "COCOTEST_TEST_FUNCTION": case.function.__name__,
+                    "COCOTEST_CWD": os.getcwd(),
+                },
+                build_dir=build_dir,
+                test_dir=build_dir,  # WARNING: must be the same as build_dir
+                test_filter=f"\.{case.function.__name__}$",
+                log_file=os.path.join(build_dir, "test_logs.log"),
+            )
+        except SystemExit:
+            return TestResult(
+                TestStatus.RUNTIME_ERROR,
+                os.path.join(build_dir, "build_logs.log"),
+                os.path.join(build_dir, "test_logs.log"),
+            )
+
+        total, failures = get_results(results_path)
+
+    return TestResult(
+        TestStatus.PASS if failures == 0 else TestStatus.FAIL,
+        os.path.join(build_dir, "build_logs.log"),
+        os.path.join(build_dir, "test_logs.log"),
+    )
+
+
+@contextmanager
+def _without_pytest_context():
+    """Temporarily suppresses pytest's PYTEST_CURRENT_TEST env variable."""
+    value = os.environ.pop("PYTEST_CURRENT_TEST", None)
+    try:
+        yield
+    finally:
+        if value is not None:
+            os.environ["PYTEST_CURRENT_TEST"] = value

cocotest-0.1.0/src/cocotest/utils.py

@@ -0,0 +1,110 @@
+import hashlib
+import inspect
+import os
+import sys
+import warnings
+from importlib.util import module_from_spec, spec_from_file_location
+from types import FunctionType, ModuleType
+from typing import Any
+
+import psutil
+
+from .core_types import DUTSpec
+from .errors import DiscoveryError
+
+
+def import_from_path(path: str, module_name: str) -> ModuleType:
+    spec = spec_from_file_location(module_name, path)
+    if spec is None:
+        raise DiscoveryError(f"failed to import {module_name}")
+    module = module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def get_module_name(path: str) -> str:
+    absolute_path = os.path.abspath(path)
+    digest = hashlib.sha1(absolute_path.encode()).hexdigest()[:12]
+
+    file_name = os.path.basename(path)
+    base_name = file_name[:-3]  # .py
+
+    return f"cocotest_{base_name}_{digest}"
+
+
+def is_test_case(
+    candidate: Any, *, module: ModuleType, duts: dict[str, DUTSpec]
+) -> bool:
+    if not inspect.iscoroutinefunction(candidate):
+        return False
+    if candidate.__module__ != module.__name__:
+        return False
+    if not candidate.__name__.startswith("test_"):
+        return False
+
+    params = inspect.signature(candidate).parameters
+    dut_params_count = 0
+    other_params_count = 0
+    for name in params:
+        if name in duts:
+            dut_params_count += 1
+        else:
+            other_params_count += 1
+
+    filename = inspect.getsourcefile(candidate) or ""
+    _, lineno = inspect.getsourcelines(candidate)
+
+    if dut_params_count == 0:
+        if other_params_count > 0:
+            warnings.warn_explicit(
+                f"function {candidate.__name__} looks like a test case but has no dut parameter. Is it a typo?",
+                UserWarning,
+                filename=filename,
+                lineno=lineno,
+            )
+        return False
+    if dut_params_count > 1:
+        warnings.warn_explicit(
+            f"test case {candidate.__name__} has {dut_params_count} dut parameters",
+            UserWarning,
+            filename=filename,
+            lineno=lineno,
+        )
+        return False
+    if other_params_count > 0:
+        warnings.warn_explicit(
+            f"test case {candidate.__name__} has {other_params_count} non-dut parameters",
+            UserWarning,
+            filename=filename,
+            lineno=lineno,
+        )
+        return False
+
+    return True
+
+
+def get_test_dut(fx: FunctionType, *, duts: dict[str, DUTSpec]) -> DUTSpec:
+    params = inspect.signature(fx).parameters
+    for name in params:
+        if name in duts:
+            return duts[name]
+    raise RuntimeError("dut not found")
+
+
+def terminate_session():
+    """Kills all the processes of the current cocotest session.
+
+    Heavily inspired by the "Kill process tree" example from psutil's documentation.
+    """
+    if "COCOTEST_SESSION" not in os.environ or os.environ["COCOTEST_SESSION"] is None:
+        return
+
+    for p in psutil.process_iter():
+        if p.pid == os.getpid():
+            continue
+        try:
+            if p.environ().get("COCOTEST_SESSION") == os.environ["COCOTEST_SESSION"]:
+                p.kill()
+        except (psutil.NoSuchProcess, psutil.AccessDenied):
+            pass