C¶
langadapter.c.adapter ¶
The C adapter: a project's C file, tested by tests of four kinds, measured with gcov.
A run builds the target from the project's recorded build, compiles each test file into a program linked with that build, and runs each program whole, as delivered. Coverage comes from gcov's record of the target alone, and mutants from Mull. The project's own tree is never built in.
Its tests are of one of four kinds (c_tests):
c: utest.h tests, each test file a program linked with the target.python: Python 3 tests of a target built into a Python extension, discovered from the project's build.programs: the project's own test programs, each judged by its exit status.ctest: a CMake project's tests as ctest runs them.
With the three kinds of C tests the project's runtime is its GCC. With
Python tests it is the project's Python,
whose tests LangAdapter's Python adapter runs: the facts,
words and source operations of those tests are Python's, the build, coverage
and mutants C's. The settings a project declares reach the adapter as
variables of the project context (context_environment).
CAdapter ¶
CAdapter(context: ProjectContext)
Bases: LangAdapter
C projects: the project's GCC build replayed for the target, its tests
of the kind c_tests names (utest.h tests, Python tests of an
extension, the project's own programs or ctest's tests), gcov coverage.
runtime
class-attribute
instance-attribute
¶
runtime = 'gcc'
The program that builds and so runs the tests: the project's GCC.
source_merge_separator
class-attribute
instance-attribute
¶
source_merge_separator = '//'
The comment a merge's separator line starts with.
test_evidence_granularity
class-attribute
instance-attribute
¶
test_evidence_granularity = (('run_suite', ('aggregate', 'per_test')), ('per_test_evidence', ('per_test',)))
native_mutation_engines
class-attribute
instance-attribute
¶
native_mutation_engines = (_mull.ENGINE,)
mutation_evidence_granularity
class-attribute
instance-attribute
¶
mutation_evidence_granularity = ('aggregate', 'per_mutant', 'per_test')
project_settings
class-attribute
instance-attribute
¶
project_settings = (ProjectSetting('c_tests', "The kind of the project's tests: c (utest.h tests), python (Python tests of a target built into a Python extension), programs (the project's own test programs, each judged by its exit status) or ctest (a CMake project's tests as ctest runs them).", 'choice', choices=_TEST_KINDS), ProjectSetting('c_compiler', "The GCC that builds the project's C code and its tests.", 'executable', alias='CC'), ProjectSetting('c_build_kind', 'How the project builds: make (its Makefile, run in a copy of the project), cmake (its CMakeLists.txt, built outside its tree), configure, setuptools, or flags (one file, with c_flags and c_link).', 'choice', choices=_build.KINDS), ProjectSetting('c_build', 'The command that builds the project in its copy, when not plain make. For a CMake project it holds the options of its configure step (-DNAME=VALUE).', 'text'), ProjectSetting('c_flags', 'The compile flags of the target, for a project without a build file.', 'text'), ProjectSetting('c_link', 'The objects, libraries and C sources (also patterns, such as src/*.c) the target links with, for a project without a build file.', 'text'), ProjectSetting('c_build_cache', 'A directory that keeps a configure build for later runs, instead of building once per adapter.', 'path'), ProjectSetting('c_target', 'The C file the tests are for, when a request does not name it. Load repair and import pruning compile against it.', 'path'), ProjectSetting('c_mull', "Mull's runner (mull-runner-N), whose IR frontend and clang N build the target's mutants.", 'executable'), ProjectSetting('c_test_prelude', "The headers every test file includes first, as the project's own tests include them (such as stdlib.h test/alloc-testing.h), each passed as -include.", 'text'), ProjectSetting('c_ctest_arguments', 'Extra arguments for named ctest tests (c_tests ctest), given after their own. The entries are separated by semicolons, each a test name followed by its arguments, such as fuzz_test {seed}. The value of {seed} is 1, since a C run carries no session seed.', 'text'), ProjectSetting('c_test_support', "The sources the project's own test programs build with besides the target (c_tests programs), such as test/framework.c test/alloc-testing.c. They are the suite's setup files.", 'text'), ProjectSetting('c_test_environment', "Variables every process of the C adapter's runs gets, Python tests of the target's extension among them, as NAME=value words such as CK_FORK=no.", 'text', check='NAME=value words'), ProjectSetting('c_address_space_limit', 'The most address space each test process may reserve (RLIMIT_AS, set with prlimit), such as 2G or a number of bytes. Empty: no limit.', 'text', check='a size such as 2G'), *(declared for declared in PythonAdapter.project_settings if declared.name != 'python_test_environment'))
collection_unit
class-attribute
instance-attribute
¶
collection_unit = 'the utest.h test, fixture block or top-level declaration around a line GCC reports an error on'
The unit load repair removes.
seeds_delivered_runs
instance-attribute
¶
seeds_delivered_runs = self._python().seeds_delivered_runs
test_vocabulary ¶
test_vocabulary() -> Dict[str, str]
C's words for its tests, and for Python tests Python's words with
the import and validity rules of an extension. A project's own programs
and ctest's tests
are measured, not generated: for those kinds the words are refused
(InvalidRequest on c_tests), so generation stops at its start.
language_facts ¶
language_facts() -> la.LanguageFacts
The facts of C tests: utest.h, the c fence and GNU C17, the
language every test file compiles as. For Python tests, Python's, with
python as the tests' language and c as the target's fence.
import_statement
classmethod
¶
import_statement(target: str, root: str) -> Optional[str]
The import of the target's module when setup.py builds the
target into an extension, else #include "<stem>.h" when a header
of its stem lies beside it, else None.
test_id_text ¶
test_id_text(test) -> str
file::set.name, with /index for an indexed test. Python
tests have Python's dotted id.
discover_runtime
classmethod
¶
discover_runtime(root, values, *, container=False, environment=None, resolve_path=None) -> RuntimeChoice
The project's GCC: c_compiler, else CC, else cc or gcc
on PATH. For Python tests, the project's Python as the Python adapter
finds it.
setup_questions
classmethod
¶
setup_questions(project_dir, probe, *, consumer='the caller')
C's own settings, each asked as by default. For a project whose tests are Python's (a target built into an extension), Python's own questions follow C's. They choose the Python that runs those tests. The Python settings C declares for that case are Python's to ask.
setup_problem
classmethod
¶
setup_problem(setting, value, project_dir, probe)
Python's check for the Python settings C declares, C's own by their kind (the default), and c_address_space_limit's size.
context_environment
classmethod
¶
context_environment(values, *, container=False) -> Dict[str, str]
The C settings as the context variables the adapter reads, with
Python's import root for Python tests of the target's extension, and
the variables c_test_environment gives its runs' processes, Python
tests of the extension among them. The import root, the setting
python_import_root, follows Python's rule: a directory outside the
project is refused, and . or none, the project itself, stays a choice
apart from no setting. Without a setting the adapter takes the directory setup.py's
extensions are built in below their package, else src when a package
lies below it, else the project itself. C does not declare Python's
python_test_environment, which is the Python adapter's alone.
request_options ¶
request_options(purpose: str, *, target: Optional[str] = None, traceback: str = 'short', stop_at_first_failure: bool = False, record_leaks: bool = False, session_seed: Optional[int] = None, reverse_order: bool = False, leave_out_timing_plugins: bool = False) -> Dict[str, Any]
The run's target as CRunOptions: the tests are linked with it.
A target inside the project is named by its path relative to the
project, so the options hold in a copy of it (a consumer's prepared
copy). For Python tests, the Python adapter's fields of the run, its
runner options carried inside. C tests have no timing plugins to
leave out.
execution_setup_issue ¶
execution_setup_issue() -> str
A system other than Linux, a module of LangAdapter's extra for C
that is not installed, a c_address_space_limit that does not
parse or finds no prlimit on PATH, or utest.h tests without stdbuf on
PATH, which a suite run and a run as delivered start each test
program under, or "".
inspect_project ¶
inspect_project(request)
The compiler and its gcov, started for their versions, and the
extra's modules, stdbuf, prlimit and Mull found (_setup). Off Linux
the system's refusal.
verify_project ¶
verify_project(request)
The inspection's items with each tool it found started once
(_setup).
project ¶
project() -> ProjectResolution
Whether the project builds: its build kind is known and the compiler runs. The build itself is recorded on the first run.
run_suite ¶
run_suite(request: SuiteRunRequest) -> SuiteRun
Run the suite against a build of the target, with the target's
coverage when coverage_target names it. A utest.h test file's
program runs whole, as delivered, and starts again without a test
that crashed. A project's own programs and ctest's tests run each
test in its own process. Python tests run in one pytest process
against the target's extension.
benchmark ¶
benchmark(request: BenchmarkRequest) -> Benchmark
The times of repeated runs of the suite after discarded warm-up runs, the target and the tests built once before them: each test program runs once a repetition, all its tests in one process. ctest's tests each run as a suite run runs them. Python tests are timed by the Python adapter, with the target's extension staged.
run_as_delivered ¶
run_as_delivered(request: SuiteRunRequest, *, sources: Optional[Mapping[str, str]] = None) -> SuiteRun
Each test file alone, as a user who copied it runs it: built
without counters, its program run once by utest.h's own main, all its
tests in one process in their order of definition.
A crash or the timeout ends the program in the test it ran, and the
tests after it have no outcome. A project's own program, or ctest's
test, is one program run whole, so it runs as in a suite run.
sources replaces a test file's text, compiled from a copy that
includes as the file does. Python tests of an extension: Python's run
as delivered.
delivered_order_refusal ¶
delivered_order_refusal(reverse: bool) -> Optional[str]
Why a run as delivered in the reverse order is refused for C tests: a test program runs its tests in its own order. Python tests of an extension: Python's answer.
coverage_texts ¶
coverage_texts(coverage) -> Dict[str, Tuple[Any, ...]]
The covered lines, and per line the untaken branches gcov counts
("line->k of n branches untaken"), as Java's adapter writes them.
per_test_evidence ¶
per_test_evidence(request: PerTestEvidenceRequest) -> PerTestEvidence
Each test's own coverage of the target: the process that ran the test alone wrote its own counters. With a mutation run, the mutants each test kills. A suite that is not green carries no evidence. Python tests write their counters per test inside one process.
test_units ¶
test_units(source: str)
Each utest.h test of source with its span in characters, or None
when the file does not parse. An indexed test is one unit. An adapter
with Python tests has no units: Python's own operations find and
remove its tests.
prune_tests ¶
prune_tests(source: str, tests)
source without the named tests, each named by its unit
(set.name) or by an id: file::set.name, with /index or a
case's [params] after it (test_id_text, a consumer's case
id). A TestId is named by its id text. An indexed test's id removes
its whole UTEST_I block, every index of it, since one index is
no unit of its own, and the detail says so. A name that matches
nothing is reported as named, a TestId by its qualname, as Python
and Java report it.
validate_source ¶
validate_source(source: str) -> SourceValidation
Whether source parses as C, utest.h's macros read as the
declarations they expand to, with the first error's place. Python
tests: as the project's Python parses them.
finalize_source ¶
finalize_source(source: str)
source with UTEST_MAIN() appended when it has utest.h tests
and no main, as a reply cut off after its last test lacks it
(SourceResult). Python tests: Python's.
merge_sources ¶
merge_sources(first: str, second: str, *, separator: str)
The second test file folded into the first: the
first as it is, after the separator line the second's items, the
names both declare shared or renamed, then one UTEST_MAIN().
Refused when the merge does not parse, loses a test or leaves two of
one name (SourceResult).
salvage_syntax ¶
salvage_syntax(source: str)
A repair of a test file the parser rejects, in at most 25 rounds
(templates.repair_syntax): a token the parser finds missing (;,
a closing bracket or brace) is inserted where it is missing, any
other error blanks its line. unchanged when it parses,
applied when repairs made it parse, else not_repaired.
strip_module_level_skips ¶
strip_module_level_skips(source: str)
source as it is (unchanged), or parse_error when it does
not parse. Python's rule removes only the statements outside any test
that skip the whole file, and utest.h has none. Its UTEST_SKIP stands
in a test or a fixture's setup and skips that test or that fixture's
tests, as a skip in a Python test or fixture does, which the rule keeps.
structural_parser_identity ¶
structural_parser_identity() -> str
tree-sitter-c's and lizard's versions. With Python tests, Python's parser, which reads the tests, and C's, which reads the target.
optimization_metrics ¶
optimization_metrics(source: str) -> Dict[str, Any]
The eight structural counters of a C source, each None when it does not parse. The target's are C's, also with Python tests.
skeleton ¶
skeleton(source: str) -> Tuple[str, ...]
The names of a C source's functions, utest.h tests and fixture blocks in source order, () when it does not parse.
same_skeleton ¶
same_skeleton(first: str, second: str) -> Tuple[bool, str]
Whether two C sources define the same functions in the same order, and why not.
function_fingerprints ¶
function_fingerprints(source: str) -> Dict[str, str]
Each function's, test's and fixture block's fingerprint by its name, the same whatever the layout and comments.
stage_pool ¶
stage_pool(members: Any, *, setup: Any = ()) -> Any
Several suites' C test files as one pool, each file named for its
suite. ctest's tests are its CMake project's, which does
not pool: the operations layer refuses it (operation_context_issue).
Python tests of an extension: Python's.
operation_context_issue ¶
operation_context_issue(name: str) -> str
Why name cannot run for these tests: ctest's tests do not
pool, which the operation report says.
target_identity ¶
target_identity(target: str)
The TargetIdentity of a C file under test for the validity
policy. Raises InvalidRequest for a missing file or one outside
the project. For Python tests, the identity Python's policy takes: the
extension's module and the C file's path and text. Its version is
Python's (PythonAdapter.validity_policy_version) followed by the
name of the rules for a test that reads or copies the C file.
analyze_validity ¶
analyze_validity(source: str, target)
The validity policy's findings on a C test source for target
(PolicyReport): reading, copying or redefining the target. Python
tests: Python's findings for the extension's identity, and those of a
test that reads or copies the C file.
screen_source ¶
screen_source(source: str, target)
The validity policy's review-only signals on a C test source for
target (PolicyReport). Python tests: Python's.
prune_collection_breakers ¶
prune_collection_breakers(source: str, *, timeout_s: float)
source without the units that keep it from compiling and linking
as a run builds it: each round removes the utest.h test, fixture block or
top-level declaration around a line GCC or ld reports an error on, at most
five rounds. unchanged when it compiles, applied with the
removed units, not_repaired with the input when a line lies in no
removable unit (an include, UTEST_MAIN()), no test is left or the
rounds do not suffice.
prune_unresolvable_imports ¶
prune_unresolvable_imports(source: str)
source without the includes of files that do not exist, one per
compile, at most ten (SourceResult).
is_test_file ¶
is_test_file(path: str) -> bool
Whether path names a C test file (test_*.c), or for Python
tests of an extension, a test file by Python's rule.
setup_files ¶
setup_files(root: str, test_paths) -> Tuple[str, ...]
The sources the project's own test programs build with
(c_test_support, relative to the project's root), as their
suite's setup files, and none in another mode. They are those of the tree
root lies in, the project or a copy of it: the nearest directory at
or above root that holds them, else the project's root. Python
tests have Python's (set on the instance in extension mode).
mutation_operators ¶
mutation_operators(engine: str = _mull.ENGINE) -> OperatorCatalogue
The operators a run measures by default: Mull's default group. The
set all is Mull's whole group.
open_mutation_session ¶
open_mutation_session(engine: str = _mull.ENGINE, workers: int = 1, **options: Any) -> MutationSession
A session of Mull that measures workers mutants at once, each
in a directory of its own.
capabilities ¶
capabilities() -> la.CapabilityReport
What this context provides: runs, coverage, per-test evidence, merging and the generated suite operations with a usable GCC and gcov, mutation also with a usable Mull, and missing setup without them.
CRunOptions
dataclass
¶
CRunOptions(target: Optional[str] = None, inner: Any = None)
The C adapter's runner options: the target the tests are linked with,
relative to the project root (request_options sets it from a run's
target).