Tooling and test execution support for Django ๐ฆ
โค๏ธ Support Django development by donating to the Django Software Foundation.
Make sure that you have Docker installed.
Clone this repository as well as the Django repository, e.g.
$ mkdir ~/Sources $ cd ~/Sources $ git clone https://github.com/django/django.git $ git clone https://github.com/django/django-docker-box.git $ cd django-docker-box
Important
As long as the two repositories are adjacent the Django source repository will be discovered. A different path can be specified by setting the DJANGO_PATH environment variable.
Build the image:
$ docker compose build sqlite
Run the tests:
$ docker compose run --rm sqlite
All of the test commands detailed below can be passed additional arguments that are provided to the runtests.py entrypoint. You can see a list of these arguments by running the following command:
$ docker compose run --rm sqlite --help
To run the standard set of tests you can use the following commands:
$ docker compose run --rm mariadb $ docker compose run --rm mysql $ docker compose run --rm oracle $ docker compose run --rm postgresql $ docker compose run --rm sqlite
Each of the above commands will run the test suite for a different supported database.
More information about running the unit tests for Django can be found in the documentation.
To run tests on geospatial features you can use the following commands:
$ docker compose run --rm mariadb-gis $ docker compose run --rm mysql-gis $ docker compose run --rm oracle-gis $ docker compose run --rm postgresql-gis $ docker compose run --rm sqlite-gis
Each of the above commands will run the test suite for a different supported geospatial database.
Tip
To only run the subset of tests for geospatial features, pass gis_tests as an argument to specify that only that folder of tests should be collected, e.g.
$ docker compose run --rm sqlite-gis gis_tests
More information about running the GeoDjango tests for Django can be found in the documentation.
To run tests on user interfaces you can use the following commands:
$ docker compose run --rm chrome $ docker compose run --rm edge $ docker compose run --rm firefox
Each of the above commands will run the subset of user interface tests for a different supported web browser. The tests are executed using Selenium.
To capture screenshots of certain test cases used for comparison to avoid regressions, the --screenshots flag can be passed.
More information about running the Selenium tests for Django can be found in the documentation.
Django uses the following linting and formatting tools: black, flake8, isort, and eslint. To ensure that the correct versions are used, Django also supports using pre-commit which is the mechanism provided here:
$ docker compose run --rm pre-commit
You can run individual tools by passing them as an argument:
$ docker compose run --rm pre-commit black $ docker compose run --rm pre-commit blacken-docs $ docker compose run --rm pre-commit isort $ docker compose run --rm pre-commit flake8 $ docker compose run --rm pre-commit eslint # XXX: Currently not working.
More information about Django's coding style can be found in the documentation.
Documentation for Django is built using Sphinx. Run the following to see the available commands:
$ docker compose run --rm sphinx
You may find the following builders particularly useful when working on documentation improvements:
$ docker compose run --rm sphinx dirhtml $ docker compose run --rm sphinx spelling $ docker compose run --rm sphinx linkcheck
The BUILDDIR environment variable has been set to generate output into the ./output/docs path under this repository instead of the usual location in the Django source repository. You can alter this environment variable to generate to a different path if required.
More information about writing documentation for Django can be found in the documentation.
To enter a shell within the container, run:
$ docker compose run --rm --entrypoint=bash sqlite
The build of the container image can be customized by setting the following environment variables:
Environment Variable Default Value DescriptionDJANGO_PATH ../django Path to the Django repostory on your local machine PYTHON_IMPLEMENTATION python Implementation of Python to use โ python or pypy PYTHON_VERSION 3.12 Version of Python container image to use
The versions of various backend services can be switched by setting these environment variables:
Environment Variable Default Value DescriptionMARIADB_VERSION 10.6 Version of MariaDB container image to use MYSQL_VERSION 8.0 Version of MySQL container image to use ORACLE_VERSION 23.5.0.0 Version of Oracle container image to use POSTGRESQL_VERSION 14 Version of PostgreSQL container image to use POSTGIS_VERSION 3.1 Version of PostGIS extension to use
The PYTHON_VERSION environment variable controls which version of Python you are running the tests against, e.g.
$ PYTHON_VERSION=3.12 docker compose run --rm sqlite
In addition, it's possible to select a different implementation of Python, i.e. PyPy instead of CPython, by setting the PYTHON_IMPLEMENTATION environment variable, e.g.
$ PYTHON_IMPLEMENTATION=pypy docker compose run --rm sqlite
Be warned, however, that support for PyPy is not as complete and there are more restrictions with respect to the range of versions available.
Most database container images are pulled from Docker Hub. Oracle database is pulled from the Oracle Container Registry.
You can switch the version of the database you test against by changing the appropriate environment variable. Available options and their defaults can be found in the configuration section.
Warning
Be aware that only a single version of a particular database may be running at one time, so you will need to ensure that you tear down the previously running instance before starting up the new one, e.g.
$ docker compose ps --format='{{.Image}}' postgresql-db
postgres:13-alpine
$ docker compose down postgresql-db
[+] Running 1/1
โ Container django-docker-box-postgresql-db-1 Removed 0.2s
$ POSTGRESQL_VERSION=17 docker compose up --detach postgresql-db
[+] Running 1/1
โ Container django-docker-box-postgresql-db-1 Started 0.3s
$ docker compose ps --format='{{.Image}}' postgresql-db
postgres:17-alpine
Alternatively, run the following to tear down the whole stack before bringing up new containers running different versions:
Note
Unlike other GIS database backends, for PostgreSQL with PostGIS you will need to specify both versions:
$ POSTGRESQL_VERSION=17 POSTGIS_VERSION=3.5 docker compose up --detach postgresql-gis-db
To determine what database versions can be used you can check the release notes for the branch of Django that you have checked out, or alternatively there is the supported database versions page on Django's Trac Wiki.
For the Memcached, Redis, and Selenium container images, the latest container image tag is always used.
Where possible, for backend services, we also use Alpine images where available for smaller image size and sometimes improved performance.
The following list is a collection of ideas for improvements that could be made with no promises that they'll be delivered:
./output/screenshots/RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4