Finding and explaining differences¶

The compare() function checks that two values are equal and, when they are not, explains how they differ. Reach for it instead of assertEqual() or a plain assert: it offers much more flexible and configurable comparison, and far clearer feedback when a check fails, particularly for deeply nested data structures, objects that don’t natively support equality checking, and objects that do silly things when compared.

By default a failed comparison is raised as an AssertionError, so it reads as an assertion in your tests. If you would rather examine the difference yourself, pass raises=False and compare() returns the explanation as text instead of raising it.

If, instead of checking for exact equality, you want to assert that a value merely matches a specification, such as a partial object, a number within a range, a string matching a pattern, or a sequence in any order, use the flexible comparison objects and matchers. They slot into the expected side of compare(), and into plain assert statements.

Comparing expected and actual¶

In its simplest form, compare() takes two values and raises an AssertionError if they are not equal:

>>> from testfixtures import compare
>>> compare(1, 2)
Traceback (most recent call last):
 ...
AssertionError: 1 != 2

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)

Only one of these needs to be specified, the other will then be inferred:

>>> actual = '123' + '456'
>>> compare(actual, expected='123457')
Traceback (most recent call last):
 ...
AssertionError: '123457' (expected) != '123456' (actual)

However, if there are more specific labels that would be more useful, they can be supplied:

>>> compare(1001, 1002, x_label='realised', y_label='unrealised')
Traceback (most recent call last):
 ...
AssertionError: 1001 (realised) != 1002 (unrealised)

A prefix can also be specified for the message to be used in the event of failure:

>>> compare(expected=1, actual=2, prefix='wrong number of orders')
Traceback (most recent call last):
 ...
AssertionError: wrong number of orders: 1 (expected) != 2 (actual)

You can also optionally specify a suffix, which will be appended to the message on a new line:

>>> compare(expected=1, actual=2, suffix='(Except for very large values of 1)')
Traceback (most recent call last):
 ...
AssertionError: 1 (expected) != 2 (actual)
(Except for very large values of 1)

Sometimes the feedback you wish to provide can be expensive to compute, and so you will only want to do this in the event the comparison fails. This can be done by providing a callable to either prefix or suffix:

>>> compare(expected=1, actual=2, suffix=lambda: 'This is very expensive to compute...')
Traceback (most recent call last):
 ...
AssertionError: 1 (expected) != 2 (actual)
This is very expensive to compute...

The real strengths of compare() show when comparing more complex and nested data: for many built-in types it pinpoints where the values differ rather than simply reporting that they are unequal. See How each type is compared for the full catalog of how each type is handled.

Controlling the comparison¶

Several keyword arguments change how compare() decides whether two values are equal.

Strict comparison¶

By default, compare() is lenient: it accepts any reasonable notion of equality. It treats values of different but compatible types as equal, and lets some comparers apply their own tolerances. That is usually what you want when checking a result.

Strict mode removes that leniency at every level. It asks whether the two values are identical: of exactly the same type, with their contents inspected directly and no tolerance applied anywhere. Reach for it when a difference the default would forgive actually matters.

The most obvious leniency is over type. By default a list matches a tuple with the same items, but strict mode rejects it:

>>> compare([1, 2], (1, 2))
>>> compare([1, 2], (1, 2), strict=True)
Traceback (most recent call last):
 ...
AssertionError: [1, 2] (<class 'list'>) != (1, 2) (<class 'tuple'>)

This catches differences between types that are otherwise treated as interchangeable. For example, two different namedtuple() classes compare equal by value but not under strict mode:

>>> TypeA = namedtuple('A', 'x')
>>> TypeB = namedtuple('B', 'x')
>>> compare(TypeA(1), TypeB(1))
>>> compare(TypeA(1), TypeB(1), strict=True)
Traceback (most recent call last):
 ...
AssertionError: A(x=1) (<class '__test__.A'>) != B(x=1) (<class '__test__.B'>)

This is also how you assert that a function returns a generator rather than some other iterable, since by default compare() unwinds a generator and compares its contents like any other sequence.

