Development¶

cite-runner is implemented in Python.

The standalone application depends on the following third-party projects:

typer for CLI commands
pydantic for models
jinja for output format templates
httpx for making network requests
lxml for parsing teamengine responses
mkdocs for documentation

Brief implementation overview¶

cite-runner runs CITE tests suites by calling teamengine's web API. It requests test suite results in the EARL (AKA the W3C Evaluation and Report Language) format, which is XML-based.

After obtaining a test suite run result in EARL format, cite-runner parses it into an instance of models.TestSuiteResult, its internal data structure.From there, it is able to serialize it into either JSON or markdown.

Setting up a development environment¶

In a brief nutshell:

Fork the cite-runner repository
Clone you fork to your local environment
Install uv
Use uv to install the cite-runner code locally. This will create a virtualenv and install all dependencies needed for development, including for working on docs:
```
uv sync
```
Optionally (but strongly recommended) enable the pre-commit hooks provided by cite-runner:
```
uv run pre-commit install
```
Stand up a docker container with a local teamengine instance:
```
docker run \
    --rm \
    --name=teamengine \
    --network=host \
    ogccite/teamengine-production:1.0-SNAPSHOT
```
You should now be able to use http:localhost:8080/teamengine in cite-runner

Warning

teamengine will try to run on your local port 8080, which could potentially already be occupied by another application.
Work on the cite-runner code
You can run cite-runner via uv with:
```
uv run cite-runner
```
If you want to work on documentation, you can start the mkdocs server with:
```
uv run mkdocs serve
```