TESTAR Trace is a toolkit for identifying trace links between software requirements and state models generated by TESTAR. It establishes requirements completeness in those state models while preserving the trace evidence needed to inspect each conclusion.
The project is developed as part of the master's thesis Requirements Traceability for Scriptless Testing in the Master Software Engineering programme at Open Universiteit.
- Import use cases, user stories, Gherkin features, formal requirements, and TESTAR state-model exports.
- Materialize complete branch-resolved requirement paths.
- Run deterministic lexical, graph-alignment, execution-alignment, and formal conformance methods.
- Inspect trace links, ordered occurrences, requirements completeness, and supporting diagnostics through a CLI or local-only web application.
- Compare completeness methods against independently curated reference labels.
apps ────────> adapters ────────> core
└─────────────────────────────> core
packages/corecontains canonical domain models, traceability methods, and analysis logic. It is distributed astestar-traceand imported astestar_trace.packages/adaptersconverts external formats into core models. It is distributed astestar-trace-adaptersand imported astestar_trace_adapters.apps/cliprovides thetestar-tracecommand.apps/webruns the same Python packages locally in a Pyodide Web Worker.
See the architecture overview for the complete boundary and data-flow description.
TESTAR Trace is pre-1.0 software under active development. Readers accept only the current declared schema versions and reject unsupported versions explicitly. The public Python API may change between minor pre-1.0 releases.
- Python 3.13 or 3.14
- uv 0.12.x
- Vite+ for web development; Vite+ manages the repository's Node.js and pnpm versions
Synchronize the Python workspace:
uv sync --all-packages --all-groups --locked
Inspect the command-line interface:
uv run testar-trace --help
uv run testar-trace methods
uv run testar-trace formats
Run an analysis with the curated TbUIS sample:
uv run testar-trace analyze \
--requirements benchmarks/tbuis/requirements/use-cases/uc-01-application-login.md \
--state-models benchmarks/tbuis/evidence/uc-01.json \
--method graph-alignment
Run the web application:
cd apps/web
vp install
vp run dev
Imported data and analysis results remain in the browser unless explicitly exported.
Run the Python validation suite from the repository root:
uv format --check
uv run ruff check .
uv check --all-packages
uv run ty check
uv run pytest --cov --cov-report=term-missing -q
uv build --all-packages
Run web validation from apps/web:
vp check
vp run test:coverage
vp run build
vp run check:bundle
vp run test:e2e:prepared
See CONTRIBUTING.md for change boundaries and the complete workflow.
benchmarks/ contains curated inputs and reference data associated with
systems under test. Generated analysis output is not versioned unless it has
been deliberately reviewed and promoted to reference data. Large reproducible
artifacts belong in a separately versioned dataset with checksums rather than
Git history.
See the benchmark policy before adding or modifying benchmark artifacts.
- Architecture
- Terminology
- Evaluation protocol
- External formats
- CLI guide
- Web application guide
- Repository operations
The web application processes imported artifacts locally. Do not commit credentials, personal data, or proprietary state models. Report security issues according to SECURITY.md.
If you use TESTAR Trace in research, cite the software using CITATION.cff.
TESTAR Trace source code is licensed under the MIT License. Benchmark artifacts may originate from third parties and must carry their own provenance and licensing information.