The same principle reaches into individual comparers: where one would normally allow some leeway, strict mode asks for an exact match instead. For example, compare() permits the small floating point differences that pandas and polars tolerate between dataframes, while strict mode requires them to be exactly equal.

Ignoring attributes¶

When comparing objects, there may be attributes that you don’t care about or cannot easily control, such as timestamps or auto-generated IDs. For example, consider this class:

from datetime import datetime

class MyObject:
    def __init__(self, name):
        self.timestamp = datetime.now()
        self.name = name

You can use the ignore_attributes parameter as follows:

>>> obj1 = MyObject('foo')
>>> obj2 = MyObject('foo')
>>> compare(expected=obj1, actual=obj2, ignore_attributes=['timestamp'])

You can also specify which attributes to ignore on a per-type basis by passing a dictionary mapping types to sets of attribute names:

>>> class OtherObject:
...     def __init__(self, id, value):
...         self.id = id
...         self.value = value
>>> compare(
...     expected=[MyObject('x'), OtherObject(1, 'y')],
...     actual=[MyObject('x'), OtherObject(2, 'y')],
...     ignore_attributes={MyObject: {'timestamp'}, OtherObject: {'id'}}
... )

Ignoring `eq`¶

Warning

If you find yourself in a situation where objects incorrectly express equality, be very careful to ensure that you see any tests you implement failing due to inequality before you assume that anything described in this section is working as you expect. Equality checking is complex, and there are gotchas lurking with container types and objects on either side of an equality check implementing __eq__.

Some objects, such as pandas and polars dataframes and Django ORM objects, make unfortunate choices in their implementations of __eq__ when it comes to checking that objects have identical attributes. 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:
    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 correct comparison, we need to use the ignore_eq parameter:

>>> compare(actual=OrmObj(1), expected=OrmObj(2), ignore_eq=OrmObj)
Traceback (most recent call last):
...
AssertionError: OrmObj not as expected:

attributes differ:
'a': 2 (expected) != 1 (actual)

ignore_eq accepts a single type, an iterable of types, or True to skip __eq__ for every object during the comparison.

If a particular type and all of its subclasses are always problematic, you can register it once globally so callers don’t need to remember the ignore_eq= argument:

from testfixtures import register

register(OrmObj, ignore_eq=True)

Custom containers and `ignore_eq`¶

When you pass a type to ignore_eq, compare() also has to ignore the __eq__ of any containers that might contain the type passed to ignore_eq. This is handled for standard container types and their subclasses, specifically list, tuple, dict, set, and frozenset.

For custom container or wrapper types that implement __eq__ and don’t subclass one of these standard container types, and which can contain instances of a type for which you’d like to ignore_eq, you will find that ignore_eq for the inner type alone is not sufficient.

For example, consider a class that groups together the two dataframes used for an evaluation, with an __eq__ that looks reasonable enough:

import polars as pl

class Eval:
    def __init__(self, test, train):
        self.test = test
        self.train = train
    def __eq__(self, other):
        return self.test == other.test and self.train == other.train

e1 = Eval(pl.DataFrame({'x': [1, 2]}), pl.DataFrame({'y': [3, 4]}))
e2 = Eval(pl.DataFrame({'x': [1, 3]}), pl.DataFrame({'y': [3, 4]}))

DataFrame implements __eq__ in a way that returns another DataFrame of element-wise results rather than a single bool, so Eval.__eq__ raises TypeError as soon as it tries to use that result in the and:

>>> compare(e1, expected=e2)
Traceback (most recent call last):
...
TypeError: the truth value of a DataFrame is ambiguous

Hint: to check if a DataFrame contains any values, use `is_empty()`.

If we only pass DataFrame to ignore_eq, Eval.__eq__ still fires first and the comparison still raises:

>>> compare(e1, expected=e2, ignore_eq=pl.DataFrame)
Traceback (most recent call last):
...
TypeError: the truth value of a DataFrame is ambiguous

Hint: to check if a DataFrame contains any values, use `is_empty()`.

We need to pass both the inner type and Eval to ignore_eq:

