1 files changed, 94 insertions, 0 deletions
diff --git a/tests/README.rst b/tests/README.rst
new file mode 100644
index 0000000..63c7238
--- /dev/null
+++ b/tests/README.rst
@@ -0,0 +1,94 @@
+psycopg test suite
+===================
+
+Quick version
+-------------
+
+To run tests on the current code you can install the `test` extra of the
+package, specify a connection string  in the `PSYCOPG_TEST_DSN` env var to
+connect to a test database, and run ``pytest``::
+
+    $ pip install -e "psycopg[test]"
+    $ export PSYCOPG_TEST_DSN="host=localhost dbname=psycopg_test"
+    $ pytest
+
+
+Test options
+------------
+
+- The tests output header shows additional psycopg related information,
+  on top of the one normally displayed by ``pytest`` and the extensions used::
+
+      $ pytest
+      ========================= test session starts =========================
+      platform linux -- Python 3.8.5, pytest-6.0.2, py-1.10.0, pluggy-0.13.1
+      Using --randomly-seed=2416596601
+      libpq available: 130002
+      libpq wrapper implementation: c
+
+
+- By default the tests run using the ``pq`` implementation that psycopg would
+  choose (the C module if installed, else the Python one). In order to test a
+  different implementation, use the normal `pq module selection mechanism`__
+  of the ``PSYCOPG_IMPL`` env var::
+
+      $ PSYCOPG_IMPL=python pytest 
+      ========================= test session starts =========================
+      [...]
+      libpq available: 130002
+      libpq wrapper implementation: python
+
+  .. __: https://www.psycopg.org/psycopg/docs/api/pq.html#pq-module-implementations
+
+
+- Slow tests have a ``slow`` marker which can be selected to reduce test
+  runtime to a few seconds only. Please add a ``@pytest.mark.slow`` marker to
+  any test needing an arbitrary wait. At the time of writing::
+
+      $ pytest
+      ========================= test session starts =========================
+      [...]
+      ======= 1983 passed, 3 skipped, 110 xfailed in 78.21s (0:01:18) =======
+
+      $ pytest -m "not slow"
+      ========================= test session starts =========================
+      [...]
+      ==== 1877 passed, 2 skipped, 169 deselected, 48 xfailed in 13.47s =====
+
+- ``pytest`` option ``--pq-trace={TRACEFILE,STDERR}`` can be used to capture
+  libpq trace. When using ``stderr``, the output will only be shown for
+  failing or in-error tests, unless ``-s/--capture=no`` option is used.
+
+- ``pytest`` option ``--pq-debug`` can be used to log access to libpq's
+  ``PGconn`` functions.
+
+
+Testing in docker
+-----------------
+
+Useful to test different Python versions without installing them. Can be used
+to replicate GitHub actions failures, specifying the ``--randomly-seed`` used
+in the test run. The following ``PG*`` env vars are an example to adjust the
+test dsn in order to connect to a database running on the docker host: specify
+a set of env vars working for your setup::
+
+    $ docker run -ti --rm --volume `pwd`:/src --workdir /src \
+      -e PSYCOPG_TEST_DSN -e PGHOST=172.17.0.1 -e PGUSER=`whoami` \
+      python:3.7 bash
+
+    # pip install -e "./psycopg[test]" ./psycopg_pool ./psycopg_c
+    # pytest
+
+
+Testing with CockroachDB
+========================
+
+You can run CRDB in a docker container using::
+
+    docker run -p 26257:26257 --name crdb --rm \
+        cockroachdb/cockroach:v22.1.3 start-single-node --insecure
+
+And use the following connection string to run the tests::
+
+    export PSYCOPG_TEST_DSN="host=localhost port=26257 user=root dbname=defaultdb"
+    pytest ...