added tester app (piccolo-orm#187)

* added tester app

* reset PICCOLO_CONF once the tests complete

* added an additional test for when an exception is raised in the context manager body

* add a test for the `tester run` command

* added docs

* make it more obvious how to send multiple args to pytest

Author: dantownsend

docs/src/piccolo/engines/index.rst

@@ -61,6 +61,8 @@ Here's an example ``piccolo_conf.py`` file:
 .. hint:: A good place for your piccolo_conf file is at the root of your
     project, where the Python interpreter will be launched.
 
+.. _PICCOLO_CONF:
+
 PICCOLO_CONF environment variable
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/src/piccolo/projects_and_apps/included_apps.rst

@@ -101,6 +101,39 @@ need to run raw SQL queries on your database.
 For it to work, the underlying command needs to be on the path (i.e. ``psql``
 or ``sqlite3`` depending on which you're using).
 
+tester
+~~~~~~
+
+Launches `pytest <https://pytest.org/>`_ , which runs your unit test suite. The
+advantage of using this rather than running ``pytest`` directly, is the
+``PICCOLO_CONF`` environment variable will automatically be set before the
+testing starts, and will be restored to it's initial value once the tests
+finish.
+
+.. code-block:: bash
+
+    piccolo tester run
+
+Setting the :ref:`PICCOLO_CONF<PICCOLO_CONF>` environment variable means your
+code will use the database engine specified in that file for the duration of
+the testing.
+
+By default ``piccolo tester run`` sets ``PICCOLO_CONF`` to
+``'piccolo_conf_test'``, meaning that a file called ``piccolo_conf_test.py``
+will be imported.
+
+If you prefer, you can set a custom ``PICCOLO_CONF`` value:
+
+.. code-block:: bash
+
+    piccolo tester run --piccolo_conf=my_custom_piccolo_conf
+
+You can also pass arguments to pytest:
+
+.. code-block:: bash
+
+    piccolo tester run --pytest_args="-s foo"
+
 -------------------------------------------------------------------------------
 
 Optional includes

piccolo/apps/tester/__init__.py

@@ -0,0 +1,71 @@
+import os
+import sys
+import typing as t
+
+from _pytest.config import ExitCode
+
+
+class set_env_var:
+    def __init__(self, var_name: str, temp_value: str):
+        """
+        Temporarily set an environment variable.
+
+        :param var_name:
+            The name of the environment variable to temporarily change.
+        :temp_value:
+            The value that the environment variable will temporarily be set to,
+            before being reset to it's pre-existing value.
+
+        """
+        self.var_name = var_name
+        self.temp_value = temp_value
+
+    def set_var(self, value: str):
+        os.environ[self.var_name] = value
+
+    def get_var(self) -> t.Optional[str]:
+        return os.environ.get(self.var_name)
+
+    def __enter__(self):
+        self.existing_value = self.get_var()
+        self.set_var(self.temp_value)
+
+    def __exit__(self, *args):
+        if self.existing_value is None:
+            del os.environ[self.var_name]
+        else:
+            self.set_var(self.existing_value)
+
+
+def run_pytest(
+    pytest_args: t.List[str],
+) -> t.Union[int, ExitCode]:  # pragma: no cover
+    try:
+        import pytest
+    except ImportError:
+        sys.exit(
+            "Couldn't find pytest. Please use `pip install 'piccolo[pytest]' "
+            "to use this feature."
+        )
+
+    return pytest.main(pytest_args)
+
+
+def run(
+    pytest_args: str = "", piccolo_conf: str = "piccolo_conf_test"
+) -> None:
+    """
+    Run your unit test suite using Pytest.
+
+    :param piccolo_conf:
+        The piccolo_conf module to use when running your tests. This will
+        contain the database settings you want to use. For example
+        `my_folder.piccolo_conf_test`.
+    :param pytest_args:
+        Any options you want to pass to Pytest. For example
+        `piccolo tester run --pytest_args="-s"`.
+
+    """
+    with set_env_var(var_name="PICCOLO_CONF", temp_value=piccolo_conf):
+        args = pytest_args.split(" ")
+        sys.exit(run_pytest(args))

piccolo/apps/tester/commands/__init__.py

@@ -0,0 +1,11 @@
+from piccolo.conf.apps import AppConfig
+
+from .commands.run import run
+
+APP_CONFIG = AppConfig(
+    app_name="tester",
+    migrations_folder_path="",
+    table_classes=[],
+    migration_dependencies=[],
+    commands=[run],
+)

piccolo/apps/tester/commands/run.py

@@ -20,6 +20,7 @@
 from piccolo.apps.schema.piccolo_app import APP_CONFIG as schema_config
 from piccolo.apps.shell.piccolo_app import APP_CONFIG as shell_config
 from piccolo.apps.sql_shell.piccolo_app import APP_CONFIG as sql_shell_config
+from piccolo.apps.tester.piccolo_app import APP_CONFIG as tester_config
 from piccolo.apps.user.piccolo_app import APP_CONFIG as user_config
 from piccolo.conf.apps import AppRegistry, Finder
 from piccolo.utils.sync import run_sync
@@ -66,6 +67,7 @@ def main():
         schema_config,
         shell_config,
         sql_shell_config,
+        tester_config,
         user_config,
     ]:
         for command in _app_config.commands:

piccolo/apps/tester/piccolo_app.py

@@ -0,0 +1 @@
+pytest

piccolo/main.py

@@ -0,0 +1,73 @@
+import os
+from unittest import TestCase
+from unittest.mock import MagicMock, patch
+
+from piccolo.apps.tester.commands.run import run, set_env_var
+
+
+class TestSetEnvVar(TestCase):
+    def test_no_existing_value(self):
+        """
+        Make sure the environment variable is set correctly, when there is
+        no existing value.
+        """
+        var_name = "PICCOLO_TEST_1"
+
+        # Make sure it definitely doesn't exist already
+        if os.environ.get(var_name) is not None:
+            del os.environ[var_name]
+
+        new_value = "hello world"
+
+        with set_env_var(var_name=var_name, temp_value=new_value):
+            self.assertEqual(os.environ.get(var_name), new_value)
+
+        self.assertEqual(os.environ.get(var_name), None)
+
+    def test_existing_value(self):
+        """
+        Make sure the environment variable is set correctly, when there is
+        an existing value.
+        """
+        var_name = "PICCOLO_TEST_2"
+        initial_value = "hello"
+        new_value = "goodbye"
+
+        os.environ[var_name] = initial_value
+
+        with set_env_var(var_name=var_name, temp_value=new_value):
+            self.assertEqual(os.environ.get(var_name), new_value)
+
+        self.assertEqual(os.environ.get(var_name), initial_value)
+
+    def test_raise_exception(self):
+        """
+        Make sure the environment variable is still reset, even if an exception
+        is raised within the context manager body.
+        """
+        var_name = "PICCOLO_TEST_3"
+        initial_value = "hello"
+        new_value = "goodbye"
+
+        os.environ[var_name] = initial_value
+
+        class FakeException(Exception):
+            pass
+
+        try:
+            with set_env_var(var_name=var_name, temp_value=new_value):
+                self.assertEqual(os.environ.get(var_name), new_value)
+                raise FakeException("Something went wrong ...")
+        except FakeException:
+            pass
+
+        self.assertEqual(os.environ.get(var_name), initial_value)
+
+
+class TestRun(TestCase):
+    @patch("piccolo.apps.tester.commands.run.run_pytest")
+    def test_success(self, pytest: MagicMock):
+        with self.assertRaises(SystemExit):
+            run(pytest_args="-s foo", piccolo_conf="my_piccolo_conf")
+
+        pytest.assert_called_once_with(["-s", "foo"])