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
|
|
@ -2,6 +2,8 @@
|
|||
How to install Django on Windows
|
||||
================================
|
||||
|
||||
.. highlight:: doscon
|
||||
|
||||
This document will guide you through installing Python 3.7 and Django on
|
||||
Windows. It also provides instructions for installing `virtualenv`_ and
|
||||
`virtualenvwrapper`_, which make it easier to work on Python projects. This is
|
||||
|
|
@ -21,13 +23,18 @@ machine. At the time of writing, Python 3.7 is the latest version.
|
|||
|
||||
To install Python on your machine go to https://python.org/downloads/. The
|
||||
website should offer you a download button for the latest Python version.
|
||||
Download the executable installer and run it. Check the box next to ``Add
|
||||
Python 3.7 to PATH`` and then click ``Install Now``.
|
||||
Download the executable installer and run it. Check the boxes next to ``Install
|
||||
launcher for all users (recommended)`` and ``Add Python 3.7 to PATH`` then
|
||||
click ``Install Now``.
|
||||
|
||||
After installation, open the command prompt and check that the Python version
|
||||
matches the version you installed by executing::
|
||||
|
||||
python --version
|
||||
...\> py --version
|
||||
|
||||
.. seealso::
|
||||
|
||||
For more details, see :doc:`python:using/windows` documentation.
|
||||
|
||||
About ``pip``
|
||||
=============
|
||||
|
|
@ -42,6 +49,8 @@ get-pip.py`` instructions.
|
|||
|
||||
.. _pip: https://pypi.org/project/pip/
|
||||
|
||||
.. _virtualenvwrapper-win:
|
||||
|
||||
Install ``virtualenv`` and ``virtualenvwrapper``
|
||||
================================================
|
||||
|
||||
|
|
@ -50,17 +59,17 @@ each Django project you create. While not mandatory, this is considered a best
|
|||
practice and will save you time in the future when you're ready to deploy your
|
||||
project. Simply type::
|
||||
|
||||
python -m pip install virtualenvwrapper-win
|
||||
...\> py -m pip install virtualenvwrapper-win
|
||||
|
||||
Then create a virtual environment for your project::
|
||||
|
||||
mkvirtualenv myproject
|
||||
...\> mkvirtualenv myproject
|
||||
|
||||
The virtual environment will be activated automatically and you'll see
|
||||
"(myproject)" next to the command prompt to designate that. If you start a new
|
||||
command prompt, you'll need to activate the environment again using::
|
||||
|
||||
workon myproject
|
||||
...\> workon myproject
|
||||
|
||||
.. _virtualenv: https://pypi.org/project/virtualenv/
|
||||
.. _virtualenvwrapper: https://pypi.org/project/virtualenvwrapper-win/
|
||||
|
|
@ -73,7 +82,7 @@ Django can be installed easily using ``pip`` within your virtual environment.
|
|||
In the command prompt, ensure your virtual environment is active, and execute
|
||||
the following command::
|
||||
|
||||
python -m pip install django
|
||||
...\> py -m pip install Django
|
||||
|
||||
This will download and install the latest Django release.
|
||||
|
||||
|
|
@ -92,9 +101,9 @@ Common pitfalls
|
|||
running Python scripts in ``PATH``. This usually occurs when there is more
|
||||
than one Python version installed.
|
||||
|
||||
* If you are connecting to the internet behind a proxy, there might be problem
|
||||
in running the command ``python -m pip install django``. Set the environment
|
||||
* If you are connecting to the internet behind a proxy, there might be problems
|
||||
in running the command ``py -m pip install Django``. Set the environment
|
||||
variables for proxy configuration in the command prompt as follows::
|
||||
|
||||
set http_proxy=http://username:password@proxyserver:proxyport
|
||||
set https_proxy=https://username:password@proxyserver:proxyport
|
||||
...\> set http_proxy=http://username:password@proxyserver:proxyport
|
||||
...\> set https_proxy=https://username:password@proxyserver:proxyport
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -150,6 +150,10 @@ If the ``source`` command is not available, you can try using a dot instead:
|
|||
|
||||
$ . ~/.virtualenvs/djangodev/bin/activate
|
||||
|
||||
You have to activate the virtual environment whenever you open a new
|
||||
terminal window. virtualenvwrapper__ is a useful tool for making this
|
||||
more convenient.
|
||||
|
||||
.. admonition:: For Windows users
|
||||
|
||||
To activate your virtual environment on Windows, run:
|
||||
|
|
@ -158,9 +162,12 @@ If the ``source`` command is not available, you can try using a dot instead:
|
|||
|
||||
...\> %HOMEPATH%\.virtualenvs\djangodev\Scripts\activate.bat
|
||||
|
||||
You have to activate the virtual environment whenever you open a new
|
||||
terminal window. virtualenvwrapper__ is a useful tool for making this
|
||||
more convenient.
|
||||
or you can install :ref:`a Windows version of virtualenvwrapper
|
||||
<virtualenvwrapper-win>` and then use:
|
||||
|
||||
.. code-block:: doscon
|
||||
|
||||
...\> workon djangodev
|
||||
|
||||
__ https://virtualenvwrapper.readthedocs.io/en/latest/
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue