Add a way to run tests in PostgreSQL in Docker

CONTRIBUTING.rst

@@ -30,12 +30,30 @@ use github's pull request workflow to review the contribution, and either ask
 you to make any refinements needed or merge it and make them ourselves. The
 changes will then land on master when we next do a release.
 
-We use `Jenkins <http://matrix.org/jenkins>`_ and
-`Travis <https://travis-ci.org/matrix-org/synapse>`_ for continuous
-integration. All pull requests to synapse get automatically tested by Travis;
-the Jenkins builds require an adminstrator to start them. If your change
-breaks the build, this will be shown in github, so please keep an eye on the
-pull request for feedback.
+We use `Jenkins <http://matrix.org/jenkins>`_, `CircleCI
+<https://circleci.com/gh/matrix-org>`_ and `Travis
+<https://travis-ci.org/matrix-org/synapse>`_ for continuous integration. All
+pull requests to synapse get automatically tested by Travis and CircleCI; the
+Jenkins builds require an adminstrator to start them. If your change breaks the
+build, this will be shown in GitHub, so please keep an eye on the pull request
+for feedback.
+
+To run unit tests, you can use:
+
+- ``tox -e py27`` (requires tox to be installed by ``pip install tox``) for
+  SQLite-backed Synapse on Python 2.7.
+- ``tox -e py35`` for SQLite-backed Synapse on Python 3.5.
+- ``tox -e py36`` for SQLite-backed Synapse on Python 3.6.
+- ``tox -e py27-postgres`` for PostgreSQL-backed Synapse on Python 2.7
+  (requires a running local PostgreSQL with access to create databases).
+- ``./test_postgresql.sh`` for PostgreSQL-backed Synapse on Python 2.7
+  (requires Docker). Entirely self-contained, recommended if you don't want to
+  set up PostgreSQL yourself.
+
+Docker images are available for running the integration tests (SyTest) locally,
+see the `documentation in the SyTest repo
+<https://github.com/matrix-org/sytest/blob/develop/docker/README.md>`_ for more
+information.
 
 Code style
 ~~~~~~~~~~

Dockerfile-pgtests

@@ -0,0 +1,8 @@
+FROM matrixdotorg/sytest:latest
+
+RUN apt-get -qq install -y python python-dev python-pip
+
+RUN pip install tox
+
+ADD docker_run_pg_tests.sh /pg_tests.sh
+ENTRYPOINT /pg_tests.sh

MANIFEST.in

@@ -28,6 +28,9 @@ exclude jenkins*.sh
 exclude jenkins*
 exclude Dockerfile
 exclude .dockerignore
+exclude Dockerfile-pgtests
+exclude docker_run_pg_tests.sh
+exclude test_postgresql.sh
 recursive-exclude jenkins *.sh
 
 include pyproject.toml

changelog.d/3699.misc

@@ -0,0 +1,2 @@
+Unit tests can now be run under PostgreSQL in Docker using 
+``test_postgresql.sh``.

docker_run_pg_tests.sh

@@ -0,0 +1,10 @@
+export PGDATA=/var/lib/postgresql/data
+export PGUSER=postgres
+
+# Initialise the database files and start the database
+su -c '/usr/lib/postgresql/9.6/bin/initdb -E "UTF-8" --lc-collate="en_US.UTF-8" --lc-ctype="en_US.UTF-8" --username=postgres' postgres
+su -c '/usr/lib/postgresql/9.6/bin/pg_ctl -w -D /var/lib/postgresql/data start' postgres
+
+cd /src
+export TRIAL_FLAGS="-j 4"
+tox -e py27-postgres

test_postgresql.sh

@@ -0,0 +1,3 @@
+#! /usr/bin/env bash
+docker build . -f Dockerfile-pgtests -t synapsepgtests
+docker run --rm -it -v $(pwd)\:/src synapsepgtests