diff --git a/docs/integration_tests.md b/docs/integration_tests.md
index 0fa1998499..b528724444 100644
--- a/docs/integration_tests.md
+++ b/docs/integration_tests.md
@@ -43,14 +43,17 @@ virtualenv -p python3 env
 source env/bin/activate
 pip install -e .
 demo/start.sh --no-rate-limit
+
 ```
 
-Alternatively, to install the latest Synapse release package (and not a cloned branch) you can run the following instead of `pip install -e .`:
+Alternatively, to install the latest Synapse release package (and not a cloned branch) you can run the following instead of `git clone` and `pip install -e .`:
 
 ```bash
 pip install matrix-synapse
 ```
 
+### Integration test failures
+
 You should now have 3 running federated Synapse instances 🎉, at http://127.0.0.1:8080/, http://127.0.0.1:8081/ and  http://127.0.0.1:8082/, which should display a "It Works! Synapse is running" message.
 
 ## Run the test
@@ -87,6 +90,18 @@ You'll need python3 to be able to run synapse
 
 Try on the Emulator browser to open "http://10.0.2.2:8080". You should see the "Synapse is running" message.
 
+### Tests partially run but some fail with "Unable to contact localhost:8080"
+
+This is because the `public_baseurl` of synapse is not consistent with the endpoint that the tests are connecting to.
+
+Ensure you have the following configuration in `demo/etc/8080.config`.
+
+```
+public_baseurl: http://10.0.2.2:8080/
+```
+
+After changing this you will need to restart synapse using `demo/stop.sh` and `demo/start.sh` to load the new configuration.
+
 ### virtualenv command fails
 
 You can try using