Merge branch '120-test-with-request-context'

Author: guruofgentoo

docs/source/index.rst

@@ -21,6 +21,7 @@ Contents
    component
    utils
    signals
+   testing
    web
    readme/features
    readme/configuration

docs/source/signals.rst

@@ -4,7 +4,7 @@ Signals
 As Keg is based on Flask architecture, signals are used to set up and execute callback
 methods upon certain events.
 
-Attaching a callback to a signal involves the connect decorator:
+Attaching a callback to a signal involves the connect decorator::
 
     from keg.signals import init_complete
 
@@ -29,17 +29,17 @@ Keg Events
 
   - App config has been loaded
   - Config is the first property of the app to be initialized. `app.config` will be available,
-  but do not count on anything else.
+    but do not count on anything else.
 
 * `db_before_import`
 
   - Database options have been configured, and the app is about to visit modules containing
-  entities
+    entities
   - Config, logging, and error handling have been loaded, but no other extensions
   - Some SQLAlchemy metadata attributes, such as naming convention, need to be set prior to
-  entities loading. Attaching a method on this signal is an ideal way to set these properties.
+    entities loading. Attaching a method on this signal is an ideal way to set these properties.
   - If customization of the db object, metadata, engine options, etc. is needed, ensure that
-  no modules containing entities are imported before the connected callback runs.
+    no modules containing entities are imported before the connected callback runs.
 
 * `testing_run_start`
 
@@ -50,4 +50,4 @@ Keg Events
 * `db_clear_pre`, `db_clear_post`, `db_init_pre`, `db_init_post`
 
   - Called during the database initialization process, which occurs in test setup and from CLI
-  commands
+    commands

docs/source/testing.rst

@@ -0,0 +1,5 @@
+Testing Utils
+=============
+
+.. automodule:: keg.testing
+    :members:

keg/testing.py

@@ -7,6 +7,7 @@
 import flask
 import six
 from flask_webtest import TestApp
+from werkzeug.datastructures import ImmutableMultiDict, MultiDict
 
 from keg import current_app, signals
 from keg.utils import app_environ_get
@@ -22,6 +23,10 @@ def _config_profile(appcls):
 class ContextManager(object):
     """
         Facilitates having a single instance of an application ready for testing.
+
+        By default, this is used in ``Keg.testing_prep``.
+
+        Constructor arg is the Keg app class to manage for tests.
     """
     apps = {}
 
@@ -31,6 +36,7 @@ def __init__(self, appcls):
         self.ctx = None
 
     def ensure_current(self, config):
+        """Ensure the manager's app has an instance set as flask's ``current_app``"""
 
         if not self.app:
             self.app = self.appcls().init(use_test_profile=True, config=config)
@@ -43,9 +49,16 @@ def ensure_current(self, config):
         return self.app
 
     def cleanup(self):
+        """Pop the app context"""
         self.ctx.pop()
 
     def is_ready(self):
+        """Indicates the manager's app instance exists.
+
+        The instance should be created with ``get_for``. Only one ContextManager instance will get
+        created in a Python process for any given app. But, ``get_for`` may be called multiple
+        times. The first call to ``ensure_current`` will set up the application and bring the
+        manager to a ready state."""
         return self.app is not None
 
     @classmethod
@@ -63,17 +76,18 @@ def get_for(cls, appcls):
 def app_config(**kwargs):
     """
         Set config values on any apps instantiated while the context manager is active.
-        This is intended to be used with cli tests where the `current_app` in the test will be
-        different from the `current_app` when the CLI command is invoked, making it very difficult
+        This is intended to be used with cli tests where the ``current_app`` in the test will be
+        different from the ``current_app`` when the CLI command is invoked, making it very difficult
         to dynamically set app config variables using mock.patch.dict like we normally would.
+
         Example::
 
-        class TestCLI(CLIBase):
-            app_cls = MyApp
-            def test_it(self):
-                with testing.app_config(FOO_NAME='Bar'):
-                    result = self.invoke('echo-foo-name')
-                assert 'Bar' in result.output
+            class TestCLI(CLIBase):
+                app_cls = MyApp
+                def test_it(self):
+                    with testing.app_config(FOO_NAME='Bar'):
+                        result = self.invoke('echo-foo-name')
+                    assert 'Bar' in result.output
     """
     @signals.config_complete.connect
     def set_config(app):
@@ -82,7 +96,57 @@ def set_config(app):
     yield
 
 
