Improves testing by providing a contextmanager

Author: sdispater

docs/index.rst

@@ -946,6 +946,68 @@ It moves your instance to the middle date between itself and the provided Pendul
     # first_of(), last_of(), nth_of()
 
 
+Testing
+=======
+
+The testing methods allow you to set a ``Pendulum`` instance (real or mock) to be returned
+when a "now" instance is created.
+The provided instance will be returned specifically under the following conditions:
+
+* A call to the ``now()`` method, ex. ``pendulum.now()``.
+* When the string "now" is passed to the ``parse()``, ex. ``pendulum.parse('now')``
+
+.. code-block:: python
+
+    import pendulum
+
+    # Create testing datetime
+    known = pendulum.create(2001, 5, 21, 12)
+
+    # Set the mock
+    pendulum.set_test_now(known)
+
+    print(pendulum.now())
+    '2001-05-21T12:00:00+00:00'
+
+    print(pendulum.parse('now'))
+    '2001-05-21T12:00:00+00:00'
+
+    # Clear the mock
+    pendulum.set_test_now()
+
+    print(pendulum.now())
+    '2016-07-10T22:10:33.954851-05:00'
+
+Related methods will also returned values mocked according to the *now* instance.
+
+.. code-block:: python
+
+    print(pendulum.today())
+    '2001-05-21T00:00:00+00:00'
+
+    print(pendulum.tomorrow())
+    '2001-05-22T00:00:00+00:00'
+
+    print(pendulum.yesterday())
+    '2001-05-20T00:00:00+00:00'
+
+If you don't want to manually clear the mock (or you are afraid of forgetting),
+you can use the provided ``test()`` contextmanager.
+
+.. code-block:: python
+
+    import pendulum
+
+    known = pendulum.create(2001, 5, 21, 12)
+
+    with pendulum.test(known):
+        print(pendulum.now())
+        '2001-05-21T12:00:00+00:00'
+
+    print(pendulum.now())
+    '2016-07-10T22:10:33.954851-05:00'
+
+
 Constants
 =========
 

pendulum/pendulum.py

@@ -11,10 +11,10 @@
 import tzlocal
 import datetime
 
+from contextlib import contextmanager
 from pytz.tzinfo import BaseTzInfo, tzinfo
 from dateutil.relativedelta import relativedelta
 from dateutil import parser as dateparser
-from dateutil.tz import tzoffset
 
 from .translator import Translator
 
@@ -757,6 +757,20 @@ def set_weekend_days(cls, value):
 
     # Testing aids
 
+    @classmethod
+    @contextmanager
+    def test(cls, mock):
+        """
+        Context manager to temporarily set the test_now value.
+
+        :type mock: Pendulum or None
+        """
+        cls.set_test_now(mock)
+
+        yield
+
+        cls.set_test_now()
+
     @classmethod
     def set_test_now(cls, test_now=None):
         """

tests/pendulum_tests/test_testing_aids.py

@@ -38,3 +38,11 @@ def test_parse_with_test_value_set(self):
 
         self.assertEqual(test_now, Pendulum.parse())
         self.assertEqual(test_now, Pendulum.parse('now'))
+
+    def test_context_manager(self):
+        test_now = Pendulum.yesterday()
+
+        with Pendulum.test(test_now):
+            self.assertEqual(test_now, Pendulum.now())
+
+        self.assertNotEqual(test_now, Pendulum.now())