Unify Complement developer docs (#19518)
Instead of having info spread across a few places, consolidate and link to one spot.
This commit is contained in:
Eric Eastwood
1
changelog.d/19518.doc
Normal file
1
changelog.d/19518.doc
Normal file
@@ -0,0 +1 @@
|
||||
Unify Complement developer docs.
|
||||
@@ -8,8 +8,7 @@ ensure everything works at a holistic level.
|
||||
## Setup
|
||||
|
||||
Nothing beyond a [normal Complement
|
||||
setup](https://github.com/matrix-org/complement?tab=readme-ov-file#running) (just Go and
|
||||
Docker).
|
||||
setup](https://github.com/matrix-org/complement#running) (just Go and Docker).
|
||||
|
||||
|
||||
## Running tests
|
||||
@@ -28,14 +27,39 @@ scripts-dev/complement.sh ./tests/csapi/... -run TestRoomCreate/Parallel/POST_/c
|
||||
scripts-dev/complement.sh ./tests/... -run 'TestRoomCreate/Parallel/POST_/createRoom_makes_a_(.*)'
|
||||
```
|
||||
|
||||
Typically, if you're developing the Synapse and Complement tests side-by-side, you will
|
||||
run something like this:
|
||||
It's often nice to develop on Synapse and write Complement tests at the same time.
|
||||
Here is how to run your local Synapse checkout against your local Complement checkout.
|
||||
|
||||
```shell
|
||||
# To run a specific test
|
||||
COMPLEMENT_DIR=../complement ./scripts-dev/complement.sh ./tests/csapi/... -run TestRoomCreate
|
||||
```
|
||||
|
||||
The above will run a monolithic (single-process) Synapse with SQLite as the database.
|
||||
For other configurations, try:
|
||||
|
||||
- Passing `POSTGRES=1` as an environment variable to use the Postgres database instead.
|
||||
- Passing `WORKERS=1` as an environment variable to use a workerised setup instead. This
|
||||
option implies the use of Postgres.
|
||||
- If setting `WORKERS=1`, optionally set `WORKER_TYPES=` to declare which worker types
|
||||
you wish to test. A simple comma-delimited string containing the worker types
|
||||
defined from the `WORKERS_CONFIG` template in
|
||||
[here](https://github.com/element-hq/synapse/blob/develop/docker/configure_workers_and_start.py#L54).
|
||||
A safe example would be `WORKER_TYPES="federation_inbound, federation_sender,
|
||||
synchrotron"`. See the [worker documentation](../workers.md) for additional
|
||||
information on workers.
|
||||
- Passing `ASYNCIO_REACTOR=1` as an environment variable to use the asyncio-backed
|
||||
reactor with Twisted instead of the default one.
|
||||
- Passing `PODMAN=1` will use the [podman](https://podman.io/) container runtime,
|
||||
instead of docker.
|
||||
- Passing `UNIX_SOCKETS=1` will utilise Unix socket functionality for Synapse, Redis,
|
||||
and Postgres(when applicable).
|
||||
|
||||
To increase the log level for the tests, set `SYNAPSE_TEST_LOG_LEVEL`, e.g:
|
||||
```sh
|
||||
SYNAPSE_TEST_LOG_LEVEL=DEBUG COMPLEMENT_DIR=../complement ./scripts-dev/complement.sh -run TestRoomCreate
|
||||
```
|
||||
|
||||
|
||||
### Running in-repo tests
|
||||
|
||||
@@ -52,3 +76,20 @@ To run the in-repo Complement tests, use the `--in-repo` command line argument.
|
||||
# Similarly, you can also use `-run` to specify all or part of a specific test path to run
|
||||
scripts-dev/complement.sh --in-repo ./tests/... -run TestIntraShardFederation
|
||||
```
|
||||
|
||||
### Access database for homeserver after Complement test runs.
|
||||
|
||||
If you're curious what the database looks like after you run some tests, here are some
|
||||
steps to get you going in Synapse:
|
||||
|
||||
1. In your Complement test comment out `defer deployment.Destroy(t)` and replace with
|
||||
`defer time.Sleep(2 * time.Hour)` to keep the homeserver running after the tests
|
||||
complete
|
||||
1. Start the Complement tests
|
||||
1. Find the name of the container, `docker ps -f name=complement_` (this will filter for
|
||||
just the Complement related Docker containers)
|
||||
1. Access the container replacing the name with what you found in the previous step:
|
||||
`docker exec -it complement_1_hs_with_application_service.hs1_2 /bin/bash`
|
||||
1. Install sqlite (database driver), `apt-get update && apt-get install -y sqlite3`
|
||||
1. Then run `sqlite3` and open the database `.open /conf/homeserver.db` (this db path
|
||||
comes from the Synapse homeserver.yaml)
|
||||
|
||||
@@ -12,11 +12,9 @@ Note that running Synapse's unit tests from within the docker image is not suppo
|
||||
|
||||
`scripts-dev/complement.sh` is a script that will automatically build
|
||||
and run Synapse against Complement.
|
||||
Consult the [contributing guide][guideComplementSh] for instructions on how to use it.
|
||||
Consult our [Complement docs][https://github.com/element-hq/synapse/tree/develop/complement] for instructions on how to use it.
|
||||
|
||||
|
||||
[guideComplementSh]: https://element-hq.github.io/synapse/latest/development/contributing_guide.html#run-the-integration-tests-complement
|
||||
|
||||
## Building and running the images manually
|
||||
|
||||
Under some circumstances, you may wish to build the images manually.
|
||||
|
||||
@@ -334,46 +334,9 @@ For more details about other configurations, see the [Docker-specific documentat
|
||||
|
||||
## Run the integration tests ([Complement](https://github.com/matrix-org/complement)).
|
||||
|
||||
[Complement](https://github.com/matrix-org/complement) is a suite of black box tests that can be run on any homeserver implementation. It can also be thought of as end-to-end (e2e) tests.
|
||||
See our [Complement docs](https://github.com/element-hq/synapse/tree/develop/complement)
|
||||
for how to use the `./scripts-dev/complement.sh` test runner script.
|
||||
|
||||
It's often nice to develop on Synapse and write Complement tests at the same time.
|
||||
Here is how to run your local Synapse checkout against your local Complement checkout.
|
||||
|
||||
(checkout [`complement`](https://github.com/matrix-org/complement) alongside your `synapse` checkout)
|
||||
```sh
|
||||
COMPLEMENT_DIR=../complement ./scripts-dev/complement.sh
|
||||
```
|
||||
|
||||
To run a specific test file, you can pass the test name at the end of the command. The name passed comes from the naming structure in your Complement tests. If you're unsure of the name, you can do a full run and copy it from the test output:
|
||||
|
||||
```sh
|
||||
COMPLEMENT_DIR=../complement ./scripts-dev/complement.sh -run TestImportHistoricalMessages
|
||||
```
|
||||
|
||||
To run a specific test, you can specify the whole name structure:
|
||||
|
||||
```sh
|
||||
COMPLEMENT_DIR=../complement ./scripts-dev/complement.sh -run TestImportHistoricalMessages/parallel/Historical_events_resolve_in_the_correct_order
|
||||
```
|
||||
|
||||
The above will run a monolithic (single-process) Synapse with SQLite as the database. For other configurations, try:
|
||||
|
||||
- Passing `POSTGRES=1` as an environment variable to use the Postgres database instead.
|
||||
- Passing `WORKERS=1` as an environment variable to use a workerised setup instead. This option implies the use of Postgres.
|
||||
- If setting `WORKERS=1`, optionally set `WORKER_TYPES=` to declare which worker
|
||||
types you wish to test. A simple comma-delimited string containing the worker types
|
||||
defined from the `WORKERS_CONFIG` template in
|
||||
[here](https://github.com/element-hq/synapse/blob/develop/docker/configure_workers_and_start.py#L54).
|
||||
A safe example would be `WORKER_TYPES="federation_inbound, federation_sender, synchrotron"`.
|
||||
See the [worker documentation](../workers.md) for additional information on workers.
|
||||
- Passing `ASYNCIO_REACTOR=1` as an environment variable to use the Twisted asyncio reactor instead of the default one.
|
||||
- Passing `PODMAN=1` will use the [podman](https://podman.io/) container runtime, instead of docker.
|
||||
- Passing `UNIX_SOCKETS=1` will utilise Unix socket functionality for Synapse, Redis, and Postgres(when applicable).
|
||||
|
||||
To increase the log level for the tests, set `SYNAPSE_TEST_LOG_LEVEL`, e.g:
|
||||
```sh
|
||||
SYNAPSE_TEST_LOG_LEVEL=DEBUG COMPLEMENT_DIR=../complement ./scripts-dev/complement.sh -run TestImportHistoricalMessages
|
||||
```
|
||||
|
||||
### Prettier formatting with `gotestfmt`
|
||||
|
||||
@@ -389,18 +352,6 @@ COMPLEMENT_DIR=../complement ./scripts-dev/complement.sh -json | gotestfmt -hide
|
||||
(Remove `-hide successful-tests` if you don't want to hide successful tests.)
|
||||
|
||||
|
||||
### Access database for homeserver after Complement test runs.
|
||||
|
||||
If you're curious what the database looks like after you run some tests, here are some steps to get you going in Synapse:
|
||||
|
||||
1. In your Complement test comment out `defer deployment.Destroy(t)` and replace with `defer time.Sleep(2 * time.Hour)` to keep the homeserver running after the tests complete
|
||||
1. Start the Complement tests
|
||||
1. Find the name of the container, `docker ps -f name=complement_` (this will filter for just the Compelement related Docker containers)
|
||||
1. Access the container replacing the name with what you found in the previous step: `docker exec -it complement_1_hs_with_application_service.hs1_2 /bin/bash`
|
||||
1. Install sqlite (database driver), `apt-get update && apt-get install -y sqlite3`
|
||||
1. Then run `sqlite3` and open the database `.open /conf/homeserver.db` (this db path comes from the Synapse homeserver.yaml)
|
||||
|
||||
|
||||
# 9. Submit your patch.
|
||||
|
||||
Once you're happy with your patch, it's time to prepare a Pull Request.
|
||||
|
||||
Reference in New Issue
Block a user