>>> compare(e1, expected=e2, ignore_eq=[pl.DataFrame, Eval])
Traceback (most recent call last):
...
AssertionError: Eval not as expected:

attributes same:
['train']

attributes differ:
'test': shape: (2, 1)
┌─────┐
│ x   │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 3   │
└─────┘ (expected) != shape: (2, 1)
┌─────┐
│ x   │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 2   │
└─────┘ (actual)

While comparing .test: DataFrames are different (value mismatch for column "x")
[left]: shape: (2,)
Series: 'x' [i64]
[
        1
        3
]
[right]: shape: (2,)
Series: 'x' [i64]
[
        1
        2
]

DataFrame is already registered with ignore_eq=True if Polars is installed, so if Eval is used a lot, the only registration you need to add yourself is for Eval itself:

from testfixtures import register

register(Eval, ignore_eq=True)

>>> compare(e1, expected=e2)
Traceback (most recent call last):
...
AssertionError: Eval not as expected:

attributes same:
['train']

attributes differ:
'test': shape: (2, 1)
┌─────┐
│ x   │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 3   │
└─────┘ (expected) != shape: (2, 1)
┌─────┐
│ x   │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 2   │
└─────┘ (actual)

While comparing .test: DataFrames are different (value mismatch for column "x")
[left]: shape: (2,)
Series: 'x' [i64]
[
        1
        3
]
[right]: shape: (2,)
Series: 'x' [i64]
[
        1
        2
]

Nested and 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 comparer you provide, as shown under Providing your own comparers.

Preventing infinite recursion¶

If an object refers back to itself, directly or via something it contains, the recursive comparison used by compare() would loop forever. To avoid this, if an object is seen more than once during a comparison, it is wrapped with an AlreadySeen marker rather than being compared again.

When that happens and a difference is being reported anyway, the marker becomes visible in the output:

>>> ouroboros1 = {}
>>> ouroboros1['ouroboros'] = ouroboros1
>>> ouroboros2 = {}
>>> ouroboros2['ouroboros'] = ouroboros2
>>> compare({1: ouroboros1, 2: 'foo'}, {1: ouroboros2, 2: ouroboros2})
Traceback (most recent call last):
 ...
AssertionError: dict not as expected:

same:
[1]

values differ:
2: 'foo' != {'ouroboros': <Recursion on dict with id=...>}

While comparing [2]: not equal:
'foo'
<AlreadySeen for {'ouroboros': {...}} at [1] with id ...>

The at [1] part of the marker is the path where that object was first encountered, so you can trace the cycle back to its origin.

If the same object appears at the same position in both sides of a comparison compare() treats it as equal by identity without calling its __eq__. No marker is visible in that case, and an unhelpful __eq__ cannot cause a spurious difference.

How each type is compared¶

Where compare() recognises the type of the values it is given, it produces a description tailored to that type, pinpointing exactly what differs, and recurses into the elements those values contain. The following sections show the feedback given for each supported type.

sets¶

Comparing sets that aren’t the same will attempt to highlight where the differences lie:

>>> compare(expected={1, 2}, actual={2, 3})
Traceback (most recent call last):
 ...
AssertionError: set not as expected:

in expected but not actual:
[1]

in actual but not expected:
[3]

See SequenceComparison to assert only that certain items are present, regardless of order.

dicts¶

Comparing dictionaries that aren’t the same will attempt to highlight where the differences lie:

>>> compare(expected=dict(x=1, y=2, a=4), actual=dict(x=1, z=3, a=5))
Traceback (most recent call last):
 ...
AssertionError: dict not as expected:

same:
['x']

in expected but not actual:
'y': 2

in actual but not expected:
'z': 3

values differ:
'a': 4 (expected) != 5 (actual)

See MappingComparison to assert only that certain keys are present, or to check the order of keys.

lists and tuples¶

Comparing lists or tuples that aren’t the same will attempt to highlight where the differences lie:

>>> compare(expected=[1, 2, 3], actual=[1, 2, 4])
Traceback (most recent call last):
 ...
AssertionError: sequence not as expected:

same:
[1, 2]

expected:
[3]

actual:
[4]

