Settings¶
LangAdapter reads no configuration file of its own. A run is configured by the objects
you pass to it, by the project settings of its language and by a few
environment variables. The API reference
describes the request objects, such as SuiteRunRequest, field by field.
Project settings¶
Each adapter declares the settings a project of its language takes
(project_settings), each with its purpose, kind and default. A program
that uses LangAdapter asks for them, for example with the adapter's
setup_questions, and passes the values to two class methods before it
builds the project context. discover_runtime selects the runtime, its
interpreter flags and the test framework configuration (RuntimeChoice),
and context_environment gives the variables of the context's
environment. An empty value leaves a setting to the adapter's discovery.
C projects lists the C adapter's settings.
Python settings¶
| Setting | What |
|---|---|
python_executable |
the project's Python interpreter. Empty: the environment uv provisions for python_version, else the project's only environment, as Environment selection describes |
python_version |
a Python version, such as 3.12, for which uv provisions an environment when python_executable is empty |
requirements |
the requirements file of the environment that python_version provisions |
python_import_root |
the directory below the project that its package is imported from, such as src, given to the runs as LANGADAPTER_PYTHON_IMPORT_ROOT. Empty: the project directory |
python_test_environment |
variables every process of the adapter's runs gets, as NAME=value words, such as PURE_PYTHON=1 |
frozen_module_strategy |
unfreeze, the default, runs the project's Python with -X frozen_modules=off, so coverage and mutation treat the standard library's frozen modules as ordinary files. skip leaves them frozen |
pytest_config |
auto, the default, uses the project's own pytest configuration. A path selects a configuration file, and none runs pytest with its defaults, as Test framework configuration describes |
Java settings¶
| Setting | What |
|---|---|
java_home |
the project's JDK: its home or its java executable. Empty: JAVA_HOME, except in a container, where it must be named |
build_java_home |
the JDK the build tool runs on when it needs a newer Java than the project's, such as Gradle 9, which runs on Java 17 or newer. Empty: java_home. The runs get it as LANGADAPTER_BUILD_JAVA_HOME |
maven |
the Maven launcher, when the project has no Maven wrapper. Empty: mvn on the path. The runs get it as LANGADAPTER_MAVEN |
gradle |
the Gradle launcher, when the project has no Gradle wrapper. Empty: gradle on the path. The runs get it as LANGADAPTER_GRADLE |
The adapters' project_settings entries in the
Python
and Java
references list the same settings.
Environment variables¶
Java projects¶
Set these in ProjectContext.environment, which is where the Java adapter
looks for them. LANGADAPTER_JAVA_TOOLS and LANGADAPTER_JAVA_TOOLS_OFFLINE
are also read from the calling process's environment when the context lacks
them, unless its environment is captured
(Environment(..., inherit=False)). A captured environment's default cache
lies below its own HOME, or USERPROFILE on Windows. In a container they
are read on the host, where the tool cache stays: from
ContainerExecution.control_environment when it is set, else from the
calling process's environment, never from the context's environment.
| Variable | Default | Effect |
|---|---|---|
LANGADAPTER_MAVEN |
mvn on the path |
The Maven launcher, for a Maven project without its own mvnw wrapper. |
LANGADAPTER_GRADLE |
gradle on the path |
The Gradle launcher, for a Gradle project without its own gradlew wrapper. |
LANGADAPTER_BUILD_JAVA_HOME |
The interpreter's JDK | The JDK that runs the project's build, when the build needs another JDK than the one that runs the tests. |
LANGADAPTER_JAVA_TOOLS |
~/.cache/langadapter/java |
The tool cache for the jars LangAdapter downloads: the JUnit launcher, JaCoCo and PIT. |
LANGADAPTER_JAVA_TOOLS_OFFLINE |
Unset | 1, true, yes or on forbids downloads. A jar missing from the cache is then unavailable, and a setup check reports it as missing setup. |
C projects¶
The C adapter reads its settings from ProjectContext.environment, as the
variables LANGADAPTER_C_TESTS, LANGADAPTER_C_COMPILER and the others
that C projects lists with each setting.
Python projects¶
| Variable | Default | Effect |
|---|---|---|
LANGADAPTER_PYTHON_IMPORT_ROOT |
Unset: the project directory | The directory below the project root that the project's package is imported from, such as src. The adapter reads it from ProjectContext.environment, not from the calling process's environment. |
Diagnostics of Python runs¶
These change only what a run records about itself, never a verdict. They are
read from the calling process's environment, which the runs LangAdapter
starts for Python tests inherit. The two descriptor watchers need Linux's
/proc and write a histogram of what the open descriptors point to, as
fdleak_<pid>.txt.
| Variable | Default | Effect |
|---|---|---|
LANGADAPTER_MUTATION_DIAG_TB |
no |
pytest's --tb level for every mutant's test run in a Cosmic Ray session. short or line keeps a failing test's traceback in the run's output, which CosmicRaySettings.keep_output stores. |
LANGADAPTER_FDLIMIT_DEBUG |
Unset | Any value makes each mutant's run on a POSIX host print its open-file limits before and after they are raised. In a suite that prepare_suite set up, it also starts a watcher thread in the test process, which writes its file once the process holds LANGADAPTER_FDLEAK_THRESHOLD descriptors. |
LANGADAPTER_FDLEAK_THRESHOLD |
3000 |
The descriptor count at which the watcher thread of LANGADAPTER_FDLIMIT_DEBUG writes its file. |
LANGADAPTER_FDLEAK_WATCH |
Unset | Any value makes each mutant's run on a POSIX host start a watcher outside the interpreter, which writes its file once the run holds more than 3000 descriptors. |
LANGADAPTER_FDLEAK_DIR |
LANGADAPTER_PROJECT_WORKZONE, else the run's directory |
Where both watchers write their files. Unset, they write to the directory LANGADAPTER_PROJECT_WORKZONE names when it is set. In a Cosmic Ray run the run's directory is a worker's copy of the project, whose next run removes the files earlier runs left there, so set it to keep the files. |
Mutation sessions¶
adapter.mutations.open_session(engine, **options) opens a session. The
options are:
| Option | Default | Effect |
|---|---|---|
workers |
1 |
How many mutants run at once. |
distributor |
auto (Cosmic Ray only) |
local runs one mutant at a time in one process, http runs a fleet of worker processes with a copy of the project each, and auto picks local for one worker and http for more. An explicit http starts as many workers as workers names, one included. local with more than one worker is refused, never run with one. |
allow_fewer_workers |
False (Cosmic Ray only) |
Lets a session open when fewer workers than requested start, instead of refusing it. |
settings |
CosmicRaySettings() (Cosmic Ray only) |
The engine's own settings, below. |
A PIT session takes workers only.
Cosmic Ray settings¶
langadapter.python.cosmic_ray.CosmicRaySettings holds the settings of the
Cosmic Ray engine. Every field has a default, and its
reference entry
lists the same fields.
| Field | Default | Effect |
|---|---|---|
init_timeout_s |
600 |
Seconds cosmic-ray init may take to build the mutant catalogue. |
worker_ready_timeout_s |
60 |
Seconds to wait for the HTTP workers to come up. |
catalogue_cache_dir |
Unset | An absolute directory for a cache of mutant catalogues, keyed by the target's content, so a run of an unchanged target skips cosmic-ray init. Unset: no cache. |
cache_max_entries |
200 |
The most catalogues the cache keeps. The oldest go first. |
cache_max_age_days |
0 |
Catalogues older than this many days are removed. 0 keeps them regardless of age. |
clone_dir |
Node-local storage | Where the HTTP workers' copies of the project go. Unset: /dev/shm (on POSIX), else the system's temporary directory, each only when it is writable with at least 1 GiB free, else the directory the caller runs in. |
clone_sweep_hours |
12 |
Worker copies and per-run directories that a killed run left behind are removed at a session's start once they are older than this. 0 turns the sweep off. |
session_dir |
A new temporary directory | The directory of a local run's session database. Cosmic Ray writes the database once per mutant, so keep it on local storage, never on a network file system. |
local_session_dir |
Unset | The node-local directory for the live session database. A container run keeps it there, else in memory-backed storage, else in the temporary directory. A local run without session_dir makes its own directory below it, or in the temporary directory when this is unset. A directory that cannot be made, or in which no directory can be made, refuses the run: the database never moves elsewhere. |
progress_interval_s |
0 |
Seconds between progress lines in the log. 0 writes none. |
per_file_adjudication |
True |
Re-measures, file by file, the kills whose verification left them unresolved. |
keep_output |
False |
Keeps each mutant's test output in its kill-matrix row. The output can be large. |
verbose |
False |
Runs Cosmic Ray's execution with its informational log, for runs on the host. |
log |
Unset | A function that receives the engine's log lines, as log(message, level). |
Test runs¶
pytest options¶
SuiteRunRequest.runner_options takes a
langadapter.python.project.PytestOptions
for a Python suite:
| Field | Default | Effect |
|---|---|---|
traceback |
short |
pytest's --tb style. |
stop_at_first_failure |
False |
Stops the run at the first failing test (pytest's -x). |
disabled_plugins |
() |
pytest plugins to turn off (pytest's -p no:<name>). |
leave_out_timing_plugins |
False |
Leaves out the plugins that change a run's time where the project's pytest loads them: pytest-cov's tracer (--no-cov), pytest-xdist's workers (-n 0) and pytest-benchmark's measurement (--benchmark-disable). The project's own options for them stay valid, a benchmark test runs its function once and saves no data, and a project whose addopts hold --benchmark-only is refused by pytest-benchmark. |
pytest-benchmark looks up the project's version control at every pytest
start, before --benchmark-disable applies, so each run, probe and
collection pays that time. Leave the plugin out of the project's
environment where an operation's time matters.
Test framework configuration¶
ProjectContext.test_framework takes a
TestFrameworkConfig:
| Field | Default | Effect |
|---|---|---|
source |
project |
project runs the test framework with the project's own configuration, found in the framework's own order. isolated runs it with the framework's defaults. |
path |
Unset | With source="project", the configuration file to use instead of the one the framework would find. |
The Java adapter takes only the default, the project's own configuration:
isolated or a path makes its operations unsupported.