add documentation on test setup

readthedocs/developing/testing.rst

@@ -0,0 +1,87 @@
+=====
+Tests
+=====
+
+Telethon uses `Pytest <https://pytest.org/>`__, for testing, `Tox
+<https://tox.readthedocs.io/en/latest/>`__ for environment setup, and
+`pytest-asyncio <https://pypi.org/project/pytest-asyncio/>`__ and `pytest-cov
+<https://pytest-cov.readthedocs.io/en/latest/>`__ for asyncio and 
+`coverage <https://coverage.readthedocs.io/>`__ integration.
+
+While reading the full documentation for these is probably a good idea, there
+is a lot to read, so a brief summary of these tools is provided below for
+convienience.
+
+Brief Introduction to Pytest
+============================
+
+`Pytest <https://pytest.org/>`__ is a tool for discovering and running python
+tests, as well as allowing modular reuse of test setup code using fixtures.
+
+Most Pytest tests will look something like this::
+
+    from module import my_thing, my_other_thing
+
+    def test_my_thing(fixture):
+        assert my_thing(fixture) == 42
+
+    @pytest.mark.asyncio
+    async def test_my_thing(event_loop):
+        assert await my_other_thing(loop=event_loop) == 42
+
+Note here:
+
+ 1. The test imports one specific function. The role of unit tests is to test
+    that the implementation of some unit, like a function or class, works.
+    It's role is not so much to test that components interact well with each
+    other. I/O, such as connecting to remote servers, should be avoided. This
+    helps with quickly identifying the source of an error, finding silent
+    breakage, and makes it easier to cover all possible code paths.
+
+    System or integration tests can also be useful, but are currently out of
+    scope of Telethon's automated testing.
+
+ 2. A function ``test_my_thing`` is declared. Pytest searches for files
+    starting with ``test_``, classes starting with ``Test`` and executes any
+    functions or methods starting with ``test_`` it finds.
+
+ 3. The function is declared with a parameter ``fixture``. Fixtures are used to
+    request things required to run the test, such as temporary directories,
+    free TCP ports, Connections, etc. Fixtures are declared by simply adding
+    the fixture name as parameter. A full list of available fixtures can be
+    found with the ``pytest --fixtures`` command.
+
+ 4. The test uses a simple ``assert`` to test some condition is valid.  Pytest
+    uses some magic to ensure that the errors from this are readable and easy
+    to debug.
+
+ 5. The ``pytest.mark.asyncio`` fixture is provided by ``pytest-asyncio``. It
+    starts a loop and executes a test function as coroutine. This should be
+    used for testing asyncio code. It also declares the ``event_loop``
+    fixture, which will request an ``asyncio`` event loop.
+
+Brief Introduction to Tox
+=========================
+
+`Tox <https://tox.readthedocs.io/en/latest/>`__ is a tool for automated setup
+of virtual environments for testing. While the tests can be run directly by
+just running ``pytest``, this only tests one specific python version in your
+existing environment, which will not catch e.g. undeclared dependencies, or
+version incompatabilities.
+
+Tox environments are declared in the ``tox.ini`` file. The default
+environments, declared at the top, can be simply run with ``tox``. The option
+``tox -e py36,flake`` can be used to request specific environments to be run.
+
+Brief Introduction to Pytest-cov
+================================
+
+Coverage is a useful metric for testing. It measures the lines of code and
+branches that are exercised by the tests. The higher the coverage, the more
+likely it is that any coding errors will be caught by the tests.
+
+A brief coverage report can be generated with the ``--cov`` option to ``tox``,
+which will be passed on to ``pytest``. Additionally, the very useful HTML
+report can be generated with ``--cov --cov-report=html``, which contains a
+browsable copy of the source code, annotated with coverage information for each
+line.

readthedocs/index.rst

@@ -93,6 +93,7 @@ You can also use the menu on the left to quickly skip over sections.
     developing/test-servers.rst
     developing/project-structure.rst
     developing/coding-style.rst
+    developing/testing.rst
     developing/understanding-the-type-language.rst
     developing/tips-for-porting-the-project.rst
     developing/telegram-api-in-other-languages.rst