# 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 --features openreg
docker build -t continuwuity:complement -f docker/complement.Dockerfile .
./bin/complement
```

The `openreg` feature is required: without it the server refuses the open
registrations Complement uses to create test users, and almost every test fails.

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