Skip to main content

A Django Toolkit for controlling Query count when testing

Project description Logo

A Django Toolkit for controlling Query count when testing. It controls the number of queries done in the tests stays below a particular threshold between Test Runs.Specially useful when paired with a CI like Jenkins or Travis to control each commit doesn’t slow down the Database considerably.


  • Python 3

  • Django


The full documentation is at


There are ways to install it into your project

Clone this repository into your project:

git clone

Download the zip file and unpack it:


Install with pip:

pip install django-test-query-counter

Add it to your INSTALLED_APPS:



Run your django tests as you do. After the run the reports directory with two files query_count.json and query_count_detail.json.

To check your tests Query Counts run:

$ python check_query_count

Then you would see an output like the following one (if you at least ran the tests twice):

All Tests API Queries are below the allowed threshold.

If the current test run had more queries than the last one, it will tell you:

There are test cases with API calls that exceeded threshold:

    In test case app.organizations.tests.api.test_division_api.DivisionViewTest.test_bulk_create_division, POST /api/divisions. Expected at most 11 queries but got 15 queries
    In test case app.shipments.tests.api.test_leg_api.LegViewTest.test_create_bulk_leg, POST /api/legs. Expected at most 59 queries but got 62 queries
    In test case app.plans.tests.functional.test_plan_api.PlannedDatesTest.test_unassign_and_assign_driver_to_leg, POST /api/assignments/assign-driver. Expected at most 261 queries but got 402 queries
CommandError: There was at least one test with an API call excedding the allowed threshold.


You can customize how the Test Query Count works by defining TEST_QUERY_COUNTER in your settings file as a dictionary. The following code shows an example

    # Global switch
    'ENABLE': True,

    # Paths where the count files are generated (relative to the current
    # process dir)
    'DETAIL_PATH': 'reports/query_count_detail.json',
    'SUMMARY_PATH': 'reports/query_count.json',

    # Tolerated percentage of count increase on successive
    # test runs.A value of 0 prevents increasing queries altoghether.

Excluding Tests

Individual tests or classes can be excluded for the count using the @exclude_query_count decorator. For example

# To exclude all methods in the class
class AllTestExcluded(TestCase):
    def test_foo(self):

    def test_foo(self):

# To exclude one test only
class OneMethodExcluded():
    def test_foo(self):

    def test_foo(self):

More specifically, exclude_query_count accept parameters to conditionally exclude a query count by path, method or count. Where path the or regex of the excluded path(s). The method specifies the regex of the method(s) to exclude, and count is minimum number of queries tolerated. Requests with less or same amount as “count” will be excluded.

For example:

class Test(TestCase):
    def test_exclude_path(self):

    def test_exclude_method(self):

    def test_exclude_count(self):
        #  succesive urls requests are additive
        for i in range(3):

Implementing into your CI

Currently the query count works locally. However, it shines when it is integrated with Jenkins, or other CIs. You have to do this manually:


  • Jenkins with a Job that build you project.

From now on let’s suppose your job is available at

  1. Activate Build Archive: Go to the job configuration page and add the archive artifacts build Post-build actions.

    Jenkins Post Build Action showing an archive artifact example
  2. Set reports/query_count.json in the files to archive path

  3. Create a new Django custom Command to run the validation against the archived Jenkins file. For example:

    from urllib.request import urlretrieve
    from import BaseCommand, CommandError
    from django.conf import settings
    from test_query_counter.apps import RequestQueryCountConfig
    from test_query_counter.query_count import QueryCountEvaluator
    class Command(BaseCommand):
        JENKINS_QUERY_COUNT = 'https://yourci/job/' \
                              'yourproject/lastSuccessfulBuild/' \
        def handle(self, *args, **options):
            current_file_path = RequestQueryCountConfig.get_setting('SUMMARY_FILE')
            with open(current_file_path) as current_file, \
                    open(urlretrieve(self.JENKINS_QUERY_COUNT)[0]) as last_file:
                violations = QueryCountEvaluator(10, current_file,last_file).run()
                if violations:
                    raise CommandError('There was at least one test with an API '
                                       'call excedding the allowed threshold.')
  4. Add a build step to run this command:

    Jenkins Build Action showing the script action

    After that, it will run fine, and the build would fail if any Query count is over the limit.


  • Include support for stacktraces in query_count_detail.json.

  • Generate an HTML report of executed Queries.

  • Make query count configurable

  • Include Jenkins support out of the box (using django_jenkins)

Running Tests

Does the code actually work?

source <YOURVIRTUALENV>/bin/activate
(myenv) $ pip install tox
(myenv) $ tox


PySchool is MIT Licensed. Copyright (c) 2017 Sophilabs, Inc.


This tool is maintained and funded by Sophilabs, Inc. The names and logos for sophilabs are trademarks of sophilabs, inc.

Tools used in rendering this package:


0.1.0 (2017-07-10)

  • First release on PyPI.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-test-query-counter-0.1.0.tar.gz (13.0 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page