# Complement

[Complement](https://github.com/matrix-org/complement) is the official
Matrix integration suite and this project's primary progress metric
(PLAN.md section 9). It runs one container per homeserver per test and
drives it over the real HTTP API.

```sh
make complement                          # the current target set
bash run.sh TestLogin                    # one test
COMPLEMENT_DEBUG=1 make complement       # with the container logs
```

Needs Docker. [run.sh](run.sh) builds the image, clones Complement into
`.complement/` at the repository root (git-ignored) and runs the subset for
the phases that are done.

## Files

| | |
|---|---|
| [Dockerfile](Dockerfile) | the homeserver image, built from the repository root |
| [entrypoint.sh](entrypoint.sh) | the deployment, entirely `WARP_*` environment variables |
| [run.sh](run.sh) | build, clone, run |

## Profiles

**`federation=off`** — what runs today. Only the Client-Server tests;
`WARP_FEDERATION_ENABLED=false`, port 8448 exposed but unserved.

**`federation=on`** — Phase 5. It needs a TLS listener on 8448 with a
certificate signed by the CA that Complement mounts at `/complement/ca`,
which is the first thing to add here when federation lands.

## The test set

`COMPLEMENT_TESTS` in `run.sh` lists what is expected to pass. Phase 1:

- `TestRegistration`
- `TestLogin`
- `TestDeviceManagement`

Extend it as each phase lands rather than switching to the whole suite: a
pass count that drops because a later phase is missing is noise, not
information.

Two notes on the environment, both in `entrypoint.sh`:

- **Rate limiting is off.** The whole suite comes from the one address the
  test runner has, so the limiter would spend the run returning
  `M_LIMIT_EXCEEDED` and tell us nothing about the server. Synapse's own
  Complement image does the same.
- **Registration is on**, because the tests create their own users.

## Tests that need later phases

Some subtests of the three above reach for endpoints that are not Phase 1
work. `TestDeviceManagement` calls `/sync` after creating a session, and
`TestLogout` checks that a revoked token cannot sync. Phase 1 answers
`/sync` with an empty but well-formed response for exactly that reason —
there are no rooms yet, so an empty sync is the complete truth, and it makes
token revocation observable. Phase 4 replaces it with the real syncapi.

The shared-secret registration subtests of `TestRegistration` probe
`/_synapse/admin/v1/register` and skip themselves when it 404s, which it
does here: that endpoint is Synapse's, and `warp create-account` covers the
same need.