add test documentation

1 files changed, 40 insertions, 0 deletions

diff --git a/tests/README.markdown b/tests/README.markdown
new file mode 100644
index 0000000..ad27a31
--- /dev/null
+++ b/tests/README.markdown
@@ -0,0 +1,40 @@
+## Running
+
+To run this test suite, install the testing dependencies:
+
+    pip install -e .[test]
+
+Then, run `pytest`.
+
+If you wish to check test coverage:
+
+    pytest --cov=mastodon
+
+And if you want a complete HTML coverage report:
+
+    pytest --cov=mastodon --cov-report html:coverage
+    # then open coverage/index.html in your favourite web browser
+
+
+## Contributing
+
+[VCR.py]: https://vcrpy.readthedocs.io/
+
+This test suite uses [VCR.py][] to record requests to Mastodon and replay them in successive runs.
+
+If you want to add or change tests, you will need a Mastodon development server running on `http://localhost:3000`, with the default `admin` user and default password.
+
+It also needs a test OAuth app to be set up by applying the provided `setup_app.sql` to Mastodon's database:
+
+    psql -d mastodon_development < tests/setup_app.sql
+
+Tests that send requests to Mastodon should be marked as needing VCR with the `pytest.mark.vcr` decorator.
+
+```python
+import pytest
+
+@pytest.mark.vcr()
+def test_fun_new_feature(api):
+    foo = api.fun_new_feature()
+    assert foo = "bar"
+```