diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt index 6799b31871..d5fdb72561 100644 --- a/docs/internals/contributing/writing-code/unit-tests.txt +++ b/docs/internals/contributing/writing-code/unit-tests.txt @@ -21,28 +21,42 @@ Running the unit tests Quickstart ---------- -If you are on Python 2, you'll first need to install a backport of the -``unittest.mock`` module that's available in Python 3. See -:ref:`running-unit-tests-dependencies` for details on installing `mock`_ and -the other optional test dependencies. +First, `fork Django on GitHub +`__. -Running the tests requires a Django settings module that defines the -databases to use. To make it easy to get started, Django provides and uses a -sample settings module that uses the SQLite database. To run the tests:: +Second, create and activate a virtual environment. If you're not familiar with +how to do that, read our :doc:`contributing tutorial `. - $ git clone https://github.com/django/django.git django-repo +Next, clone your fork, install some requirements, and run the tests:: + + $ git clone git@github.com:YourGitHubName/django.git django-repo $ cd django-repo/tests - $ PYTHONPATH=..:$PYTHONPATH ./runtests.py + $ pip install -e .. + $ pip install -r requirements/py3.txt # Python 2: py2.txt + $ ./runtests.py + +Installing the requirements will likely require some operating system packages +that your computer doesn't have installed. You can usually figure out which +package to install by doing a Web search for the last line or so of the error +message. Try adding your operating system to the search query if needed. + +If you have trouble installing the requirements, you can skip that step, except +on Python 2, where you must ``pip install mock``. See +:ref:`running-unit-tests-dependencies` for details on installing the optional +test dependencies. If you don't have an optional dependency installed, the +tests that require it will be skipped. + +Running the tests requires a Django settings module that defines the databases +to use. To make it easy to get started, Django provides and uses a sample +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 `_ to run the tests using the above approach. -You can avoid typing the ``PYTHONPATH`` bit each time by adding your Django -checkout to your ``PYTHONPATH`` or by installing the source checkout using pip. -See :ref:`installing-development-version`. - Having problems? See :ref:`troubleshooting-unit-tests` for some common issues. Running tests using ``tox`` diff --git a/docs/intro/contributing.txt b/docs/intro/contributing.txt index 0cc0394836..ce93f48974 100644 --- a/docs/intro/contributing.txt +++ b/docs/intro/contributing.txt @@ -111,14 +111,15 @@ Getting a copy of Django's development version ============================================== The first step to contributing to Django is to get a copy of the source code. -From the command line, use the ``cd`` command to navigate to the directory -where you'll want your local copy of Django to live. +First, `fork Django on GitHub `__. +Then, from the command line, use the ``cd`` command to navigate to the +directory where you'll want your local copy of Django to live. Download the Django source code repository using the following command: .. code-block:: console - $ git clone https://github.com/django/django.git + $ git clone git@github.com:YourGitHubName/django.git Now that you have a local copy of Django, you can install it just like you would install any package using ``pip``. The most convenient way to do so is by using diff --git a/tests/README.rst b/tests/README.rst index 73bce435e2..7d4ddb513a 100644 --- a/tests/README.rst +++ b/tests/README.rst @@ -1,8 +1,10 @@ -To run the test suite:: +To run the test suite, first, create and activate a virtual environment. Then +install some requirements and run the tests:: $ cd tests + $ pip install -e .. $ pip install -r requirements/py3.txt # or py2.txt - $ PYTHONPATH=..:$PYTHONPATH ./runtests.py + $ ./runtests.py For more information about the test suite, see https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/unit-tests/.