# 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 C-S set, federation off
make complement-federation               # the federation 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

`COMPLEMENT_PROFILE` picks one; each has its own test set in `run.sh`.

**`csapi`** (the default, `make complement`) — the Client-Server tests in
`tests/csapi`, with `WARP_FEDERATION_ENABLED=false`. Port 8448 is still
served over TLS, because the CA is mounted either way, but the gate answers
every federation request with `M_UNRECOGNIZED`.

**`federation`** (`make complement-federation`) — the federation tests in
`tests/` and the multi-server tests in `tests/csapi`, with federation on.
The entrypoint has Complement's CA at `/complement/ca` sign a certificate
for the server's name, serves the API on 8448 with it, and points
`federation.tls_ca_file` at the same CA, so that Warp trusts the other
homeservers of the run and the servers Complement itself pretends to be.
The switch reaches the container through `COMPLEMENT_SHARE_ENV_PREFIX`:
`run.sh` sets `PASS_WARP_FEDERATION_ENABLED`, which Complement passes on
as `WARP_FEDERATION_ENABLED`.

The federation set leaves out partial-state joins (MSC3706,
`TestPartialStateJoin*`), which Warp does not implement.

Application services arrived in Phase 9. Complement writes the
registration file of each service a blueprint asks for into
`/complement/appservice`, and `entrypoint.sh` hands every file there to
`WARP_APPSERVICE_CONFIG_FILES`. The tests that use them, and the Phase 9
account tests (password change, deactivation), are not in either set yet.
They join once a run has shown which pass.

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