+@contextlib.contextmanager
+def inrequest(*req_args, args_modifier=None, **req_kwargs):
+    """A decorator/context manager to add the flask request context to a test function.
+
+    Allows test to assume a request context without running a full view stack. Use for
+    unit-testing a view instance without setting up a webtest instance for the app and
+    running requests.
+
+    Flask's ``request.args`` is normally immutable, but in test cases, it can be helpful to
+    patch in args without needing to construct the URL. But, we don't want to leave them
+    mutable, because potential app bugs could be masked in doing so. To modify args, pass
+    in a callable as ``args_modifier`` that takes the args dict to be modified in-place. Args
+    will only be mutable for executing the modifier, then returned to immutable for the
+    remainder of the scope.
+
+    Assumes that ``flask.current_app`` is pointing to the desired app.
+
+    Example::
+
+        @inrequest('/mypath?foo=bar&baz=boo')
+        def test_in_request_args(self):
+            assert flask.request.args['foo'] == 'bar'
+
+        def test_request_args_mutated(self):
+            def args_modifier(args_dict):
+                args_dict['baz'] = 'custom-value'
+
+            with inrequest('/mypath?foo=bar&baz=boo', args_modifier=args_modifier):
+                assert flask.request.args['foo'] == 'bar'
+                assert flask.request.args['baz'] == 'custom-value'
+    """
+    with flask.current_app.test_request_context(*req_args, **req_kwargs):
+        if callable(args_modifier):
+            # Temporarily turn args into a mutable MultiDict to be patched. Then, we must
+            # be sure to turn them back immutable, or else tests may end up not catching
+            # bugs that attempt to modify request args improperly.
+            new_args = MultiDict(flask.request.args)
+            args_modifier(new_args)
+            flask.request.args = ImmutableMultiDict(new_args)
+
+        yield
+
+
 def invoke_command(app_cls, *args, **kwargs):
+    """Invoke a command using a CLI runner and return the result.
+
+    Optional kwargs:
+    - exit_code: Default 0. Process exit code to assert.
+    - runner: Default ``click.testing.CliRunner()``. CLI runner instance to use for invocation.
+    - use_test_profile: Default True. Drive invoked app to use test profile instead of default.
+    """
     exit_code = kwargs.pop('exit_code', 0)
     runner = kwargs.pop('runner', None) or click.testing.CliRunner()
     use_test_profile = kwargs.pop('use_test_profile', True)
@@ -107,6 +171,15 @@ def invoke_command(app_cls, *args, **kwargs):
 
 
 class CLIBase(object):
+    """Test class base for testing Keg click commands.
+
+    Creates a CLI runner instance, and allows subclass to call ``self.invoke`` with
+    command args.
+
+    Class attributes:
+    - app_cls: Optional, will default to ``flask.current_app`` class.
+    - cmd_name: Optional, provides default in ``self.invoke`` for ``cmd_name`` kwarg.
+    """
     # child classes will need to set these values in order to use the class
     app_cls = None
     cmd_name = None
@@ -116,6 +189,7 @@ def setup_class(cls):
         cls.runner = click.testing.CliRunner()
 
     def invoke(self, *args, **kwargs):
+        """Run a command, perform some assertions, and return the result for testing."""
         cmd_name = kwargs.pop('cmd_name', self.cmd_name)
         if cmd_name is None:
             cmd_name_args = []

keg/tests/test_utils.py

@@ -3,9 +3,12 @@
 import tempfile
 from unittest import mock
 
+import flask
 import pytest
 
+from keg.testing import inrequest
 from keg.utils import pymodule_fpaths_to_objects
+from keg_apps.web.app import WebApp
 
 
 class TestUtils(object):
@@ -45,3 +48,30 @@ def test_pymodule_fpaths_to_objects_error(self, m_open, error):
         assert fpath == 'some-path.py'
         assert fpath_objs is None
         assert isinstance(exc, error)
+
+
+class TestInRequest:
+    @classmethod
+    def setup_class(cls):
+        WebApp.testing_prep()
+
+    @inrequest('/mypath?foo=bar&baz=boo')
+    def test_in_request_args(self):
+        assert flask.request.args['foo'] == 'bar'
+
+    @inrequest('/mypath?foo=bar&baz=boo')
+    def test_request_args_immutable(self):
+        with pytest.raises(TypeError, match='immutable'):
+            flask.request.args['foo'] = 'moo'
+
+    def test_request_args_mutated(self):
+        def args_modifier(args_dict):
+            args_dict['baz'] = 'custom-value'
+
+        with inrequest('/mypath?foo=bar&baz=boo', args_modifier=args_modifier):
+            assert flask.request.args['foo'] == 'bar'
+            assert flask.request.args['baz'] == 'custom-value'
+
+            # ensure args return to immutable after patch
+            with pytest.raises(TypeError, match='immutable'):
+                flask.request.args['foo'] = 'moo'