# Testing

## Complement

Have a look at [Complement's repository][complement] for an explanation of what
it is. Continuwuity runs Complement manually; it is not part of the normal test
suite or default CI gate.

### Run it locally

Install Git, Rust, Docker, Go, and `jq`. From this repository's root, build the
server image and run the suite:

```bash
cargo build -p conduwuit
docker build -t continuwuity:complement -f docker/complement.Dockerfile .
./bin/complement
```

The run can take up to an hour. The runner writes the full Go test stream to
`tests/test_results/complement/test_logs.jsonl` and a sorted pass/fail/skip
summary to `tests/test_results/complement/test_results.jsonl`. It exits nonzero
when Complement reports failing tests, after writing both files.

On first use, the runner downloads the pinned upstream Complement revision to
`target/complement`. Pass a checkout path or set `COMPLEMENT_SRC` to run a
different revision or the [Continuwuity fork][complement-fork].

To run test packages that mention an MSC, pass its number:

```bash
./bin/complement --msc 3391
```

This selects packages from Complement's source comments and file names, so it
can include tests shared with that MSC but does not claim a complete mapping.

To run a Docker image archive instead of building locally:

```bash
./bin/complement --image path/to/complement-image.tar.gz
```

`COMPLEMENT_ENABLE_DIRTY_RUNS=1` reuses Complement containers for faster local
runs, but can let state leak between tests. Do not use it when validating a
failure or updating the committed result summary.

The checked-in result summary is a baseline, not an assertion that every test
passes. Compare a manual run with it when working on a compliance fix:

```bash
git diff -- tests/test_results/complement/test_results.jsonl
```

### Run it in CI

Add the `Testing/Complement` label to a pull request to run the suite in
Forgejo Actions. The workflow builds the image from the pull request, checks
out upstream Complement, and uploads the full logs and result summary as an
artifact. It passes only when the summary matches the checked-in baseline, so
expected existing failures do not hide regressions.

You can also start the workflow manually from the Actions page.

[complement]: https://github.com/matrix-org/complement
[complement-fork]: https://forgejo.ellis.link/continuwuation/complement