Finding and explaining differences ================================== .. currentmodule:: testfixtures .. invisible-code-block: python from collections import namedtuple try: import polars except ImportError: polars = None The :func:`compare` function checks that two values are equal and, when they are not, explains *how* they differ. Reach for it instead of :meth:`~unittest.TestCase.assertEqual` or a plain ``assert``: it offers much more :ref:`flexible ` and :ref:`configurable ` comparison, and far clearer feedback when a check fails, particularly for deeply nested data structures, objects that don't :ref:`natively support equality checking `, and objects that do :ref:`silly things ` when compared. By default a failed comparison is raised as an :class:`AssertionError`, so it reads as an assertion in your tests. If you would rather examine the difference yourself, pass ``raises=False`` and :func:`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 :ref:`comparison objects and matchers `. They slot into the expected side of :func:`compare`, and into plain ``assert`` statements. Comparing expected and actual ----------------------------- In its simplest form, :func:`compare` takes two values and raises an :class:`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 :func:`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 :ref:`compare-types` for the full catalog of how each type is handled. .. _flexible: Controlling the comparison -------------------------- Several keyword arguments change how :func:`compare` decides whether two values are equal. .. _strict-comparison: Strict comparison ~~~~~~~~~~~~~~~~~ By default, :func:`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 :class:`list` matches a :class:`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] () != (1, 2) () This catches differences between types that are otherwise treated as interchangeable. For example, two different :func:`~collections.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) () != B(x=1) () This is also how you assert that a function returns a :ref:`generator ` rather than some other iterable, since by default :func:`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, :func:`compare` permits the small floating point differences that :doc:`pandas ` and :doc:`polars ` tolerate between dataframes, while strict mode requires them to be exactly equal. .. _ignore-attributes: 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: .. code-block:: python 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'}} ... ) .. _ignore-eq: 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 :doc:`pandas ` and :doc:`polars ` dataframes and :doc:`Django ORM objects`, make unfortunate choices in their implementations of ``__eq__`` when it comes to checking that objects have identical attributes. Since :func:`compare` normally relies on this, it can result in objects appearing to be equal when they are not. Take this class, for example: .. code-block:: python 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: .. invisible-code-block: python from testfixtures.comparing import Registry registry = Registry.initial().install() .. code-block:: python from testfixtures import register register(OrmObj, ignore_eq=True) .. invisible-code-block: python registry.uninstall() Custom containers and ``ignore_eq`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When you pass a type to ``ignore_eq``, :func:`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 :class:`list`, :class:`tuple`, :class:`dict`, :class:`set`, and :class:`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: .. skip: start if(polars is None, reason="No polars installed") .. code-block:: python 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]})) :class:`~polars.DataFrame` implements ``__eq__`` in a way that returns another :class:`~polars.DataFrame` of element-wise results rather than a single :class:`bool`, so ``Eval.__eq__`` raises :exc:`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 :class:`~polars.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 :class:`!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 ] :class:`~polars.DataFrame` is already registered with ``ignore_eq=True`` if Polars is installed, so if :class:`!Eval` is used a lot, the only registration you need to add yourself is for :class:`!Eval` itself: .. invisible-code-block: python from testfixtures.comparing import Registry from testfixtures.polars import compare_dataframe registry = Registry.initial().install() register(pl.DataFrame, compare_dataframe, ignore_eq=True) .. code-block:: python 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 ] .. invisible-code-block: python registry.uninstall() .. skip: end .. _recursion: Nested and recursive comparison ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Where :func:`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 :ref:`comparer-register`. Preventing infinite recursion ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If an object refers back to itself, directly or via something it contains, the recursive comparison used by :func:`compare` would loop forever. To avoid this, if an object is seen more than once during a comparison, it is wrapped with an :class:`~testfixtures.comparers.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': } While comparing [2]: not equal: 'foo' 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 :func:`compare` treats it as equal by identity without calling its ``__eq__``. No marker is visible in that case, and an :ref:`unhelpful ` ``__eq__`` cannot cause a spurious difference. .. _compare-types: How each type is compared ------------------------- Where :func:`compare` recognises the type of the values it is given, it produces a description tailored to that type, pinpointing exactly what differs, and :ref:`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 :ref:`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 :ref:`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 :ref:`SequenceComparison ` to compare without regard to order, or to assert only that certain items are present. namedtuples ~~~~~~~~~~~ When two :func:`~collections.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) .. _compare-generators: generators ~~~~~~~~~~ When two generators are compared, they are both first unwound into tuples and those tuples are then compared. The :ref:`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>> 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 :ref:`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 :ref:`strict comparison `. .. _compare-strings: 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, :func:`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: .. code-block:: python 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: .. code-block:: python compare( expected='line1\nline2', actual='line1 \t\nline2 \n', trailing_whitespace=False ) See :ref:`TextComparison ` to assert that a string matches a regular expression instead of comparing it exactly. .. _compare-datetime: datetimes and times ~~~~~~~~~~~~~~~~~~~ Given the following two :class:`~datetime.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 :func:`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 :ref:`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 :class:`~datetime.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) .. _comparer-objects: 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: .. code-block:: python class MyObject: def __init__(self, name): self.name = name def __repr__(self): return '' 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 :ref:`ignore-attributes`, or use the partial :func:`like` matcher described in :ref:`comparison-objects`. .. _comparer-register: Providing your own comparers ---------------------------- The sections above cover how :func:`compare` performs out of the box. When you need richer feedback for your own types, you can teach :func:`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 :ref:`comparison-objects` as this may well be an easier solution. .. invisible-code-block: python from testfixtures.comparing import Registry from testfixtures.comparers import compare_sequence registry = Registry.initial({list: compare_sequence}).install() 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: .. code-block:: python 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: .. code-block:: python 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: .. code-block:: python 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: [] actual: [] 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 :func:`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 :func:`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' .. invisible-code-block: python registry.uninstall() A full list of the available comparers included can be found below the API documentation for :func:`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. .. _custom-comparer-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 :func:`compare` machinery. For example, you may have an object that has a couple of dictionaries as attributes: .. code-block:: python 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: .. code-block:: python 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. .. _custom-comparer-options: 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: .. invisible-code-block: python registry = Registry.initial().install() .. code-block:: python 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 :func:`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 :ref:`RoundComparison ` and :ref:`RangeComparison ` objects may be simpler than a custom comparer. Ignoring attributes in custom comparers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When writing custom comparers that delegate to :func:`~testfixtures.comparers.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 :func:`compare`. The :func:`~testfixtures.comparers.merge_ignored_attributes` function makes this easy by combining multiple ignore specifications: .. code-block:: python 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']) .. invisible-code-block: python registry.uninstall() 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. :func:`~testfixtures.comparers.safe_repr` and :func:`~testfixtures.comparers.safe_pformat` are drop-in replacements for :func:`repr` and :func:`pprint.pformat` that catch exceptions, but not :class:`BaseException` instances such as :exc:`KeyboardInterrupt` or :exc:`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()))