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

### 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
```

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