Using Pytest
============

So, you already have ``dpytest`` installed, and can import it. However, setting up a client for every test is
a pain. The library is designed to work well with ``pytest`` (Thus the name), and it can make writing tests much
easier. In the following tutorial we'll show how to set it up.

Starting with Pytest
--------------------

``pytest`` can be installed through pip the same way ``dpytest`` is. Once that's done, using it is as easy
as:

- Windows: ``py -m pytest``
- Linux: ``python3 -m pytest``

``pytest`` will detect any functions starting with 'test' in directories it searches, and run them. It also supports
a feature we will use heavily, called 'fixtures'. Fixtures are functions that do some common test setup, and
then can be used in tests to always perform that setup. They can also return an object that will be passed to
the test.

The final piece of this is ``pytest-asyncio``, a library for allowing ``pytest`` to run async tests. It is
automatically installed when you get ``dpytest`` from pip, so you don't need to worry about installing it.

Putting all this together, we can rewrite our previous tests to look like this:

.. code:: python

    import pytest
    import discord.ext.test as dpytest


    @pytest.fixture
    def bot():
        bot = ... # However you create your bot
        dpytest.configure(bot)
        return bot


    @pytest.mark.asyncio
    async def test_ping(bot):
        await dpytest.message("!ping")
        dpytest.verify_message("Ping:", contains=True)


    @pytest.mark.asyncio
    async def test_foo(bot):
        await dpytest.message("!hello")
        dpytest.verify_message("Hello World!")

Much less writing the same code over and over again, and tests will be automatically run by pytest, then the results
output in a nice pretty format once it's done.

What is conftest.py?
--------------------

As you write tests, you may want to split them into multiple files. One file for testing this cog, another for
ensuring reactions work right. As it stands, you'll still need to copy your bot fixture into every file. To fix this,
you need to create a file named ``conftest.py`` at the root of where you're putting your tests. If you haven't already,
you should probably put them all in their own directory. Then you can put any fixtures you want in ``conftest.py``,
and pytest will let you use them in any other test file. ``pytest`` also recognizes certain function names with
special meanings, for example ``pytest_sessionfinish`` will be run after all tests are done if defined in your conftest.

An example ``conftest.py`` might look like this:

.. code:: python

    import pytest
    import discord.ext.test as dpytest


    @pytest.fixture
    def bot():
        bot = ... # However you create your bot
        dpytest.configure(bot)
        return bot


    def pytest_sessionfinish():
        # Clean up attachment files
        fileList = glob.glob('./dpytest_*.dat')
        for filePath in fileList:
            try:
                os.remove(filePath)
            except Exception:
                print("Error while deleting file : ", filePath)

With that, you should be ready to use ``dpytest`` with your bot.


This is currently the end of the tutorials. Take a look at the `Runner Documentation`_ to see all the things you can
do with ``dpytest``.

.. _Runner Documentation: ../modules/runner.html