How the parts fit¶
A program such as Testuary reaches a language's tools through the layers below, and Words defines the terms the guides use.
The layers¶
consumers Testuary, and programs built on it
each publishes a profile: what it needs, family by family
|
| call LangAdapter's public operations: run a suite, measure
| coverage, run mutation testing, repair a test file, ...
v
LangAdapter the base class checks each request once for every
base class language, answers what an adapter lacks and removes a
test by its test_units. The shared loops (templates) that
repair a test file that does not load, repair syntax and
remove failing imports are there for your hooks to call
|
| calls the adapter's hooks
v
adapters Python, Java and C, which come with LangAdapter, and yours
each declares its facts and implements its hooks. The
tree-sitter units (find tests, imports and the code
around a line from a grammar) serve every adapter whose
language has a grammar
|
| run the language's tools
v
the language's its test runner, coverage tool and mutation tool
own tools
A consumer asks for operations, and reads facts and calls some hooks
itself, such as run_counts. It never calls a language's tools directly, so
it needs no code per language. An adapter provides only its language's
specifics and calls the shared loops for the rest.
Words¶
The steps of the guide use four words:
- fact: something your adapter declares about its language, such as how test files are named. Facts have defaults.
- hook: a method or attribute of your adapter that LangAdapter or a
consumer calls or reads, such as
run_suite. - family: a group of hooks that together give one capability, such as coverage or load repair.
- fallback: what a consumer does when an optional family is missing.
Who needs what defines two more: consumer and profile.
The rest appear in the reference and in messages:
- operation: what a consumer asks of LangAdapter, such as running a suite. An operation is built on one or more hooks.
- capability: whether an operation, or an entry of the capability report such as coverage, works for a project: available, unsupported, or missing its setup, with the reason.
- template: a shared loop in
langadapter.templatesthat your hook calls with its own steps, such as the loop that repairs a test file that does not load. - toolkit: a helper an adapter uses for common work, such as reading tests from a tree-sitter grammar.
- level: a group of families in a consumer's profile, in the order the consumer suggests adding them. Levels belong to a consumer, not to LangAdapter.
- fallbacks: the record a consumer's run keeps when it applied a fallback.
Where things live¶
A newcomer can read LangAdapter's package in this order:
langadapter/
adapter.py the base class: facts and hooks
operations.py the operation groups, built on the hooks
hooks.py every fact, hook and family, with what it enables
consumers.py the consumers' profiles, read from installed packages
check.py the check: neutral, or for a consumer
templates.py the shared loops
treesitter.py tree-sitter units
tutorial/ langadapter tutorial and its example language
cli.py the langadapter command and the new-language scaffold
python/, java/, the three adapters that come with LangAdapter, java/ with
c/ the JDK, build, JUnit, JaCoCo and PIT machinery
The Python, Java and C adapters are worked examples of most families. None
has every one: langadapter check python, langadapter check java and
langadapter check c show which they leave out.