See SequenceComparison to compare without regard to order, or to assert only that certain items are present.

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(expected=TestTuple(1, 2, 3), actual=TestTuple(1, 4, 3))
Traceback (most recent call last):
 ...
AssertionError: TestTuple not as expected:

same:
['x', 'z']

values differ:
'y': 2 (expected) != 4 (actual)

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(expected=generator(1, 2, 3), actual=my_gen(2))
Traceback (most recent call last):
 ...
AssertionError: sequence not as expected:

same:
(1, 2)

expected:
(3,)

actual:
()

See SequenceComparison to compare the unwound results without regard to order, or to assert only that certain items are present.

Warning

If you wish to assert that a function returns a generator, say, for performance reasons, then you should use strict comparison.

strings¶

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(expected="1234567891011", actual="1234567789")
Traceback (most recent call last):
 ...
AssertionError:
'1234567891011' (expected)
!=
'1234567789' (actual)

Likewise, multi-line strings give unified diffs when their comparison fails:

>>> compare(
...     expected="""
...         This is line 1
...         This is line 2
...         This is line 3
...         """,
...     actual="""
...         This is line 1
...         This is another line
...         This is line 3
...         """
... )
Traceback (most recent call last):
 ...
AssertionError:
--- expected
+++ actual
@@ -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(
    expected='line1\nline2',
    actual='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(
    expected='line1\nline2',
    actual='line1 \t\nline2   \n',
    trailing_whitespace=False
)

See TextComparison to assert that a string matches a regular expression instead of comparing it exactly.

datetimes and times¶

Given the following two datetime objects:

>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> t1 = datetime(2024, 10, 27, 1, fold=0, tzinfo=ZoneInfo('Europe/London'))
>>> str(t1)
'2024-10-27 01:00:00+01:00'
>>> t2 = datetime(2024, 10, 27, 1, fold=1, tzinfo=ZoneInfo('Europe/London'))
>>> str(t2)
'2024-10-27 01:00:00+00:00'

It may well be surprising to find out that Python considers them equivalent:

>>> t1 == t2
True

Unfortunately, that also means that compare() will also consider them equal:

>>> compare(t1, t2)

If it is important for you to be able to check you have the correct point in time, then you can use strict comparison, which will highlight the difference:

>>> compare(t1, t2, strict=True)
Traceback (most recent call last):
...
AssertionError: datetime.datetime(2024, 10, 27, 1, 0, tzinfo=zoneinfo.ZoneInfo(key='Europe/London')) != datetime.datetime(2024, 10, 27, 1, 0, fold=1, tzinfo=zoneinfo.ZoneInfo(key='Europe/London'))

This problem can also be seen with time objects, where given the following two times:

>>> from datetime import time
>>> t1 = time(1, 30, fold=0)
>>> str(t1)
'01:30:00'
>>> t2 = time(1, 30, fold=1)
>>> str(t2)
'01:30:00'

The times will be considered equal:

>>> t1 == t2
True
>>> compare(t1, t2)

However, once again, strict comparison will highlight the difference:

>>> compare(t1, t2, strict=True)
Traceback (most recent call last):
...
AssertionError: datetime.time(1, 30) != datetime.time(1, 30, fold=1)

objects¶

Even if your objects do not natively support comparison, when they are compared they will be considered identical if they are of the same type and have identical attributes. Take instances of this class as an example:

class MyObject:
    def __init__(self, name):
        self.name = name
    def __repr__(self):
        return '<MyObject>'

If the attributes and type of instances are the same, they will be considered equal:

>>> compare(MyObject('foo'), expected=MyObject('foo'))

However, if their attributes differ, you will get an informative error:

>>> compare(MyObject('foo'), expected=MyObject('bar'))
Traceback (most recent call last):
 ...
AssertionError: MyObject not as expected:

attributes differ:
'name': 'bar' (expected) != 'foo' (actual)

While comparing .name: 'bar' (expected) != 'foo' (actual)

This type of comparison is also used on objects that make use of __slots__.

To compare only some of an object’s attributes, see Ignoring attributes, or use the partial like() matcher described in Comparison objects and matchers.

