Skip to content

robot.utils.asserts

Convenience functions for testing both in unit and higher levels.

Benefits
  • Integrates 100% with unittest (see example below)
  • Can be easily used without unittest (using unittest.TestCase when you only need convenient asserts is not so nice)
  • Saved typing and shorter lines because no need to have 'self.' before asserts. These are static functions after all so that is OK.
  • All 'equals' methods (by default) report given values even if optional message given. This behavior can be controlled with the optional values argument.
Drawbacks
  • unittest is not able to filter as much non-interesting traceback away as with its own methods because AssertionErrors occur outside.

Most of the functions are copied more or less directly from unittest.TestCase which comes with the following license. Further information about unittest in general can be found from http://pyunit.sourceforge.net/. This module can be used freely in same terms as unittest.

unittest license::

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
Copyright (c) 1999-2003 Steve Purcell
This module is free software, and you may redistribute it and/or modify
it under the same terms as Python itself, so long as this copyright message
and disclaimer are retained in their original form.

IN NO EVENT SHALL THE AUTHOR BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF
THIS CODE, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.

THE AUTHOR SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE.  THE CODE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS,
AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

Examples::

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import unittest
from robot.utils.asserts import assert_equal

class MyTests(unittest.TestCase):

    def test_old_style(self):
        self.assertEqual(1, 2, 'my msg')

    def test_new_style(self):
        assert_equal(1, 2, 'my msg')

Example output::

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
FF
======================================================================
FAIL: test_old_style (example.MyTests)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "example.py", line 7, in test_old_style
    self.assertEqual(1, 2, 'my msg')
AssertionError: my msg

======================================================================
FAIL: test_new_style (example.MyTests)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "example.py", line 10, in test_new_style
    assert_equal(1, 2, 'my msg')
  File "/path/to/robot/utils/asserts.py", line 181, in assert_equal
    _report_inequality_failure(first, second, msg, values, '!=')
  File "/path/to/robot/utils/asserts.py", line 229, in _report_inequality_failure
    raise AssertionError(msg)
AssertionError: my msg: 1 != 2

----------------------------------------------------------------------
Ran 2 tests in 0.000s

FAILED (failures=2)

fail 

1
fail(msg=None)

Fail test immediately with the given message.

Source code in src/robot/utils/asserts.py 
101
102
103
def fail(msg=None):
    """Fail test immediately with the given message."""
    _report_failure(msg)

assert_false 

1
assert_false(expr, msg=None)

Fail the test if the expression is True.

Source code in src/robot/utils/asserts.py 
106
107
108
109
def assert_false(expr, msg=None):
    """Fail the test if the expression is True."""
    if expr:
        _report_failure(msg)

assert_true 

1
assert_true(expr, msg=None)

Fail the test unless the expression is True.

Source code in src/robot/utils/asserts.py 
112
113
114
115
def assert_true(expr, msg=None):
    """Fail the test unless the expression is True."""
    if not expr:
        _report_failure(msg)

assert_not_none 

1
assert_not_none(obj, msg=None, values=True)

Fail the test if given object is None.

Source code in src/robot/utils/asserts.py 
118
119
120
121
122
123
124
125
126
def assert_not_none(obj, msg=None, values=True):
    """Fail the test if given object is None."""
    _msg = 'is None'
    if obj is None:
        if msg is None:
            msg = _msg
        elif values is True:
            msg = '%s: %s' % (msg, _msg)
        _report_failure(msg)

assert_none 

1
assert_none(obj, msg=None, values=True)

Fail the test if given object is not None.

Source code in src/robot/utils/asserts.py 
129
130
131
132
133
134
135
136
137
def assert_none(obj, msg=None, values=True):
    """Fail the test if given object is not None."""
    _msg = '%r is not None' % obj
    if obj is not None:
        if msg is None:
            msg = _msg
        elif values is True:
            msg = '%s: %s' % (msg, _msg)
        _report_failure(msg)

assert_raises 

1
assert_raises(exc_class, callable_obj, *args, **kwargs)

Fail unless an exception of class exc_class is thrown by callable_obj.

callable_obj is invoked with arguments args and keyword arguments kwargs. If a different type of exception is thrown, it will not be caught, and the test case will be deemed to have suffered an error, exactly as for an unexpected exception.

If a correct exception is raised, the exception instance is returned by this method.

