mirror of
https://github.com/django/django.git
synced 2025-08-30 07:17:49 +00:00
Fixed #30387 -- Enhanced docs CLI examples in Unit tests and Install Django on Windows.
Follow up to 37c17846ad.
This commit is contained in:
Ramiro Morales
Mariusz Felisiak
parent
405c836336
commit
25b5eea8cd
3 changed files with 100 additions and 42 deletions
|
|
@ -2,8 +2,6 @@
|
|||
Unit tests
|
||||
==========
|
||||
|
||||
.. highlight:: console
|
||||
|
||||
Django comes with a test suite of its own, in the ``tests`` directory of the
|
||||
code base. It's our policy to make sure all tests pass at all times.
|
||||
|
||||
|
|
@ -26,7 +24,9 @@ First, `fork Django on GitHub <https://github.com/django/django/fork>`__.
|
|||
Second, create and activate a virtual environment. If you're not familiar with
|
||||
how to do that, read our :doc:`contributing tutorial </intro/contributing>`.
|
||||
|
||||
Next, clone your fork, install some requirements, and run the tests::
|
||||
Next, clone your fork, install some requirements, and run the tests:
|
||||
|
||||
.. console::
|
||||
|
||||
$ git clone git@github.com:YourGitHubName/django.git django-repo
|
||||
$ cd django-repo/tests
|
||||
|
|
@ -50,11 +50,6 @@ settings module that uses the SQLite database. See
|
|||
:ref:`running-unit-tests-settings` to learn how to use a different settings
|
||||
module to run the tests with a different database.
|
||||
|
||||
.. admonition:: Windows users
|
||||
|
||||
We recommend something like `Git Bash <https://msysgit.github.io/>`_ to run
|
||||
the tests using the above approach.
|
||||
|
||||
Having problems? See :ref:`troubleshooting-unit-tests` for some common issues.
|
||||
|
||||
Running tests using ``tox``
|
||||
|
|
@ -66,7 +61,9 @@ checks that our build server performs on pull requests. To run the unit tests
|
|||
and other checks (such as :ref:`import sorting <coding-style-imports>`, the
|
||||
:ref:`documentation spelling checker <documentation-spelling-check>`, and
|
||||
:ref:`code formatting <coding-style-python>`), install and run the ``tox``
|
||||
command from any place in the Django source tree::
|
||||
command from any place in the Django source tree:
|
||||
|
||||
.. console::
|
||||
|
||||
$ python -m pip install tox
|
||||
$ tox
|
||||
|
|
@ -75,7 +72,9 @@ By default, ``tox`` runs the test suite with the bundled test settings file for
|
|||
SQLite, ``flake8``, ``isort``, and the documentation spelling checker. In
|
||||
addition to the system dependencies noted elsewhere in this documentation,
|
||||
the command ``python3`` must be on your path and linked to the appropriate
|
||||
version of Python. A list of default environments can be seen as follows::
|
||||
version of Python. A list of default environments can be seen as follows:
|
||||
|
||||
.. console::
|
||||
|
||||
$ tox -l
|
||||
py3
|
||||
|
|
@ -91,7 +90,9 @@ for other versions of Python and other database backends. Since Django's test
|
|||
suite doesn't bundle a settings file for database backends other than SQLite,
|
||||
however, you must :ref:`create and provide your own test settings
|
||||
<running-unit-tests-settings>`. For example, to run the tests on Python 3.7
|
||||
using PostgreSQL::
|
||||
using PostgreSQL:
|
||||
|
||||
.. console::
|
||||
|
||||
$ tox -e py37-postgres -- --settings=my_postgres_settings
|
||||
|
||||
|
|
@ -105,10 +106,19 @@ The remainder of this documentation shows commands for running tests without
|
|||
``tox`` by prefixing the argument list with ``--``, as above.
|
||||
|
||||
Tox also respects the ``DJANGO_SETTINGS_MODULE`` environment variable, if set.
|
||||
For example, the following is equivalent to the command above::
|
||||
For example, the following is equivalent to the command above:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ DJANGO_SETTINGS_MODULE=my_postgres_settings tox -e py35-postgres
|
||||
|
||||
Windows users should use:
|
||||
|
||||
.. code-block:: doscon
|
||||
|
||||
...\> set DJANGO_SETTINGS_MODULE=my_postgres_settings
|
||||
...\> tox -e py35-postgres
|
||||
|
||||
Running the JavaScript tests
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
|
@ -116,7 +126,9 @@ Django includes a set of :ref:`JavaScript unit tests <javascript-tests>` for
|
|||
functions in certain contrib apps. The JavaScript tests aren't run by default
|
||||
using ``tox`` because they require `Node.js` to be installed and aren't
|
||||
necessary for the majority of patches. To run the JavaScript tests using
|
||||
``tox``::
|
||||
``tox``:
|
||||
|
||||
.. console::
|
||||
|
||||
$ tox -e javascript
|
||||
|
||||
|
|
@ -178,7 +190,9 @@ tests by appending the names of the test modules to ``runtests.py`` on the
|
|||
command line.
|
||||
|
||||
For example, if you'd like to run tests only for generic relations and
|
||||
internationalization, type::
|
||||
internationalization, type:
|
||||
|
||||
.. console::
|
||||
|
||||
$ ./runtests.py --settings=path.to.settings generic_relations i18n
|
||||
|
||||
|
|
@ -187,11 +201,15 @@ directory name there is the name of a test.
|
|||
|
||||
If you just want to run a particular class of tests, you can specify a list of
|
||||
paths to individual test classes. For example, to run the ``TranslationTests``
|
||||
of the ``i18n`` module, type::
|
||||
of the ``i18n`` module, type:
|
||||
|
||||
.. console::
|
||||
|
||||
$ ./runtests.py --settings=path.to.settings i18n.tests.TranslationTests
|
||||
|
||||
Going beyond that, you can specify an individual test method like this::
|
||||
Going beyond that, you can specify an individual test method like this:
|
||||
|
||||
.. console::
|
||||
|
||||
$ ./runtests.py --settings=path.to.settings i18n.tests.TranslationTests.test_lazy_objects
|
||||
|
||||
|
|
@ -201,7 +219,9 @@ Running the Selenium tests
|
|||
Some tests require Selenium and a Web browser. To run these tests, you must
|
||||
install the selenium_ package and run the tests with the
|
||||
``--selenium=<BROWSERS>`` option. For example, if you have Firefox and Google
|
||||
Chrome installed::
|
||||
Chrome installed:
|
||||
|
||||
.. console::
|
||||
|
||||
$ ./runtests.py --selenium=firefox,chrome
|
||||
|
||||
|
|
@ -238,7 +258,9 @@ dependencies:
|
|||
|
||||
You can find these dependencies in `pip requirements files`_ inside the
|
||||
``tests/requirements`` directory of the Django source tree and install them
|
||||
like so::
|
||||
like so:
|
||||
|
||||
.. console::
|
||||
|
||||
$ python -m pip install -r tests/requirements/py3.txt
|
||||
|
||||
|
|
@ -288,11 +310,15 @@ that need additional tests. The coverage tool installation and use is described
|
|||
in :ref:`testing code coverage<topics-testing-code-coverage>`.
|
||||
|
||||
Coverage should be run in a single process to obtain accurate statistics. To
|
||||
run coverage on the Django test suite using the standard test settings::
|
||||
run coverage on the Django test suite using the standard test settings:
|
||||
|
||||
.. console::
|
||||
|
||||
$ coverage run ./runtests.py --settings=test_sqlite --parallel=1
|
||||
|
||||
After running coverage, generate the html report by running::
|
||||
After running coverage, generate the html report by running:
|
||||
|
||||
.. console::
|
||||
|
||||
$ coverage html
|
||||
|
||||
|
|
@ -321,12 +347,16 @@ Many test failures with ``UnicodeEncodeError``
|
|||
If the ``locales`` package is not installed, some tests will fail with a
|
||||
``UnicodeEncodeError``.
|
||||
|
||||
You can resolve this on Debian-based systems, for example, by running::
|
||||
You can resolve this on Debian-based systems, for example, by running:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ apt-get install locales
|
||||
$ dpkg-reconfigure locales
|
||||
|
||||
You can resolve this for macOS systems by configuring your shell's locale::
|
||||
You can resolve this for macOS systems by configuring your shell's locale:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ export LANG="en_US.UTF-8"
|
||||
$ export LC_ALL="en_US.UTF-8"
|
||||
|
|
@ -347,7 +377,9 @@ it possible to identify a small number of tests that may be related to the
|
|||
failure.
|
||||
|
||||
For example, suppose that the failing test that works on its own is
|
||||
``ModelTest.test_eq``, then using::
|
||||
``ModelTest.test_eq``, then using:
|
||||
|
||||
.. console::
|
||||
|
||||
$ ./runtests.py --bisect basic.tests.ModelTest.test_eq
|
||||
|
||||
|
|
@ -361,7 +393,9 @@ failing tests is minimized.
|
|||
|
||||
The ``--pair`` option runs the given test alongside every other test from the
|
||||
suite, letting you check if another test has side-effects that cause the
|
||||
failure. So::
|
||||
failure. So:
|
||||
|
||||
.. console::
|
||||
|
||||
$ ./runtests.py --pair basic.tests.ModelTest.test_eq
|
||||
|
||||
|
|
@ -370,13 +404,17 @@ will pair ``test_eq`` with every test label.
|
|||
With both ``--bisect`` and ``--pair``, if you already suspect which cases
|
||||
might be responsible for the failure, you may limit tests to be cross-analyzed
|
||||
by :ref:`specifying further test labels <runtests-specifying-labels>` after
|
||||
the first one::
|
||||
the first one:
|
||||
|
||||
.. console::
|
||||
|
||||
$ ./runtests.py --pair basic.tests.ModelTest.test_eq queries transactions
|
||||
|
||||
You can also try running any set of tests in reverse using the ``--reverse``
|
||||
option in order to verify that executing tests in a different order does not
|
||||
cause any trouble::
|
||||
cause any trouble:
|
||||
|
||||
.. console::
|
||||
|
||||
$ ./runtests.py basic --reverse
|
||||
|
||||
|
|
@ -385,7 +423,9 @@ Seeing the SQL queries run during a test
|
|||
|
||||
If you wish to examine the SQL being run in failing tests, you can turn on
|
||||
:ref:`SQL logging <django-db-logger>` using the ``--debug-sql`` option. If you
|
||||
combine this with ``--verbosity=2``, all SQL queries will be output::
|
||||
combine this with ``--verbosity=2``, all SQL queries will be output:
|
||||
|
||||
.. console::
|
||||
|
||||
$ ./runtests.py basic --debug-sql
|
||||
|
||||
|
|
@ -394,7 +434,9 @@ Seeing the full traceback of a test failure
|
|||
|
||||
By default tests are run in parallel with one process per core. When the tests
|
||||
are run in parallel, however, you'll only see a truncated traceback for any
|
||||
test failures. You can adjust this behavior with the ``--parallel`` option::
|
||||
test failures. You can adjust this behavior with the ``--parallel`` option:
|
||||
|
||||
.. console::
|
||||
|
||||
$ ./runtests.py basic --parallel=1
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue