wireforge 0.1.0__py3-none-any.whl

wireforge/test_project.py

@@ -0,0 +1,478 @@
+"""Generated GoogleTest project: tests, CMake build, presets, coverage target and analyzer config.
+
+`write_test_project()` writes `<output>/<project>/generated_tests/` next to the generated code of
+`wireforge.generate`. The project builds one test executable per profile (with the profile's
+defines), compiles with the full warning set as errors, offers sanitizer and clang-tidy presets
+and a `coverage` target that fails below a line-coverage threshold, or below 100 percent branch or
+function coverage, of the generated code. The coverage build also writes `<build>/results/` (JUnit
+and CTest results, coverage as JSON and Cobertura, runtime coverage on request, the toolchain) for
+`wireforge docs --results`.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from wireforge import cpp_tests, golden, layout, resources, test_cases, vectors, versioning
+from wireforge.codec import CodecError
+from wireforge.coverage_points import CoveragePointError
+from wireforge.issues import Issue
+
+if TYPE_CHECKING:
+    from wireforge.model import Project
+
+VECTOR_NOTE = (
+    "- `hlr_vector_test.cpp`: the requirement vectors of the model, checked against the values "
+    "written there (not against the reference codec).\n"
+)
+DIRECTORY = "generated_tests"
+DEFAULT_COVERAGE = 100
+RUNTIME_INCLUDE = resources.runtime_include()
+SOURCES = ("golden_test.cpp", "message_test.cpp", "interface_test.cpp")
+VECTOR_SOURCE = "hlr_vector_test.cpp"
+
+CLANG_TIDY = """\
+# Generated by WireForge. Do not edit; regenerate instead.
+Checks: >
+  -*,
+  bugprone-*,
+  cert-*,
+  cppcoreguidelines-*,
+  performance-*,
+  portability-*,
+  misc-*,
+  readability-*,
+  -bugprone-easily-swappable-parameters,
+  -cppcoreguidelines-avoid-magic-numbers,
+  -readability-magic-numbers,
+  -misc-include-cleaner
+WarningsAsErrors: '*'
+HeaderFilterRegex: '.*/{name}/.*'
+"""
+
+CMAKE_HEAD = """\
+# Generated by @TOOL@ from project @NAME@. Do not edit; regenerate instead.
+#
+# Tests of the generated C++ code of @NAME@; see README.md.
+cmake_minimum_required(VERSION 3.21)
+project(@NAME@_generated_tests LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+option(WIREFORGE_WERROR "Treat every warning as an error" ON)
+option(WIREFORGE_COVERAGE "Instrument for coverage and add the coverage target" OFF)
+option(WIREFORGE_CLANG_TIDY "Run clang-tidy on the test sources while building" OFF)
+option(WIREFORGE_COVERAGE_RUNTIME "Include the runtime headers in the coverage report" OFF)
+option(WIREFORGE_FUZZ "Build the libFuzzer targets (Clang only)" OFF)
+set(WIREFORGE_SANITIZE "" CACHE STRING "Sanitizers: address,undefined or thread")
+set(WIREFORGE_COVERAGE_MIN_LINE "@THRESHOLD@" CACHE STRING
+    "Minimum line coverage of the generated code in percent")
+set(WIREFORGE_COVERAGE_MIN_BRANCH "100" CACHE STRING
+    "Minimum branch coverage of the generated code in percent")
+set(WIREFORGE_COVERAGE_MIN_FUNCTION "100" CACHE STRING
+    "Minimum function coverage of the generated code in percent")
+set(WIREFORGE_COVERAGE_RUNTIME_MIN_LINE "100" CACHE STRING
+    "Minimum statement coverage of the runtime headers in percent")
+set(WIREFORGE_RUNTIME_INCLUDE_DIR "@RUNTIME@" CACHE PATH
+    "Directory holding the WireForge runtime headers (wireforge/*.hpp)")
+get_filename_component(WIREFORGE_GENERATED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../.." ABSOLUTE)
+if(NOT EXISTS "${WIREFORGE_RUNTIME_INCLUDE_DIR}/wireforge/status.hpp")
+  message(FATAL_ERROR "Set WIREFORGE_RUNTIME_INCLUDE_DIR to the WireForge runtime/include dir")
+endif()
+"""
+
+CMAKE_MODEL_DIR = """\
+set(WIREFORGE_MODEL_DIR "@MODEL@" CACHE PATH
+    "Directory of the WireForge project (base of user_includes.include_dirs)")
+"""
+
+CMAKE_BODY = """\
+
+# Compiler flags of the WireForge quality policy.
+add_library(wireforge_test_flags INTERFACE)
+if(MSVC)
+  target_compile_options(wireforge_test_flags INTERFACE /W4 /permissive- /Zc:__cplusplus)
+  if(WIREFORGE_WERROR)
+    target_compile_options(wireforge_test_flags INTERFACE /WX)
+  endif()
+else()
+  target_compile_options(wireforge_test_flags INTERFACE
+    -Wall -Wextra -Wpedantic -Wconversion -Wsign-conversion -Wshadow -Wold-style-cast
+    -Wcast-align -Wcast-qual -Wnon-virtual-dtor -Woverloaded-virtual -Wnull-dereference
+    -Wdouble-promotion -Wformat=2 -Wundef -Wunused -Wswitch-enum)
+  if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+    target_compile_options(wireforge_test_flags INTERFACE
+      -Wuseless-cast -Wduplicated-cond -Wduplicated-branches -Wlogical-op)
+  else()
+    target_compile_options(wireforge_test_flags INTERFACE -Wextra-semi -Wimplicit-fallthrough)
+  endif()
+  if(WIREFORGE_WERROR)
+    target_compile_options(wireforge_test_flags INTERFACE -Werror)
+  endif()
+  if(WIREFORGE_SANITIZE)
+    target_compile_options(wireforge_test_flags INTERFACE
+      -fsanitize=${WIREFORGE_SANITIZE} -fno-omit-frame-pointer -fno-sanitize-recover=all)
+    target_link_options(wireforge_test_flags INTERFACE -fsanitize=${WIREFORGE_SANITIZE})
+  endif()
+  if(WIREFORGE_COVERAGE)
+    target_compile_options(wireforge_test_flags INTERFACE --coverage -O0 -g -fstack-usage)
+    target_link_options(wireforge_test_flags INTERFACE --coverage)
+  endif()
+endif()
+
+# The self-test is built like embedded code: no exceptions, no RTTI.
+add_library(wireforge_no_exceptions INTERFACE)
+if(MSVC)
+  target_compile_options(wireforge_no_exceptions INTERFACE /GR-)
+else()
+  target_compile_options(wireforge_no_exceptions INTERFACE -fno-exceptions -fno-rtti)
+endif()
+
+find_package(GTest 1.14 QUIET)
+if(NOT GTest_FOUND)
+  include(FetchContent)
+  set(INSTALL_GTEST OFF CACHE BOOL "" FORCE)
+  set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+  FetchContent_Declare(googletest
+    GIT_REPOSITORY https://github.com/google/googletest.git
+    GIT_TAG v1.14.0
+    GIT_SHALLOW TRUE
+    SYSTEM)
+  FetchContent_MakeAvailable(googletest)
+endif()
+find_package(Threads REQUIRED)
+include(GoogleTest)
+enable_testing()
+
+if(WIREFORGE_FUZZ AND NOT CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+  message(FATAL_ERROR "WIREFORGE_FUZZ needs Clang (libFuzzer)")
+endif()
+
+if(WIREFORGE_CLANG_TIDY)
+  find_program(WIREFORGE_CLANG_TIDY_EXE clang-tidy REQUIRED)
+  set(CMAKE_CXX_CLANG_TIDY ${WIREFORGE_CLANG_TIDY_EXE} --quiet
+      --extra-arg=-Wno-unknown-warning-option)
+endif()
+
+# wireforge_add_profile(<suffix> <definitions...>): tests, differential harness, self-test and fuzz
+# target of one profile (@NAME@_tests<suffix>, _diff, _selftest, _fuzz).
+function(wireforge_add_profile suffix)
+  set(includes ${CMAKE_CURRENT_SOURCE_DIR} ${WIREFORGE_GENERATED_DIR}
+               ${WIREFORGE_RUNTIME_INCLUDE_DIR}@INCLUDES@)
+  set(tests @NAME@_tests${suffix})
+  add_executable(${tests} @SOURCES@)
+  target_include_directories(${tests} PRIVATE ${includes})
+  target_compile_definitions(${tests} PRIVATE ${ARGN})
+  target_link_libraries(${tests} PRIVATE GTest::gtest_main Threads::Threads wireforge_test_flags)
+  gtest_discover_tests(${tests} DISCOVERY_MODE PRE_TEST
+                       XML_OUTPUT_DIR ${CMAKE_BINARY_DIR}/results/junit/${tests})
+  set(diff @NAME@_diff${suffix})
+  add_executable(${diff} diff_harness.cpp)
+  target_include_directories(${diff} PRIVATE ${includes})
+  target_compile_definitions(${diff} PRIVATE ${ARGN})
+  target_link_libraries(${diff} PRIVATE Threads::Threads wireforge_test_flags)
+  set(selftest @NAME@_selftest${suffix})
+  add_executable(${selftest} selftest.cpp)
+  target_include_directories(${selftest} PRIVATE ${includes})
+  target_compile_definitions(${selftest} PRIVATE ${ARGN})
+  target_link_libraries(${selftest} PRIVATE wireforge_test_flags wireforge_no_exceptions)
+  add_test(NAME ${selftest} COMMAND ${selftest})
+  if(WIREFORGE_FUZZ)
+    set(fuzz @NAME@_fuzz${suffix})
+    add_executable(${fuzz} fuzz_target.cpp)
+    target_include_directories(${fuzz} PRIVATE ${includes})
+    target_compile_definitions(${fuzz} PRIVATE ${ARGN})
+    target_compile_options(${fuzz} PRIVATE -fsanitize=fuzzer,address,undefined
+                           -fno-sanitize-recover=all)
+    target_link_options(${fuzz} PRIVATE -fsanitize=fuzzer,address,undefined)
+    target_link_libraries(${fuzz} PRIVATE Threads::Threads wireforge_test_flags)
+  endif()
+endfunction()
+
+@TARGETS@
+if(WIREFORGE_COVERAGE)
+  find_program(WIREFORGE_GCOVR gcovr REQUIRED)
+  if(CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+    set(WIREFORGE_GCOV "llvm-cov gcov" CACHE STRING "gcov command used by gcovr")
+  else()
+    set(WIREFORGE_GCOV "gcov" CACHE STRING "gcov command used by gcovr")
+  endif()
+  # Runs the tests, then reports the line, branch and function coverage of the generated headers
+  # of @NAME@. Headers outside the generated directory (runtime, application) are not part of the
+  # report unless WIREFORGE_COVERAGE_RUNTIME is ON: then a second report measures the statements of
+  # the runtime headers that were compiled into the tests. The machine-readable results are written
+  # to <build>/results (junit/, ctest.xml, coverage.json, coverage_summary.json,
+  # coverage.cobertura.xml, coverage_runtime.json, toolchain.json).
+  set(WIREFORGE_RESULTS_DIR ${CMAKE_BINARY_DIR}/results)
+  set(wireforge_coverage_steps
+    COMMAND ${CMAKE_COMMAND} -E make_directory ${WIREFORGE_RESULTS_DIR}
+    COMMAND ${CMAKE_CTEST_COMMAND} --test-dir ${CMAKE_BINARY_DIR} --output-on-failure
+            --output-junit ${WIREFORGE_RESULTS_DIR}/ctest.xml
+    COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_BINARY_DIR}/coverage
+    COMMAND ${WIREFORGE_GCOVR} --root ${WIREFORGE_GENERATED_DIR}
+            --object-directory ${CMAKE_BINARY_DIR} --gcov-executable ${WIREFORGE_GCOV}
+            --gcov-ignore-errors=source_not_found
+            --filter "@NAME@/model[.]hpp" --filter "@NAME@/interfaces/"
+            --txt --html-details ${CMAKE_BINARY_DIR}/coverage/index.html
+            --json ${WIREFORGE_RESULTS_DIR}/coverage.json
+            --json-summary ${WIREFORGE_RESULTS_DIR}/coverage_summary.json
+            --cobertura ${WIREFORGE_RESULTS_DIR}/coverage.cobertura.xml
+            --fail-under-line ${WIREFORGE_COVERAGE_MIN_LINE}
+            --fail-under-branch ${WIREFORGE_COVERAGE_MIN_BRANCH}
+            --fail-under-function ${WIREFORGE_COVERAGE_MIN_FUNCTION})
+  if(WIREFORGE_COVERAGE_RUNTIME)
+    get_filename_component(wireforge_runtime_abs "${WIREFORGE_RUNTIME_INCLUDE_DIR}" REALPATH)
+    list(APPEND wireforge_coverage_steps
+      COMMAND ${WIREFORGE_GCOVR} --root ${wireforge_runtime_abs}
+              --object-directory ${CMAKE_BINARY_DIR} --gcov-executable ${WIREFORGE_GCOV}
+              --gcov-ignore-errors=source_not_found
+              --filter "${wireforge_runtime_abs}/wireforge/"
+              --json ${WIREFORGE_RESULTS_DIR}/coverage_runtime.json
+              --fail-under-line ${WIREFORGE_COVERAGE_RUNTIME_MIN_LINE})
+  endif()
+  add_custom_target(coverage
+    ${wireforge_coverage_steps}
+    WORKING_DIRECTORY ${WIREFORGE_GENERATED_DIR}
+    DEPENDS @TARGET_NAMES@
+    VERBATIM)
+endif()
+
+# Facts about the toolchain for the lifecycle documents. No path is written: the file must not
+# change when the project moves.
+execute_process(COMMAND ${CMAKE_COMMAND} --version OUTPUT_VARIABLE wireforge_cmake_version
+                OUTPUT_STRIP_TRAILING_WHITESPACE)
+string(REGEX MATCH "[0-9]+[.][0-9]+[.][0-9]+" wireforge_cmake_version "${wireforge_cmake_version}")
+set(wireforge_gcovr_version "not used")
+if(WIREFORGE_COVERAGE)
+  execute_process(COMMAND ${WIREFORGE_GCOVR} --version OUTPUT_VARIABLE wireforge_gcovr_version
+                  OUTPUT_STRIP_TRAILING_WHITESPACE)
+  string(REGEX MATCH "[0-9]+[.][0-9]+([.][0-9]+)?" wireforge_gcovr_version
+         "${wireforge_gcovr_version}")
+endif()
+if(WIREFORGE_COVERAGE_RUNTIME)
+  set(wireforge_runtime_dir "set")
+else()
+  set(wireforge_runtime_dir "default")
+endif()
+get_target_property(wireforge_flag_options wireforge_test_flags INTERFACE_COMPILE_OPTIONS)
+string(REPLACE ";" " " wireforge_flags "${CMAKE_CXX_FLAGS} ${wireforge_flag_options}")
+string(REGEX REPLACE "[$]<[^>]*>" "" wireforge_flags "${wireforge_flags}")
+string(REPLACE "\\"" "'" wireforge_flags "${wireforge_flags}")
+file(WRITE ${CMAKE_BINARY_DIR}/results/toolchain.json
+"{
+  \\"cxx_compiler_id\\": \\"${CMAKE_CXX_COMPILER_ID}\\",
+  \\"cxx_compiler_version\\": \\"${CMAKE_CXX_COMPILER_VERSION}\\",
+  \\"cmake_version\\": \\"${wireforge_cmake_version}\\",
+  \\"gcovr_version\\": \\"${wireforge_gcovr_version}\\",
+  \\"build_type\\": \\"${CMAKE_BUILD_TYPE}\\",
+  \\"coverage\\": \\"${WIREFORGE_COVERAGE}\\",
+  \\"coverage_runtime\\": \\"${WIREFORGE_COVERAGE_RUNTIME}\\",
+  \\"sanitize\\": \\"${WIREFORGE_SANITIZE}\\",
+  \\"runtime_include_dir\\": \\"${wireforge_runtime_dir}\\",
+  \\"cxx_flags\\": \\"${wireforge_flags}\\"
+}
+")
+"""
+
+README = """\
+# Generated tests of {name}
+
+Generated by {tool}. Do not edit; regenerate instead.
+
+GoogleTest suites for the generated C++ code of `{name}`. Every expectation comes from the
+WireForge reference codec:
+
+- `golden_test.cpp`: golden vectors round-trip through `serialize`/`deserialize`, encode to the
+  golden frame and loop back through `Link`, `Endpoint` and the `Handler`;
+- `message_test.cpp`: defaults, minimum/maximum and out-of-range values, empty arrays, invalid enum
+  values and decode errors (wrong checksum, count above the maximum, constants, truncation);
+- `interface_test.cpp`: dispatch of every message, byte-wise delivery, bytes before the sync,
+  corrupted frames and too small buffers.
+{vector_note}
+Profiles are separate executables: {executables}.
+
+```sh
+cmake --preset dev && cmake --build --preset dev && ctest --preset dev
+cmake --preset coverage && cmake --build --preset coverage --target coverage
+cmake --preset asan-ubsan && cmake --build --preset asan-ubsan && ctest --preset asan-ubsan
+cmake --preset clang-tidy && cmake --build --preset clang-tidy
+```
+
+`WIREFORGE_RUNTIME_INCLUDE_DIR` points to the WireForge runtime headers. The `coverage` target
+writes `results/` below the build directory (JUnit, CTest, coverage, toolchain); with
+`WIREFORGE_COVERAGE_RUNTIME=ON` it also measures the runtime headers. The target needs
+gcovr and fails below `WIREFORGE_COVERAGE_MIN_LINE` percent line coverage (default {threshold}) or
+below 100 percent branch and function coverage (`WIREFORGE_COVERAGE_MIN_BRANCH`,
+`WIREFORGE_COVERAGE_MIN_FUNCTION`) of the generated headers. GoogleTest 1.14 is taken from the
+system or downloaded.
+"""
+
+
+def _relative(target: Path, start: Path) -> str:
+    """CMake path of `target`: relative to `start` when they share a directory, else absolute."""
+    target, start = target.resolve(), start.resolve()
+    try:
+        common = Path(os.path.commonpath([target, start]))
+    except ValueError:  # different drives on Windows
+        return target.as_posix()
+    if common == Path(common.anchor):
+        return target.as_posix()
+    return "${CMAKE_CURRENT_SOURCE_DIR}/" + Path(os.path.relpath(target, start)).as_posix()
+
+
+def _profiles(project: Project) -> list[tuple[str, list[str]]]:
+    """Per profile: target name suffix and compile definitions."""
+    if not project.profiles:
+        return [("", [])]
+    result = []
+    for profile in project.profiles.values():
+        definitions = [f"{name}={value}" for name, value in profile.defines.items()]
+        definitions.append(f"WIREFORGE_PROFILE_{profile.name}")
+        result.append((f"_{profile.name}", definitions))
+    return result
+
+
+def executables(project: Project, kind: str) -> list[str]:
+    """Names of the `tests`, `diff` or `fuzz` executables, one per profile."""
+    return [f"{project.name}_{kind}{suffix}" for suffix, _ in _profiles(project)]
+
+
+def _fill(template: str, values: dict[str, str]) -> str:
+    for key, value in values.items():
+        template = template.replace(f"@{key}@", value)
+    return template
+
+
+def sources(project: Project) -> tuple[str, ...]:
+    """Return the test sources of the test executable (the vector test only with vectors)."""
+    return (*SOURCES, VECTOR_SOURCE) if project.vectors else SOURCES
+
+
+def _cmake(project: Project, directory: Path, location: Path, options: TestOptions) -> str:
+    profiles = _profiles(project)
+    values = {
+        "TOOL": f"WireForge {versioning.TOOL_VERSION}",
+        "NAME": project.name,
+        "THRESHOLD": str(options.threshold),
+        "RUNTIME": _relative(options.runtime, directory),
+        "MODEL": _relative(location, directory),
+        "SOURCES": " ".join(sources(project)),
+        "INCLUDES": "".join(
+            f" ${{WIREFORGE_MODEL_DIR}}/{path}" for path, _ in project.include_dirs
+        ),
+        "TARGETS": "".join(
+            f'wireforge_add_profile("{suffix}"{"".join(" " + item for item in definitions)})\n'
+            for suffix, definitions in profiles
+        ),
+        "TARGET_NAMES": " ".join(executables(project, "tests")),
+    }
+    model_dir = CMAKE_MODEL_DIR if project.include_dirs else ""
+    return _fill(CMAKE_HEAD + model_dir + CMAKE_BODY, values)
+
+
+def _presets(project: Project) -> str:
+    variants = {
+        "dev": {},
+        "asan-ubsan": {"WIREFORGE_SANITIZE": "address,undefined"},
+        "tsan": {"WIREFORGE_SANITIZE": "thread"},
+        "coverage": {"WIREFORGE_COVERAGE": "ON"},
+        "clang-tidy": {"WIREFORGE_CLANG_TIDY": "ON"},
+    }
+    configure = [
+        {
+            "name": name,
+            "displayName": f"{project.name} tests ({name})",
+            "binaryDir": f"${{sourceDir}}/build/{name}",
+            "cacheVariables": {"CMAKE_BUILD_TYPE": "Debug", **cache},
+        }
+        for name, cache in variants.items()
+    ]
+    presets = {
+        "version": 3,
+        "cmakeMinimumRequired": {"major": 3, "minor": 21, "patch": 0},
+        "configurePresets": configure,
+        "buildPresets": [{"name": name, "configurePreset": name} for name in variants],
+        "testPresets": [
+            {"name": name, "configurePreset": name, "output": {"outputOnFailure": True}}
+            for name in variants
+        ],
+    }
+    return json.dumps(presets, indent=2) + "\n"
+
+
+@dataclass(frozen=True)
+class TestOptions:
+    """Settings of the generated test project."""
+
+    plugins: Path | None = None
+    runtime: Path = RUNTIME_INCLUDE
+    threshold: int = DEFAULT_COVERAGE
+
+
+def render(
+    project: Project, location: Path, directory: Path, options: TestOptions | None = None
+) -> dict[str, str]:
+    """Files of the test project (name -> content) for a project located at `location`.
+
+    `directory` is where the files will be written; the CMake paths to the runtime headers and the
+    project's include directories are relative to it. Raises CodecError when the reference codec
+    cannot encode the samples (e.g. a custom checksum without plugin).
+    """
+    options = options or TestOptions()
+    plugins = golden.load_plugins(options.plugins) if options.plugins else None
+    golden_vectors = golden.vectors(project, plugins)
+    profiles = test_cases.cases(project, plugins)
+    report = layout.analyze(project)
+    runs = vectors.run(project, plugins)
+    names = ", ".join(f"`{name}`" for name in executables(project, "tests"))
+    tool = f"WireForge {versioning.TOOL_VERSION}"
+    threshold = options.threshold
+    return {
+        "CMakeLists.txt": _cmake(project, directory, location, options),
+        "CMakePresets.json": _presets(project),
+        ".clang-tidy": CLANG_TIDY.format(name=project.name),
+        "README.md": README.format(
+            name=project.name,
+            tool=tool,
+            executables=names,
+            threshold=threshold,
+            vector_note=VECTOR_NOTE if project.vectors else "",
+        ),
+        "test_support.hpp": cpp_tests.SUPPORT_HEADER,
+        "wire_support.hpp": cpp_tests.WIRE_SUPPORT_HEADER,
+        "diff_harness.cpp": cpp_tests.diff_harness_source(project),
+        "fuzz_target.cpp": cpp_tests.fuzz_source(project),
+        "selftest.cpp": cpp_tests.selftest_source(project, golden_vectors, profiles, runs),
+        "handlers.hpp": cpp_tests.handlers_header(project),
+        "golden_test.cpp": cpp_tests.golden_test_source(project, golden_vectors),
+        "message_test.cpp": cpp_tests.message_test_source(project, profiles, report),
+        "interface_test.cpp": cpp_tests.interface_test_source(project, profiles, report),
+    } | (
+        {VECTOR_SOURCE: cpp_tests.hlr_vector_test_source(project, runs)} if project.vectors else {}
+    )
+
+
+def write_test_project(
+    project: Project, location: Path, output: Path, options: TestOptions | None = None
+) -> list[Issue]:
+    """Write `<output>/<project>/generated_tests/`; unchanged files are not rewritten."""
+    directory = output / project.name / DIRECTORY
+    try:
+        files = render(project, location, directory, options)
+    except CodecError as error:
+        return [Issue(str(location), None, "", f"cannot compute the test expectations: {error}")]
+    except CoveragePointError as error:
+        return [Issue(str(location), None, "", str(error))]
+    for name, text in files.items():
+        target = directory / name
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if not target.exists() or target.read_text(encoding="utf-8") != text:
+            target.write_text(text, encoding="utf-8")
+    return []