Source code in src/robot/utils/asserts.py 
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
def assert_raises(exc_class, callable_obj, *args, **kwargs):
    """Fail unless an exception of class exc_class is thrown by callable_obj.

    callable_obj is invoked with arguments args and keyword arguments
    kwargs. If a different type of exception is thrown, it will not be
    caught, and the test case will be deemed to have suffered an
    error, exactly as for an unexpected exception.

    If a correct exception is raised, the exception instance is returned
    by this method.
    """
    try:
        callable_obj(*args, **kwargs)
    except exc_class as err:
        return err
    else:
        if hasattr(exc_class,'__name__'):
            exc_name = exc_class.__name__
        else:
            exc_name = str(exc_class)
        _report_failure('%s not raised' % exc_name)

assert_raises_with_msg 

1
2
3
assert_raises_with_msg(
    exc_class, expected_msg, callable_obj, *args, **kwargs
)

Similar to fail_unless_raises but also checks the exception message.

Source code in src/robot/utils/asserts.py 
163
164
165
166
167
168
169
170
171
172
173
174
175
def assert_raises_with_msg(exc_class, expected_msg, callable_obj, *args,
                           **kwargs):
    """Similar to fail_unless_raises but also checks the exception message."""
    try:
        callable_obj(*args, **kwargs)
    except exc_class as err:
        assert_equal(expected_msg, str(err), 'Correct exception but wrong message')
    else:
        if hasattr(exc_class,'__name__'):
            exc_name = exc_class.__name__
        else:
            exc_name = str(exc_class)
        _report_failure('%s not raised' % exc_name)

assert_equal 

1
2
3
assert_equal(
    first, second, msg=None, values=True, formatter=safe_str
)

Fail if given objects are unequal as determined by the '==' operator.

Source code in src/robot/utils/asserts.py 
178
179
180
181
def assert_equal(first, second, msg=None, values=True, formatter=safe_str):
    """Fail if given objects are unequal as determined by the '==' operator."""
    if not first == second:
        _report_inequality(first, second, '!=', msg, values, formatter)

assert_not_equal 

1
2
3
assert_not_equal(
    first, second, msg=None, values=True, formatter=safe_str
)

Fail if given objects are equal as determined by the '==' operator.

Source code in src/robot/utils/asserts.py 
184
185
186
187
def assert_not_equal(first, second, msg=None, values=True, formatter=safe_str):
    """Fail if given objects are equal as determined by the '==' operator."""
    if first == second:
        _report_inequality(first, second, '==', msg, values, formatter)

assert_almost_equal 

1
2
3
assert_almost_equal(
    first, second, places=7, msg=None, values=True
)

Fail if the two objects are unequal after rounded to given places.

inequality is determined by object's difference rounded to the given number of decimal places (default 7) and comparing to zero. Note that decimal places (from zero) are usually not the same as significant digits (measured from the most significant digit).

Source code in src/robot/utils/asserts.py 
190
191
192
193
194
195
196
197
198
199
200
def assert_almost_equal(first, second, places=7, msg=None, values=True):
    """Fail if the two objects are unequal after rounded to given places.

    inequality is determined by object's difference rounded to the
    given number of decimal places (default 7) and comparing to zero.
    Note that decimal places (from zero) are usually not the same as
    significant digits (measured from the most significant digit).
    """
    if round(second - first, places) != 0:
        extra = 'within %r places' % places
        _report_inequality(first, second, '!=', msg, values, extra=extra)

assert_not_almost_equal 

1
2
3
assert_not_almost_equal(
    first, second, places=7, msg=None, values=True
)

Fail if the two objects are unequal after rounded to given places.

Equality is determined by object's difference rounded to to the given number of decimal places (default 7) and comparing to zero. Note that decimal places (from zero) are usually not the same as significant digits (measured from the most significant digit).

Source code in src/robot/utils/asserts.py 
203
204
205
206
207
208
209
210
211
212
213
def assert_not_almost_equal(first, second, places=7, msg=None, values=True):
    """Fail if the two objects are unequal after rounded to given places.

    Equality is determined by object's difference rounded to to the
    given number of decimal places (default 7) and comparing to zero.
    Note that decimal places (from zero) are usually not the same as
    significant digits (measured from the most significant digit).
    """
    if round(second-first, places) == 0:
        extra = 'within %r places' % places
        _report_inequality(first, second, '==', msg, values, extra=extra)