Providing your own comparers¶

The sections above cover how compare() performs out of the box. When you need richer feedback for your own types, you can teach compare() how to compare them.

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 and matchers 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:
    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 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(expected=[1, MyObject('foo')], actual=[1, MyObject('bar')])
Traceback (most recent call last):
 ...
AssertionError: sequence not as expected:

same:
[1]

expected:
[<MyObject ...>]

actual:
[<MyObject ...>]

While comparing [1]: MyObject named 'foo' (expected) != MyObject named 'bar' (actual)

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(MyObject('foo'), MyObject('bar'), x_label='stored', y_label='supplied')
Traceback (most recent call last):
 ...
AssertionError: MyObject named 'foo' (stored) != MyObject named 'bar' (supplied)

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:

>>> 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.

Note

A comparer should always return some text when it considers the two objects it is comparing to be different.

Handing off comparison¶

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.

For example, you may have an object that has a couple of dictionaries as attributes:

class Request:
    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 f'Request for {x.uri!r} != Request for {y.uri!r}'

Here’s this custom request comparer in action:

>>> 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'

Note

A comparer should always return some text when it considers the two objects it is comparing to be different.

Options for custom comparers¶

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 import register

def compare_decimal(x, y, context, precision: int = 2):
     if round(x, precision) != round(y, precision):
         return f'{x!r} != {y!r} when rounded to {precision} places'

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 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 places

If you only need to compare numbers approximately or within a range, the RoundComparison and RangeComparison objects may be simpler than a custom comparer.

Ignoring attributes in custom comparers¶

When writing custom comparers that delegate to compare_object(), you may want to always ignore certain attributes while still allowing users to pass additional attributes to ignore via the ignore_attributes parameter to compare().

The merge_ignored_attributes() function makes this easy by combining multiple ignore specifications:

from testfixtures.comparers import compare_object, merge_ignored_attributes

class Thing:
    def __init__(self, **kw):
        for k, v in kw.items():
            setattr(self, k, v)

def compare_thing(x, y, context):
    # Always ignore 'y' attribute, plus any user-specified ignores
    context_ignored = context.options.get('ignore_attributes')
    ignored = merge_ignored_attributes('y', context_ignored)
    return compare_object(x, y, context, ignore_attributes=ignored)

Now the y attribute will always be ignored, but users can still specify additional attributes to ignore:

>>> compare(Thing(x=1, y=2), Thing(x=1, y=3),
...         comparers={Thing: compare_thing})

>>> compare(Thing(x=1, y=2, z=3), Thing(x=1, y=4, z=5),
...         comparers={Thing: compare_thing},
...         ignore_attributes=['z'])

Rendering objects safely in custom comparers¶

When a custom comparer builds a message it usually needs to render the objects it is comparing. If one of those objects raises an exception as part of that process, the caller sees an unrelated traceback instead of any useful comparison message.

safe_repr() and safe_pformat() are drop-in replacements for repr() and pprint.pformat() that catch exceptions, but not BaseException instances such as KeyboardInterrupt or SystemExit, and substitute any failures with a marker.

For example, an object whose __repr__ raises yields a marker instead of propagating the exception:

>>> from testfixtures import safe_repr
>>> class Broken:
...     def __repr__(self):
...         raise ValueError('boom')
>>> print(safe_repr(Broken()))
<unrepresentable ...Broken: ValueError: boom>

Finding and explaining differences¶

Comparing expected and actual¶

Controlling the comparison¶

Strict comparison¶

Ignoring attributes¶

Ignoring __eq__¶

Custom containers and ignore_eq¶

Nested and recursive comparison¶

Preventing infinite recursion¶

How each type is compared¶

sets¶

dicts¶

lists and tuples¶

namedtuples¶

generators¶

strings¶

datetimes and times¶

objects¶

Providing your own comparers¶

Handing off comparison¶

Options for custom comparers¶

Ignoring attributes in custom comparers¶

Rendering objects safely in custom comparers¶

Ignoring `eq`¶

Custom containers and `ignore_eq`¶