Errors

Every error Hegel raises about a run, rather than one raised by the test itself, is a HegelError. The exception is MultipleFailures, which groups the test’s own exceptions when a run reports more than one failure.

exception hegel.HegelError

Bases: Exception

Base class for Hegel errors.

exception hegel.InvalidArgument

Bases: HegelError

An argument passed to Hegel was invalid.

exception hegel.RunError

Bases: HegelError

The engine aborted the run rather than reporting a pass or a test failure: a failed health check (FailedHealthCheck), nondeterminism under the error strictness (Flaky), too few valid test cases (Unsatisfiable), or another engine error. The message explains which.

exception hegel.FailedHealthCheck(message: str, health_check: HealthCheck | None = None)

Bases: RunError

A health check failed: the run was likely to test poorly or slowly (too many rejected test cases, say). health_check is the HealthCheck that failed, and the message names it and says how to suppress it with suppress_health_check if the behaviour is intentional.

exception hegel.Unsatisfiable

Bases: RunError

The engine could not find enough inputs satisfying the test’s assumptions and filters. With the filter_too_much health check enabled, a run that rejects nearly everything fails that check (FailedHealthCheck) first.

exception hegel.Flaky

Bases: RunError

The engine aborted the run because the test behaved nondeterministically, under NondeterminismStrictness.error. The default strictness instead confirms such failures by repeated replay and reports them with a caveat.

exception hegel.DidNotReproduce

Bases: HegelError

The blob given to reproduce_failure() no longer makes the test fail: the bug is fixed (remove the decorator) or the test has changed so the blob means something else.

exception hegel.ResolutionFailed

Bases: InvalidArgument

from_type() could not find a generator for a type. Raised when the generator is built; a subclass of InvalidArgument.

exception hegel.NotPrintable

Bases: InvalidArgument

TestCase.draw was given a generator that cannot print the values it draws: a Generator subclass that implements only do_draw, or a structure containing one. Raised from the draw, on the first test case that reaches it; a subclass of InvalidArgument, so it ends the run as a usage error. Implement do_draw_and_print on the generator, make it printable with print_with() or print_as_repr(), or draw it with TestCase.draw_silent.

exception hegel.BackendError

Bases: HegelError

The Hegel engine reported an error.

exception hegel.InternalError

Bases: HegelError

An internal error in Hegel. Please report this as a bug.

exception hegel.MultipleFailures(message: str, exceptions: Any)

Bases: BaseExceptionGroup

A run found several distinct failures, with report_multiple_failures=True. Each failure is in exceptions, with its own falsifying example attached as notes.

Like the built-in exception groups, an instance whose failures are all Exception s is itself an ExceptionGroup, so except Exception catches it; one with a BaseException among them is only a BaseExceptionGroup.

Control flow

These exceptions are how Hegel ends a test case early. A test should let them propagate.

exception hegel.AssumeFailed

Bases: BaseException

Control flow: the current test case was rejected by an assumption.

exception hegel.StopTest

Bases: BaseException

Control flow: the engine abandoned the current test case.