Introduction

Doing dirty (but extremely useful) things with equals.

Documentation for version: v0.11.0

dirty-equals is a python library that (mis)uses the __eq__ method to make python code (generally unit tests) more declarative and therefore easier to read and write.

dirty-equals can be used in whatever context you like, but it comes into its own when writing unit tests for applications where you're commonly checking the response to API calls and the contents of a database.

Usage¶

Here's a trivial example of what dirty-equals can do:

Trivial Usage

from dirty_equals import IsPositive

assert 1 == IsPositive  This assert will pass since 1 is indeed positive, so the result of 1 == IsPositive is True.

assert -2 == IsPositive  # this will fail! This will fail (raise a AssertionError) since -2 is not positive,
   so the result of -2 == IsPositive is False.

Not that interesting yet!, but consider the following unit test code using dirty-equals:

More Powerful Usage

from dirty_equals import IsJson, IsNow, IsPositiveInt, IsStr


def test_user_endpoint(client: 'HttpClient', db_conn: 'Database'):
    client.post('/users/create/', data=...)

    user_data = db_conn.fetchrow('select * from users')
    assert user_data == {
        'id': IsPositiveInt,  We don't actually care what the id is, just that it's present, it's an int and it's positive.

        'username': 'samuelcolvin',  We can use a normal key and value here since we know exactly what value username should have before we test it.

        'avatar_file': IsStr(regex=r'/[a-z0-9\-]{10}/example\.png'),  avatar_file is a string, but we don't know all of the string before the assert,
   just the format (regex) it should match.

        'settings_json': IsJson({'theme': 'dark', 'language': 'en'}),  settings_json is a JSON string, but it's simpler and more robust to confirm it represents a particular python
   object rather than compare strings.

        'created_ts': IsNow(delta=3),  created_at is a datetime, although we don't know (or care) about its exact value;
   since the user was just created we know it must be close to now. delta is optional, it defaults to 2 seconds.

    }

Without dirty-equals, you'd have to compare individual fields and/or modify some fields before comparison - the test would not be declarative or as clear.

dirty-equals can do so much more than that, for example:

IsPartialDict lets you compare a subset of a dictionary
IsStrictDict lets you confirm order in a dictionary
IsList and IsTuple lets you compare partial lists and tuples, with or without order constraints
nesting any of these types inside any others
IsInstance lets you simply confirm the type of an object
You can even use boolean operators | and & to combine multiple conditions
and much more...

Installation¶

Simply:

pip install dirty-equals

dirty-equals requires Python 3.9+.