diff --git a/docs/development/development-setup.rst b/docs/development/development-setup.rst
index f311800c8..b4bf57dac 100644
--- a/docs/development/development-setup.rst
+++ b/docs/development/development-setup.rst
@@ -2,8 +2,8 @@
 Development setup
 =================
 
-Development environment & tests
--------------------------------
+Development environment & unit tests
+------------------------------------
 
 The basic method to set up a local environment is::
 
@@ -36,6 +36,40 @@ To avoid this, use ``--basetemp`` to set an alternate temporary directory, e.g.:
 
 You may also want to add ``-v`` for more verbose output.
 
+Integration test
+----------------
+
+The integration test is not included when running ``pytest irrd``.
+To run the integration test, two databases need to be configured, e.g.::
+
+    export IRRD_DATABASE_URL_INTEGRATION_1=postgresql:///irrd_test1
+    export IRRD_DATABASE_URL_INTEGRATION_2=postgresql:///irrd_test2
+
+The test can then be started with::
+
+    pytest --basetemp=.tmpdirs/ -s -vv irrd/integration_tests/run.py
+
+The `-s` parameter prevents `stdout` capture, which gives some information
+about the test setup to aid in debugging. This example also uses the
+temporary directory name fix suggested for unit tests.
+
+The integration test will start two instances of IRRd, one mirroring off the
+other, and an email server that captures all mail. It will then run a series
+of updates and queries, verify the contents of mails, the state of the
+databases, mirroring, utf-8 handling and run all basic types of queries.
+
+Code coverage is not measured for the integration test, as its purpose is
+not to test all paths, but rather verify that the most important paths
+are working end-to-end.
+
+.. danger::
+    The integration test will wipe all contents of IRRd tables in the databases
+    ``IRRD_DATABASE_URL_INTEGRATION_1`` and ``IRRD_DATABASE_URL_INTEGRATION_2``
+    without further checks or confirmation.
+
+Mypy and flake8
+---------------
+
 In addition to the tests, this project uses `mypy` for type checking and `flake8`
 for style checking. To run these, run::
 
diff --git a/irrd/integration_tests/run.py b/irrd/integration_tests/run.py
index 7024b88c4..2afcbd257 100644
--- a/irrd/integration_tests/run.py
+++ b/irrd/integration_tests/run.py
@@ -73,7 +73,23 @@ def test_irrd_integration(self, tmpdir):
         self._start_mailserver()
         self._start_irrds()
 
-        # Load a regular mntner and person into the DB, and verify
+        # Attempt to load a mntner with valid auth, but broken references.
+        self._submit_update(self.config_path1,
+                            SAMPLE_MNTNER + '\n\npassword: md5-password')
+        messages = self._retrieve_mails()
+        assert len(messages) == 1
+        mail_text = self._extract_message_body(messages[0])
+        assert messages[0]['Subject'] == 'FAILED: my subject'
+        assert messages[0]['From'] == 'from@example.com'
+        assert messages[0]['To'] == 'Sasha <sasha@example.com>'
+        assert '\nCreate FAILED: [mntner] TEST-MNT\n' in mail_text
+        assert '\nERROR: Object PERSON-TEST referenced in field admin-c not found in database TEST - must reference one of role, person.\n' in mail_text
+        assert '\nERROR: Object OTHER1-MNT referenced in field mnt-by not found in database TEST - must reference mntner.\n' in mail_text
+        assert '\nERROR: Object OTHER2-MNT referenced in field mnt-by not found in database TEST - must reference mntner.\n' in mail_text
+        assert 'email footer' in mail_text
+        assert 'Generated by IRRd version ' in mail_text
+
+        # Load a regular valid mntner and person into the DB, and verify
         # the contents of the result.
         self._submit_update(self.config_path1,
                             SAMPLE_MNTNER_CLEAN + '\n\n' + SAMPLE_PERSON + '\n\npassword: md5-password')
@@ -269,7 +285,6 @@ def test_irrd_integration(self, tmpdir):
         messages = self._retrieve_mails()
         assert len(messages) == 1
         mail_text = self._extract_message_body(messages[0])
-        print(mail_text)
         assert messages[0]['Subject'] == 'SUCCESS: my subject'
         assert messages[0]['From'] == 'from@example.com'
         assert messages[0]['To'] == 'Sasha <sasha@example.com>'
diff --git a/irrd/updates/tests/test_parser.py b/irrd/updates/tests/test_parser.py
index 733d62640..8ba173f30 100644
--- a/irrd/updates/tests/test_parser.py
+++ b/irrd/updates/tests/test_parser.py
@@ -160,7 +160,7 @@ def test_check_references_invalid_referred_objects_dont_exist(self, prepare_mock
         query_result_existing_obj = {
             'object_text': SAMPLE_INETNUM,
         }
-        query_results = iter([[query_result_existing_obj], [], [], []])
+        query_results = iter([[query_result_existing_obj], iter([]), iter([]), iter([])])
         mock_dh.execute_query = lambda query: next(query_results)
         validator = ReferenceValidator(mock_dh)
 
diff --git a/setup.py b/setup.py
index b8fd7ef9e..06662e8be 100755
--- a/setup.py
+++ b/setup.py
@@ -18,7 +18,7 @@
     long_description_content_type='text/x-rst',
     url='https://github.com/irrdnet/irrd4',
     packages=setuptools.find_packages(
-        exclude=["*.tests", "*.tests.*", "tests.*", "tests"]
+        exclude=['*.tests', '*.tests.*', 'tests.*', 'tests', 'integration_tests']
     ) + ['twisted.plugins'],
     python_requires='>=3.6',
     package_data={'': ['*.txt', '*.yaml', '*.mako']},