From 37ec1ba202f8bcf2622257e54cc1298273036918 Mon Sep 17 00:00:00 2001
From: Eric Eastwood <erice@element.io>
Date: Wed, 9 Jun 2021 02:29:15 -0500
Subject: [PATCH] Document how to see logger output when running the twisted
 tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

As shared by @erikjohnston ❤
https://github.com/matrix-org/synapse/pull/9247#discussion_r647237778
---
 README.rst            | 36 ++++++++++++++++++++++++------------
 changelog.d/10148.doc |  1 +
 2 files changed, 25 insertions(+), 12 deletions(-)
 create mode 100644 changelog.d/10148.doc

diff --git a/README.rst b/README.rst
index a14a687fd1b4..11631816a6b2 100644
--- a/README.rst
+++ b/README.rst
@@ -293,18 +293,6 @@ try installing the failing modules individually::
 
     pip install -e "module-name"
 
-Once this is done, you may wish to run Synapse's unit tests to
-check that everything is installed correctly::
-
-    python -m twisted.trial tests
-
-This should end with a 'PASSED' result (note that exact numbers will
-differ)::
-
-    Ran 1337 tests in 716.064s
-
-    PASSED (skips=15, successes=1322)
-
 We recommend using the demo which starts 3 federated instances running on ports `8080` - `8082`
 
     ./demo/start.sh
@@ -324,6 +312,30 @@ If you just want to start a single instance of the app and run it directly::
     python -m synapse.app.homeserver --config-path homeserver.yaml
 
 
+Running the unit tests
+======================
+
+After getting up and running, you may wish to run Synapse's unit tests to
+check that everything is installed correctly::
+
+    python -m twisted.trial tests
+
+This should end with a 'PASSED' result (note that exact numbers will
+differ)::
+
+    Ran 1337 tests in 716.064s
+
+    PASSED (skips=15, successes=1322)
+
+To run a specific test::
+
+    python -m twisted.trial tests.storage.test_redaction
+    python -m twisted.trial tests.handlers.test_presence.PresenceJoinTestCase.test_remote_gets_presence_when_local_user_joins
+
+To see logger output from the app while the tests run, set ``SYNAPSE_TEST_LOG_LEVEL``
+and the resulting logs will be in ``_trial_temp/test.log``::
+
+    SYNAPSE_TEST_LOG_LEVEL=DEBUG python -m twisted.trial tests
 
 
 Running the Integration Tests
diff --git a/changelog.d/10148.doc b/changelog.d/10148.doc
new file mode 100644
index 000000000000..5066392d409a
--- /dev/null
+++ b/changelog.d/10148.doc
@@ -0,0 +1 @@
+Document `SYNAPSE_TEST_LOG_LEVEL` to see the logger output when running tests.