Comparing objects and sequences¶
Python’s unittest
package often fails to give very useful
feedback when comparing long sequences or chunks of text. It also has
trouble dealing with objects that don’t natively support
comparison. The functions and classes described here alleviate these
problems.
The compare function¶
The compare()
function can be used as a replacement for
assertEqual()
. It raises an
AssertionError
when its parameters are not equal, which will be
reported as a test failure:
>>> from testfixtures import compare
>>> compare(1, 2)
Traceback (most recent call last):
...
AssertionError: 1 != 2
However, it allows you to specify a prefix for the message to be used in the event of failure:
>>> compare(1, 2, prefix='wrong number of orders')
Traceback (most recent call last):
...
AssertionError: wrong number of orders: 1 != 2
This is recommended as it makes the reason for the failure more apparent without having to delve into the code or tests.
You can also optionally specify a suffix, which will be appended to the message on a new line:
>>> compare(1, 2, suffix='(Except for very large values of 1)')
Traceback (most recent call last):
...
AssertionError: 1 != 2
(Except for very large values of 1)
The expected and actual value can also be explicitly supplied, making it clearer as to what has gone wrong:
>>> compare(expected=1, actual=2)
Traceback (most recent call last):
...
AssertionError: 1 (expected) != 2 (actual)
The real strengths of this function come when comparing more complex data types. A number of common python data types will give more detailed output when a comparison fails as described below:
sets¶
Comparing sets that aren’t the same will attempt to highlight where the differences lie:
>>> compare(set([1, 2]), set([2, 3]))
Traceback (most recent call last):
...
AssertionError: set not as expected:
in first but not second:
[1]
in second but not first:
[3]
dicts¶
Comparing dictionaries that aren’t the same will attempt to highlight where the differences lie:
>>> compare(dict(x=1, y=2, a=4), dict(x=1, z=3, a=5))
Traceback (most recent call last):
...
AssertionError: dict not as expected:
same:
['x']
in first but not second:
'y': 2
in second but not first:
'z': 3
values differ:
'a': 4 != 5
lists and tuples¶
Comparing lists or tuples that aren’t the same will attempt to highlight where the differences lie:
>>> compare([1, 2, 3], [1, 2, 4])
Traceback (most recent call last):
...
AssertionError: sequence not as expected:
same:
[1, 2]
first:
[3]
second:
[4]
namedtuples¶
When two namedtuple()
instances are compared, if
they are of the same type, the description given will highlight which
elements were the same and which were different:
>>> from collections import namedtuple
>>> TestTuple = namedtuple('TestTuple', 'x y z')
>>> compare(TestTuple(1, 2, 3), TestTuple(1, 4, 3))
Traceback (most recent call last):
...
AssertionError: TestTuple not as expected:
same:
['x', 'z']
values differ:
'y': 2 != 4
generators¶
When two generators are compared, they are both first unwound into tuples and those tuples are then compared.
The generator helper is useful for creating a generator to represent the expected results:
>>> from testfixtures import generator
>>> def my_gen(t):
... i = 0
... while i<t:
... i += 1
... yield i
>>> compare(generator(1, 2, 3), my_gen(2))
Traceback (most recent call last):
...
AssertionError: sequence not as expected:
same:
(1, 2)
first:
(3,)
second:
()
Warning
If you wish to assert that a function returns a generator, say, for performance reasons, then you should use strict comparison.
strings and unicodes¶
Comparison of strings can be tricky, particularly when those strings contain multiple lines; spotting the differences between the expected and actual values can be hard.
To help with this, long strings give a more helpful representation when comparison fails:
>>> compare("1234567891011", "1234567789")
Traceback (most recent call last):
...
AssertionError:
'1234567891011'
!=
'1234567789'
Likewise, multi-line strings give unified diffs when their comparison fails:
>>> compare("""
... This is line 1
... This is line 2
... This is line 3
... """,
... """
... This is line 1
... This is another line
... This is line 3
... """)
Traceback (most recent call last):
...
AssertionError:
--- first
+++ second
@@ -1,5 +1,5 @@
This is line 1
- This is line 2
+ This is another line
This is line 3
Such comparisons can still be confusing as white space is taken into account. If you need to care about whitespace characters, you can make spotting the differences easier as follows:
>>> compare("\tline 1\r\nline 2"," line1 \nline 2", show_whitespace=True)
Traceback (most recent call last):
...
AssertionError:
--- first
+++ second
@@ -1,2 +1,2 @@
-'\tline 1\r\n'
+' line1 \n'
'line 2'
However, you may not care about some of the whitespace involved. To
help with this, compare()
has two options that can be set to
ignore certain types of whitespace.
If you wish to compare two strings that contain blank lines or lines containing only whitespace characters, but where you only care about the content, you can use the following:
compare('line1\nline2', 'line1\n \nline2\n\n',
blanklines=False)
If you wish to compare two strings made up of lines that may have trailing whitespace that you don’t care about, you can do so with the following:
compare('line1\nline2', 'line1 \t\nline2 \n',
trailing_whitespace=False)
Recursive comparison¶
Where compare()
is able to provide a descriptive comparison for
a particular type, it will then recurse to do the same for the
elements contained within objects of that type.
For example, when comparing a list of dictionaries, the description
will not only tell you where in the list the difference occurred, but
also what the differences were within the dictionaries that weren’t
equal:
>>> compare([{'one': 1}, {'two': 2, 'text':'foo\nbar\nbaz'}],
... [{'one': 1}, {'two': 2, 'text':'foo\nbob\nbaz'}])
Traceback (most recent call last):
...
AssertionError: sequence not as expected:
same:
[{'one': 1}]
first:
[{'text': 'foo\nbar\nbaz', 'two': 2}]
second:
[{'text': 'foo\nbob\nbaz', 'two': 2}]
While comparing [1]: dict not as expected:
same:
['two']
values differ:
'text': 'foo\nbar\nbaz' != 'foo\nbob\nbaz'
While comparing [1]['text']:
--- first
+++ second
@@ -1,3 +1,3 @@
foo
-bar
+bob
baz
This also applies to any comparers you have provided, as can be seen in the next section.
Providing your own comparers¶
When using compare()
frequently for your own complex objects,
it can be beneficial to give more descriptive output when two objects
don’t compare as equal.
Note
If you are reading this section as a result of needing to test objects that don’t natively support comparison, or as a result of needing to infrequently compare your own subclasses of python basic types, take a look at Comparison objects as this may well be an easier solution.
As an example, suppose you have a class whose instances have a timestamp and a name as attributes, but you’d like to ignore the timestamp when comparing:
from datetime import datetime
class MyObject(object):
def __init__(self, name):
self.timestamp = datetime.now()
self.name = name
To compare lots of these, you would first write a comparer:
def compare_my_object(x, y, context):
if x.name == y.name:
return
return 'MyObject named %s != MyObject named %s' % (
context.label('x', repr(x.name)),
context.label('y', repr(y.name)),
)
Then you’d register that comparer for your type:
from testfixtures.comparison import register
register(MyObject, compare_my_object)
Now, it’ll get used when comparing objects of that type, even if they’re contained within other objects:
>>> compare([1, MyObject('foo')], [1, MyObject('bar')])
Traceback (most recent call last):
...
AssertionError: sequence not as expected:
same:
[1]
first:
[<MyObject ...>]
second:
[<MyObject ...>]
While comparing [1]: MyObject named 'foo' != MyObject named 'bar'
From this example, you can also see that a comparer can indicate that
two objects are equal, for compare()
‘s purposes, by returning
None
:
>>> MyObject('foo') == MyObject('foo')
False
>>> compare(MyObject('foo'), MyObject('foo'))
You can also see that you can, and should, use the context object passed in to add labels to the representations of the objects being compared if the comparison fails:
>>> compare(expected=MyObject('foo'), actual=MyObject('bar'))
Traceback (most recent call last):
...
AssertionError: MyObject named 'foo' (expected) != MyObject named 'bar' (actual)
It may be that you only want to use a comparer or set of
comparers for a particular test. If that’s the case, you can pass
compare()
a comparers
parameter consisting of a
dictionary that maps types to comparers. These will be added to the
global registry for the duration of the call:
>>> compare(MyObject('foo'), MyObject('bar'),
... comparers={MyObject: compare_my_object})
Traceback (most recent call last):
...
AssertionError: MyObject named 'foo' != MyObject named 'bar'
A full list of the available comparers included can be found below the
API documentation for compare()
. These make good candidates for
registering for your own classes, if they provide the necessary
behaviour, and their source is also good to read when wondering how to
implement your own comparers.
You may be wondering what the context
object passed to the
comparer is for; it allows you to hand off comparison of parts of the
two objects currently being compared back to the compare()
machinery, it also allows you to pass options to your comparison
function.
For example, you may have an object that has a couple of dictionaries as attributes:
from datetime import datetime
class Request(object):
def __init__(self, uri, headers, body):
self.uri = uri
self.headers = headers
self.body = body
When your tests encounter instances of these that are not as expected, you want feedback about which bits of the request or response weren’t as expected. This can be achieved by implementing a comparer as follows:
def compare_request(x, y, context):
uri_different = x.uri != y.uri
headers_different = context.different(x.headers, y.headers, '.headers')
body_different = context.different(x.body, y.body, '.body')
if uri_different or headers_different or body_different:
return 'Request for %r != Request for %r' % (
x.uri, y.uri
)
Note
A comparer should always return some text when it considers the two objects it is comparing to be different.
This comparer can either be registered globally or passed to each
compare()
call and will give detailed feedback about how the
requests were different:
>>> compare(Request('/foo', {'method': 'POST'}, {'my_field': 'value_1'}),
... Request('/foo', {'method': 'GET'}, {'my_field': 'value_2'}),
... comparers={Request: compare_request})
Traceback (most recent call last):
...
AssertionError: Request for '/foo' != Request for '/foo'
While comparing .headers: dict not as expected:
values differ:
'method': 'POST' != 'GET'
While comparing .headers['method']: 'POST' != 'GET'
While comparing .body: dict not as expected:
values differ:
'my_field': 'value_1' != 'value_2'
While comparing .body['my_field']: 'value_1' != 'value_2'
As an example of passing options through to a comparer, suppose you wanted to compare all decimals in a nested data structure by rounding them to a number of decimal places that varies from test to test. The comparer could be implemented and registered as follows:
from decimal import Decimal
from testfixtures.comparison import register
def compare_decimal(x, y, context):
precision = context.get_option('precision', 2)
if round(x, precision) != round(y, precision):
return '%r != %r when rounded to %i decimal places' % (
x, y, precision
)
register(Decimal, compare_decimal)
Now, this comparer will be used for comparing all decimals and the
precision used will be that passed to compare()
:
>>> expected_order = {'price': Decimal('1.234'), 'quantity': 5}
>>> actual_order = {'price': Decimal('1.236'), 'quantity': 5}
>>> compare(expected_order, actual_order, precision=1)
>>> compare(expected_order, actual_order, precision=3)
Traceback (most recent call last):
...
AssertionError: dict not as expected:
same:
['quantity']
values differ:
'price': Decimal('1.234') != Decimal('1.236')
While comparing ['price']: Decimal('1.234') != Decimal('1.236') when rounded to 3 decimal places
If no precision is passed, the default of 2
will be used:
>>> compare(Decimal('2.006'), Decimal('2.009'))
>>> compare(Decimal('2.001'), Decimal('2.009'))
Traceback (most recent call last):
...
AssertionError: Decimal('2.001') != Decimal('2.009') when rounded to 2 decimal places
Ignoring __eq__
¶
Some objects, such as those from the Django ORM, have pretty broken
implementations or __eq__
. Since compare()
normally relies on this,
it can result in objects appearing to be equal when they are not.
Take this class, for example:
class OrmObj(object):
def __init__(self, a):
self.a = a
def __eq__(self, other):
return True
def __repr__(self):
return 'OrmObj: '+str(self.a)
If we compare normally, we erroneously understand the objects to be equal:
>>> compare(actual=OrmObj(1), expected=OrmObj(2))
In order to get a sane comparison, we need to both supply a custom comparer
as described above, and use the ignore_eq
parameter:
def compare_orm_obj(x, y, context):
if x.a != y.a:
return 'OrmObj: %s != %s' % (x.a, y.a)
>>> compare(actual=OrmObj(1), expected=OrmObj(2),
... comparers={OrmObj: compare_orm_obj}, ignore_eq=True)
Traceback (most recent call last):
...
AssertionError: OrmObj: 2 != 1
Strict comparison¶
If is it important that the two values being compared are of exactly
the same type, rather than just being equal as far as Python is
concerned, then the strict mode of compare()
should be used.
For example, these two instances will normally appear to be equal provided the elements within them are the same:
>>> TypeA = namedtuple('A', 'x')
>>> TypeB = namedtuple('B', 'x')
>>> compare(TypeA(1), TypeB(1))
If this type difference is important, then the strict parameter should be used:
>>> compare(TypeA(1), TypeB(1), strict=True)
Traceback (most recent call last):
...
AssertionError: A(x=1) (<class '__main__.A'>) != B(x=1) (<class '__main__.B'>)
Comparison objects¶
Another common problem with the checking in tests is that not all
objects support comparison and nor should they need to. For this
reason, TextFixtures provides the Comparison
class.
This class lets you instantiate placeholders that can be used to compare expected results with actual results where objects in the actual results do not support useful comparison.
Comparisons will appear to be equal to any object they are compared with that matches their specification. For example, take the following class:
class SomeClass:
def __init__(self, x, y):
self.x, self.y = x, y
Normal comparison doesn’t work, which makes testing tricky:
>>> SomeClass(1, 2) == SomeClass(1, 2)
False
Here’s how this comparison can be done:
>>> from testfixtures import Comparison as C
>>> C(SomeClass, x=1, y=2) == SomeClass(1, 2)
True
Perhaps even more importantly, when a comparison fails, its
representation changes to give information about what went wrong. The
common idiom for using comparisons is in conjuction with
assertEqual()
or
compare()
:
>>> compare(C(SomeClass, x=2), SomeClass(1, 2))
Traceback (most recent call last):
...
AssertionError:
<C(failed):...SomeClass>
x:2 != 1
y:2 not in Comparison
</C> != <...SomeClass...>
The key is that the comparison object actually stores information about what it was last compared with. The following example shows this more clearly:
>>> c = C(SomeClass, x=2)
>>> print(repr(c))
<C:...SomeClass>
x:2
</C>
>>> c == SomeClass(1, 2)
False
>>> print(repr(c))
<C(failed):...SomeClass>
x:2 != 1
y:2 not in Comparison
</C>
Note
assertEqual()
has regressed in Python 3.4
and will now truncate the text shown in assertions with no way to
configure this behaviour. Use compare()
instead, which will
give you other desirable behaviour as well as showing you the full
output of failed comparisons.
Types of comparison¶
There are several ways a comparison can be set up depending on what you want to check.
If you only care about the class of an object, you can set up the comparison with only the class:
>>> C(SomeClass) == SomeClass(1, 2)
True
This can also be achieved by specifying the type of the object as a dotted name:
>>> import sys
>>> C('types.ModuleType') == sys
True
Alternatively, if you happen to have a non-comparable object already around, comparison can be done with it:
>>> C(SomeClass(1,2)) == SomeClass(1,2)
True
If you only care about certain attributes, this can also easily be achieved with the strict parameter:
>>> C(SomeClass, x=1, strict=False) == SomeClass(1, 2)
True
The above can be problematic if you want to compare an object with
attibutes that share names with parameters to the Comparison
constructor. For this reason, you can pass the attributes in a
dictionary:
>>> compare(C(SomeClass, {'strict':3}, strict=False), SomeClass(1, 2))
Traceback (most recent call last):
...
AssertionError:
<C(failed):...SomeClass>
strict:3 not in other
</C> != <...SomeClass...>
Gotchas¶
There are a few things to be careful of when using comparisons:
The default strict comparison cannot be used with a class such as the following:
class NoVars(object): __slots__ = ['x']
If you try, you will get an error that explains the problem:
>>> C(NoVars, x=1) == NoVars() Traceback (most recent call last): ... TypeError: <NoVars object at ...> does not support vars() so cannot do strict comparison
Comparisons can still be done with classes that don’t support
vars()
, they just need to be non-strict:>>> nv = NoVars() >>> nv.x = 1 >>> C(NoVars, x=1, strict=False) == nv True
If the object being compared has an
__eq__
method, such as Django model instances, then theComparison
must be the first object in the equality check.The following class is an example of this:
class SomeModel: def __eq__(self,other): if isinstance(other,SomeModel): return True return False
It will not work correctly if used as the second object in the expression:
>>> SomeModel()==C(SomeModel) False
However, if the comparison is correctly placed first, then everything will behave as expected:
>>> C(SomeModel)==SomeModel() True
It probably goes without saying, but comparisons should not be used on both sides of an equality check:
>>> C(SomeClass)==C(SomeClass) False
Round Comparison objects¶
When comparing numerics you often want to be able to compare to a given precision to allow for rounding issues which make precise equality impossible.
For these situations, you can use RoundComparison
objects
wherever you would use floats or Decimals, and they will compare equal to
any float or Decimal that matches when both sides are rounded to the
specified precision.
Here’s an example:
from testfixtures import compare, RoundComparison as R
compare(R(1234.5678, 2), 1234.5681)
Note
You should always pass the same type of object to the
RoundComparison
object as you intend compare it with. If
the type of the rounded expected value is not the same as the type of
the rounded value being compared against it, a TypeError
will be raised.
Range Comparison objects¶
When comparing orderable types just as numbers, dates and time, you may only
know what range a value will fall into. RangeComparison
objects
let you confirm a value is within a certain tolerance or range.
Here’s an example:
from testfixtures import compare, RangeComparison as R
compare(R(123.456, 789), Decimal(555.01))
Note
RangeComparison
is inclusive of both the lower and upper bound.
String Comparison objects¶
When comparing sequences of strings, particularly those comping from things like the python logging package, you often end up wanting to express a requirement that one string should be almost like another, or maybe fit a particular regular expression.
For these situations, you can use StringComparison
objects
wherever you would use normal strings, and they will compare equal to
any string that matches the regular expression they are created with.
Here’s an example:
from testfixtures import compare, StringComparison as S
compare(S('Starting thread \d+'),'Starting thread 132356')
Differentiating chunks of text¶
TextFixtures provides a function that will compare two strings and
give a unified diff as a result. This can be handy as a third
parameter to assertEqual()
or just as a
general utility function for comparing two lumps of text.
As an example:
>>> from testfixtures import diff
>>> print(diff('line1\nline2\nline3',
... 'line1\nlineA\nline3'))
--- first
+++ second
@@ -1,3 +1,3 @@
line1
-line2
+lineA
line3