Skip to content

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.

language class-attribute instance-attribute

language = 'c'

file_extensions class-attribute instance-attribute

file_extensions = ('.c',)

display_name class-attribute instance-attribute

display_name = 'C'

runtime class-attribute instance-attribute

runtime = 'gcc'

The program that builds and so runs the tests: the project's GCC.

test_file_name class-attribute instance-attribute

test_file_name = 'test_{stem}.c'

test_framework class-attribute instance-attribute

test_framework = 'utest.h'

code_fence class-attribute instance-attribute

code_fence = 'c'

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_files instance-attribute

test_files = self._extension_test_files

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_engines

mutation_engines() -> Tuple[str, ...]

Mull, with a usable GCC and Mull.

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).

target class-attribute instance-attribute

target: Optional[str] = None

inner class-attribute instance-attribute

inner: Any = None

The Python adapter's runner options, for Python tests.