deploy: ea01d4c2de

develop/development/contributing_guide.html

@@ -291,6 +291,41 @@ trial tests.rest.admin.test_room tests.handlers.test_admin.ExfiltrateData.test_i
 <p>To increase the log level for the tests, set <code>SYNAPSE_TEST_LOG_LEVEL</code>:</p>
 <pre><code class="language-sh">SYNAPSE_TEST_LOG_LEVEL=DEBUG trial tests
 </code></pre>
+<h3 id="running-tests-under-postgresql"><a class="header" href="#running-tests-under-postgresql">Running tests under PostgreSQL</a></h3>
+<p>Invoking <code>trial</code> as above will use an in-memory SQLite database. This is great for
+quick development and testing. However, we recommend using a PostgreSQL database
+in production (and indeed, we have some code paths specific to each database).
+This means that we need to run our unit tests against PostgreSQL too. Our CI does
+this automatically for pull requests and release candidates, but it's sometimes
+useful to reproduce this locally.</p>
+<p>To do so, <a href="../postgres.html">configure Postgres</a> and run <code>trial</code> with the
+following environment variables matching your configuration:</p>
+<ul>
+<li><code>SYNAPSE_POSTGRES</code> to anything nonempty</li>
+<li><code>SYNAPSE_POSTGRES_HOST</code></li>
+<li><code>SYNAPSE_POSTGRES_USER</code></li>
+<li><code>SYNAPSE_POSTGRES_PASSWORD</code></li>
+</ul>
+<p>For example:</p>
+<pre><code class="language-shell">export SYNAPSE_POSTGRES=1
+export SYNAPSE_POSTGRES_HOST=localhost
+export SYNAPSE_POSTGRES_USER=postgres
+export SYNAPSE_POSTGRES_PASSWORD=mydevenvpassword
+trial
+</code></pre>
+<h4 id="prebuilt-container"><a class="header" href="#prebuilt-container">Prebuilt container</a></h4>
+<p>Since configuring PostgreSQL can be fiddly, we can make use of a pre-made
+Docker container to set up PostgreSQL and run our tests for us. To do so, run</p>
+<pre><code class="language-shell">scripts-dev/test_postgresql.sh
+</code></pre>
+<p>Any extra arguments to the script will be passed to <code>tox</code> and then to <code>trial</code>,
+so we can run a specific test in this container with e.g.</p>
+<pre><code class="language-shell">scripts-dev/test_postgresql.sh tests.replication.test_sharded_event_persister.EventPersisterShardTestCase
+</code></pre>
+<p>The container creates a folder in your Synapse checkout called
+<code>.tox-pg-container</code> and uses this as a tox environment. The output of any
+<code>trial</code> runs goes into <code>_trial_temp</code> in your synapse source directory — the same
+as running <code>trial</code> directly on your host machine.</p>
 <h2 id="run-the-integration-tests-a-hrefhttpsgithubcommatrix-orgsytestsytesta"><a class="header" href="#run-the-integration-tests-a-hrefhttpsgithubcommatrix-orgsytestsytesta">Run the integration tests (<a href="https://github.com/matrix-org/sytest">Sytest</a>).</a></h2>
 <p>The integration tests are a more comprehensive suite of tests. They
 run a full version of Synapse, including your changes, to check if

develop/print.html

@@ -11460,6 +11460,41 @@ trial tests.rest.admin.test_room tests.handlers.test_admin.ExfiltrateData.test_i
 <p>To increase the log level for the tests, set <code>SYNAPSE_TEST_LOG_LEVEL</code>:</p>
 <pre><code class="language-sh">SYNAPSE_TEST_LOG_LEVEL=DEBUG trial tests
 </code></pre>
+<h3 id="running-tests-under-postgresql"><a class="header" href="#running-tests-under-postgresql">Running tests under PostgreSQL</a></h3>
+<p>Invoking <code>trial</code> as above will use an in-memory SQLite database. This is great for
+quick development and testing. However, we recommend using a PostgreSQL database
+in production (and indeed, we have some code paths specific to each database).
+This means that we need to run our unit tests against PostgreSQL too. Our CI does
+this automatically for pull requests and release candidates, but it's sometimes
+useful to reproduce this locally.</p>
+<p>To do so, <a href="development/../postgres.html">configure Postgres</a> and run <code>trial</code> with the
+following environment variables matching your configuration:</p>
+<ul>
+<li><code>SYNAPSE_POSTGRES</code> to anything nonempty</li>
+<li><code>SYNAPSE_POSTGRES_HOST</code></li>
+<li><code>SYNAPSE_POSTGRES_USER</code></li>
+<li><code>SYNAPSE_POSTGRES_PASSWORD</code></li>
+</ul>
+<p>For example:</p>
+<pre><code class="language-shell">export SYNAPSE_POSTGRES=1
+export SYNAPSE_POSTGRES_HOST=localhost
+export SYNAPSE_POSTGRES_USER=postgres
+export SYNAPSE_POSTGRES_PASSWORD=mydevenvpassword
+trial
+</code></pre>
+<h4 id="prebuilt-container"><a class="header" href="#prebuilt-container">Prebuilt container</a></h4>
+<p>Since configuring PostgreSQL can be fiddly, we can make use of a pre-made
+Docker container to set up PostgreSQL and run our tests for us. To do so, run</p>
+<pre><code class="language-shell">scripts-dev/test_postgresql.sh
+</code></pre>
+<p>Any extra arguments to the script will be passed to <code>tox</code> and then to <code>trial</code>,
+so we can run a specific test in this container with e.g.</p>
+<pre><code class="language-shell">scripts-dev/test_postgresql.sh tests.replication.test_sharded_event_persister.EventPersisterShardTestCase
+</code></pre>
+<p>The container creates a folder in your Synapse checkout called
+<code>.tox-pg-container</code> and uses this as a tox environment. The output of any
+<code>trial</code> runs goes into <code>_trial_temp</code> in your synapse source directory — the same
+as running <code>trial</code> directly on your host machine.</p>
 <h2 id="run-the-integration-tests-a-hrefhttpsgithubcommatrix-orgsytestsytesta"><a class="header" href="#run-the-integration-tests-a-hrefhttpsgithubcommatrix-orgsytestsytesta">Run the integration tests (<a href="https://github.com/matrix-org/sytest">Sytest</a>).</a></h2>
 <p>The integration tests are a more comprehensive suite of tests. They
 run a full version of Synapse, including your changes, to check if