django-sql-test

Prevent SQL regressions, detect N+1 queries, and visualize query diffs in your Django tests. A test mixin that captures, snapshots, and diffs all executed SQL queries in your test output.

$ poetry run python manage.py test path.to.test.FooTest.test_bar
======================================================================
FAIL: test_bar (path.to.test.FooTest.test_bar)
 ...
AssertionError: 5 != 2 : 5 queries executed, 2 expected
Queries diff:
- SELECT polls_choice.id FROM polls_choice
+ SELECT polls_choice.id FROM polls_choice WHERE polls_choice.votes >= N
+ SELECT polls_question.id FROM polls_question WHERE polls_question.id = N LIMIT N
+ SELECT polls_question.id FROM polls_question WHERE polls_question.id = N LIMIT N
+ SELECT polls_question.id FROM polls_question WHERE polls_question.id = N LIMIT N
  SELECT COUNT(*) AS __count FROM polls_question

Table of Contents

• Requirements
• Installation
• Quickstart
• Configuration
• API Reference
• Contributing
• License
• Changelog

Requirements

• Django >= 4.0
• Python >= 3.9

Installation

pip install django-sql-test

Quickstart

In your test.py just import NumNewQueriesMixin and add it as a parent:

from django.test import TestCase
from django_sql_test import NumNewQueriesMixin

class FooTest(NumNewQueriesMixin, TestCase):
    def test_bar(self):
        with self.assertNumNewQueries(2):
            response = self.client.get(self.url)

        self.assertEqual(response.status_code, 200)

What you got before adding NumNewQueriesMixin:

$ poetry run python manage.py test path.to.test.FooTest.test_bar
======================================================================
FAIL: test_bar (path.to.test.FooTest.test_bar)
  ...
AssertionError: 5 != 2 : 5 queries executed, 2 expected
Captured queries were:
1. SELECT "polls_choice"."id" FROM "polls_choice" WHERE "polls_choice"."votes" >= 0
2. SELECT "polls_question"."id" FROM "polls_question" WHERE "polls_question"."id" = 1 LIMIT 21
3. SELECT "polls_question"."id" FROM "polls_question" WHERE "polls_question"."id" = 1 LIMIT 21
4. SELECT "polls_question"."id" FROM "polls_question" WHERE "polls_question"."id" = 1 LIMIT 21
5. SELECT COUNT(*) AS "__count" FROM "polls_question"

What you get after adding NumNewQueriesMixin:

$ poetry run python manage.py test path.to.test.FooTest.test_bar
======================================================================
FAIL: test_bar (path.to.test.FooTest.test_bar)
 ...
AssertionError: 5 != 2 : 5 queries executed, 2 expected
Queries diff:
- SELECT polls_choice.id FROM polls_choice
+ SELECT polls_choice.id FROM polls_choice WHERE polls_choice.votes >= N
+ SELECT polls_question.id FROM polls_question WHERE polls_question.id = N LIMIT N
+ SELECT polls_question.id FROM polls_question WHERE polls_question.id = N LIMIT N
+ SELECT polls_question.id FROM polls_question WHERE polls_question.id = N LIMIT N
  SELECT COUNT(*) AS __count FROM polls_question

Configuration

Configure via your Django settings:

SQL_TEST_GENERALIZED_DIFF

If set to True:

Queries diff:
+ SELECT polls_choice.id FROM polls_choice WHERE polls_choice.votes >= N

If set to False:

Queries diff:
+ SELECT "polls_choice"."id" FROM "polls_choice" WHERE "polls_choice"."votes" >= 0

API Reference

NumNewQueriesMixin

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/YourFeature)
3. Write tests and ensure coverage
4. Run and pass:

   poetry run isort -c --diff --settings-file pyproject.toml .
   poetry run black --diff --config pyproject.toml --check .
   poetry run python runtests.py
   

5. Submit a pull request

License

This project is licensed under the MIT License. See LICENSE for details.

Changelog

All notable changes are documented on the Releases page.