django_assert_queries.testing

Utilities for capturing queries during unit tests.

Functions

assert_queries(queries[, num_statements, ...])

Assert the number and complexity of queries.
django_assert_queries.testing.assert_queries(queries: Sequence[ExpectedQuery | Dict[str, Any]], num_statements: int | None = None, *, with_tracebacks: bool = False, traceback_size: int = 15, check_join_types: bool = True, check_subqueries: bool = True) → ContextManager[source]

Assert the number and complexity of queries.

This provides advanced checking of queries, allowing the caller to match filtering, JOINs, ordering, selected fields, and more.

This takes a list of dictionaries with query information. Each contains the keys in ExpectedQuery.

New in version 2.0: Turned on check_join_types and check_subqueries by default.

Parameters:

  • queries (list of django_equery.query_comparator.ExpectedQuery) – The list of query dictionaries to compare executed queries against.

  • num_statements (int, optional) –

    The numbre of SQL statements executed.

    This defaults to the length of queries, but callers may need to provide an explicit number, as some operations may add additional database-specific statements (such as transaction-related SQL) that won’t be covered in queries.

  • with_tracebacks (bool, optional) – If enabled, tracebacks for queries will be included in results.

  • traceback_size (int, optional) –

    The size of any tracebacks, in number of lines.

    The default is 15.

  • check_join_types (bool, optional) –

    Whether to check join types.

    If disabled, table join types (join_types on queries) will not be checked.

  • check_subqueries (bool, optional) –

    Whether to check subqueries.

    If disabled, inner_query on queries with subqueries will not be checked.

Raises:

AssertionError – The parameters passed, or the queries compared, failed expectations.