assertion 0.1.4

Supercharged assertion tests

---

assertion

This small package solves a few issues of the regular assert statements in Python:

• Regular asserts are ignored if the code is run with python -O.

• If an assertion fails, no additional information is given about the parameters which caused the fail.

• Test parameters are fixed (e.g., a variable which is True).

• A timing-critical test might fail now, but would have passed a few seconds later (e.g., after some action has been completed).

The assertion tests behave differently:

• The tests are always evaluated.

• If a test fails, a string representation of the provided arguments is included in the exception description.

• Test parameters can be

  • constants,

  • functions (sync and async),

  • other mutable variables.

• Optionally, a test can be re-evaluated until a configurable timeout is reached. By default, the timeout is zero and test fail instantly.

Quickstart

Here is a simple example:

>>> from assertion import Assertion
>>> assertion = Assertion()
>>> val = 999
>>> assertion.false(val)
Traceback (most recent call last):
    ...
AssertionError: 999 != False

Here is a more complex example using coroutines:

import asyncio
from assertion import Assertion

assertion = Assertion(msg="D'oh!", timeout=10.0)

class Countdown:
    def __init__(self, start: int):
        self.counter = start

    async def countdown(self) -> bool:
        self.counter -= 1
        return self.counter == 0

async def main():
    print("Test A...")
    await assertion.true(Countdown(10).countdown)  # should be successful
    print("ok")

    print("Test B...")
    await assertion.true(Countdown(50).countdown)  # should fail
    print("ok")

asyncio.run(main())

Note

The test functions act as both regular functions and as awaitables depending on the test arguments.

If the test arguments contain coroutines or awaitables, you must await the test.

There are several pre-defined tests:

true false	Expects single parameter and determines its boolean value.
equal not_equal less less_or_equal greater greater_or_equal	Expects two parameters and performs the corresponding comparison operators.
in_ not_in	Expects two parameters and uses the built-in in operator.
is_ is_not	Expects two parameters and uses the built-in is operator.

In addition to the test parameters, each call accepts optional parameters:

msg (str, default: “”)

This message is prefixed to the exception text.

timeout (float, unit: seconds, default: 0.0)

The number of seconds until the test is finally considered as failed.

exception (Exception, default: AssertionError)

Any Exception subclass which is raised if the test fails.

Note

If you use a non-zero timeout, the test arguments might be evaluated/called multiple time. Please make sure that any given function call can handle this or set the timeout to zero.

More Details

You can choose different defaults for msg, timeout, and exception while creating an instance of Assertion.

In addition, you can specify three more parameters:

msg_length_max (int, default: 100)

This limits the string representation of the provided test parameters to the given number of characters. The optional message is not considered and will always be included in full length).

delay_init (float, unit: seconds, default 0.125)

Non-zero timeout only: If the initial test fails, the arguments are re-evaluated after this initial delay.

delay_max (float, unit: seconds, default: 5.0)

Non-zero timeout only: This limits the delay between two test parameter evaluations.

In the default implementation, the delay between each evaluation is doubled (until it reaches the given maximum). This behavior can be changed by overloading Assert._get_new_delay.

Similar Packages

This package was heavily inspired by the assert magic in pytest.

assert-info has a slightly different focus, but might suit you better.