Merge branch 'master' of github.com:gabrielfalcao/sure

CHANGELOG.md

@@ -4,7 +4,11 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
-*Nothing to release yet*
+*Nothing here yet.*
+
+## [v1.4.2]
+### Added
+- `ensure` context manager to provide custom assertion messages. Refs #125
 
 ## [v1.4.1]
 ### Added
@@ -41,7 +45,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 Please see `git log`
 
-[Unreleased]: https://github.com/gabrielfalcao/sure/compare/v1.4.1...HEAD
+[Unreleased]: https://github.com/gabrielfalcao/sure/compare/v1.4.2...HEAD
+[v1.4.2]: https://github.com/gabrielfalcao/sure/compare/1.4.1...v1.4.2
 [v1.4.1]: https://github.com/gabrielfalcao/sure/compare/1.4.0...v1.4.1
 [v1.4.0]: https://github.com/gabrielfalcao/sure/compare/1.3.0...v1.4.0
 [v1.3.0]: https://github.com/gabrielfalcao/sure/compare/1.2.9...v1.3.0

README.rst

@@ -17,7 +17,7 @@ Installing
 Documentation
 -------------
 
-Available in the `website <https://sure.readthedocs.io>`__ or under the
+Available in the `website <https://sure.readthedocs.io/en/latest/>`__ or under the
 ``docs`` directory.
 
 You can also build the documentation locally using sphinx:

docs/source/api-reference.rst

@@ -803,7 +803,7 @@ Add custom assertions, chains and chain properties
 ``sure`` allows to add custom assertion methods, chain methods and chain properties.
 
 Custom assertion methods
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 By default ``sure`` comes with a good amount of *assertion methods*. For example:
 
@@ -853,7 +853,7 @@ I'll admit you have to write the assertion method yourself, but the result is a
 
 
 Chain methods
--------------
+~~~~~~~~~~~~~
 
 *chain methods* are similar to *assertion methods*. The only difference is that the *chain methods*, as the name implies, can be chained with further chains or assertions:
 
@@ -874,7 +874,7 @@ Chain methods
 
 
 Chain properties
-----------------
+~~~~~~~~~~~~~~~~
 
 *chain properties* are simple properties which are available to build an assertion.
 Some of the default chain properties are:
@@ -919,3 +919,23 @@ Use the ``chainproperty`` decorator like the following to build your own *chain*
    # Build awesome assertion chains
    expect(Foo).having.attribute('magic')
    Foo.doesnt.implement.attribute('nomagic')
+
+Use custom assertion messages with ``ensure``
+---------------------------------------------
+
+With the ``ensure`` context manager *sure* provides an easy to use way to override the ``AssertionError`` message raised by ``sure``'s assertion methods. See the following example:
+
+.. code:: python
+
+    import sure
+
+    name = myapi.do_something_that_returns_string()
+
+    with sure.ensure('the return value actually looks like: {0}', name):
+        name.should.contain('whatever')
+
+
+In case ``name`` does not contain the string ``whatever`` it will raise an ``AssertionError`` exception
+with the message *the return value actually looks like: <NAME>* (where *<NAME>* would be the actual value of the variable ``name``) instead of *sure*'s default error message in that particular case.
+
+Only ``AssertionError`` exceptions are re-raised by ``sure.ensure()`` with the custom provided message. Every other exception will be ignored and handled as expected.

docs/source/conf.py

@@ -64,9 +64,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.4.1'
+version = '1.4.2'
 # The full version, including alpha/beta/rc tags.
-release = '1.4.1'
+release = '1.4.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

sure/__init__.py

@@ -48,7 +48,7 @@
 if not PY2:
     basestring = str
 
-version = '1.4.1'
+version = '1.4.2'
 
 
 not_here_error = \
@@ -941,6 +941,34 @@ def chainproperty(func):
     return func
 
 
+class ensure(object):
+    """
+    Contextmanager to ensure that the given assertion message
+    is printed upon a raised ``AssertionError`` exception.
+
+    The ``args`` and ``kwargs`` are used to format
+    the message using ``format()``.
+    """
+    def __init__(self, msg, *args, **kwargs):
+        self.msg = msg
+        self.args = args
+        self.kwargs = kwargs
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        """
+        Catch all ``AsertionError`` exceptions and reraise
+        them with the message provided to the context manager.
+        """
+        if exc_type is not AssertionError:
+            return
+
+        msg = self.msg.format(*self.args, **self.kwargs)
+        raise AssertionError(msg)
+
+
 allows_new_syntax = not os.getenv('SURE_DISABLE_NEW_SYNTAX')
 
 

tests/test_ensure_ctxmgr.py

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+
+import sure
+
+
+def test_ensure_simple_assertion():
+    """Test ensure simple assertion"""
+
+    def __test_something():
+        # same calculated value
+        name = 'Hodor'
+        with sure.ensure('the return value actually looks like: {0}', name):
+            sure.expect(name).should.contain('whatever')
+
+
+    # check if the test function raises the custom AssertionError
+    sure.expect(__test_something).when.called_with().should.throw(AssertionError, \
+                                                                  'the return value actually looks like: Hodor')
+
+
+def test_ensure_just_assertion_error():
+    """Test that ensure only captures AssertionErrors"""
+    def __test_something():
+        # same calculated value
+        with sure.ensure('neverused'):
+            raise Exception('This is not an AssertionError')
+
+
+    # check if the test function does not override the original exception
+    # if it is not an AssertionError exception
+    sure.expect(__test_something).when.called_with().should.throw(Exception, \
+                                                                  'This is not an AssertionError')