From 8c78be660f69b4f0823494cf4063b9b144291542 Mon Sep 17 00:00:00 2001
From: Raphael Kimmig <raphael.kimmig@ampad.de>
Date: Tue, 26 Mar 2024 08:56:09 +0100
Subject: [PATCH] Fixed #11593 -- Added testing to reusable apps intro

---
 docs/intro/reusable-apps.txt     | 66 ++++++++++++++++++++++++
 docs/topics/testing/advanced.txt | 87 +++++++++++++++++++++++---------
 2 files changed, 129 insertions(+), 24 deletions(-)

diff --git a/docs/intro/reusable-apps.txt b/docs/intro/reusable-apps.txt
index 98f21c9d91..ea214fb213 100644
--- a/docs/intro/reusable-apps.txt
+++ b/docs/intro/reusable-apps.txt
@@ -314,6 +314,72 @@ working. We'll now fix this by installing our new ``django-polls`` package.
 
 #. Run the development server to confirm the project continues to work.
 
+Testing your app
+================
+
+Since we moved the ``polls`` directory out of the project, we don't have the
+project's ``settings.py`` and ``urls.py`` anymore. We need another way to
+configure our app in order to test it.
+
+#. First create a ``tests`` directory and move the tests over from the
+   ``polls`` directory. Because the tests now reside in a different module the
+   relative import ``from .models import Poll`` has to be changed to
+   ``from polls.models import Poll``.
+
+#. Now create a ``settings.py`` inside the ``tests`` folder which will contain
+   only the settings required to test the application.
+
+   .. code-block:: python
+       :caption: ``tests/settings.py``
+
+       from django.urls import include, path
+
+       SECRET_KEY = "fake-key"
+
+       INSTALLED_APPS = [
+           "polls",
+           # adding tests allows us to define models inside the tests package
+           # "tests",
+       ]
+
+       DATABASES = {
+           "default": {
+               "ENGINE": "django.db.backends.sqlite3",
+               "NAME": ":memory:",
+           }
+       }
+
+       TEMPLATES = [
+           {
+               "BACKEND": "django.template.backends.django.DjangoTemplates",
+               "APP_DIRS": True,
+           },
+       ]
+
+       ROOT_URLCONF = "tests.urls"
+
+#. Because the test involves views, a :setting:`ROOT_URLCONF` that includes our
+   app is needed. Create an appropriate ``urls.py`` inside the ``tests``
+   directory.
+
+   .. code-block:: python
+       :caption: ``tests/urls.py``
+
+       from django.urls import include, path
+
+       urlpatterns = [
+           path("polls/", include("polls.urls")),
+       ]
+
+#. Now run the tests.
+
+   .. code-block:: shell
+
+        python -m django test --settings=tests.settings tests
+
+For more information on testing reusable applications see :ref:`Advanced
+testing topics <testing-reusable-applications>`.
+
 Publishing your app
 ===================
 
diff --git a/docs/topics/testing/advanced.txt b/docs/topics/testing/advanced.txt
index 6b03f0f82b..5311fdb7c4 100644
--- a/docs/topics/testing/advanced.txt
+++ b/docs/topics/testing/advanced.txt
@@ -421,7 +421,6 @@ following structure:
 
 .. code-block:: text
 
-    runtests.py
     polls/
         __init__.py
         models.py
@@ -429,11 +428,70 @@ following structure:
     tests/
         __init__.py
         models.py
-        test_settings.py
+        settings.py
         tests.py
+        urls.py
 
 Let's take a look inside a couple of those files:
 
+.. code-block:: python
+   :caption: ``tests/settings.py``
+
+   from django.urls import include, path
+
+   SECRET_KEY = "fake-key"
+
+   INSTALLED_APPS = [
+       "polls",
+       # adding tests allows us to define models inside the tests package
+       "tests",
+   ]
+
+   DATABASES = {
+       "default": {
+           "ENGINE": "django.db.backends.sqlite3",
+           "NAME": ":memory:",
+       }
+   }
+
+   TEMPLATES = [
+       {
+           "BACKEND": "django.template.backends.django.DjangoTemplates",
+           "APP_DIRS": True,
+       },
+   ]
+
+   ROOT_URLCONF = "tests.urls"
+
+This file contains the :doc:`Django settings </topics/settings>` required to
+run your app's tests.
+
+Since the *tests* package is included in :setting:`INSTALLED_APPS` when running
+your tests, you can define test-only models in its ``models.py`` file.
+
+
+.. code-block:: python
+   :caption: ``tests/urls.py``
+
+   from django.urls import include, path
+
+   urlpatterns = [
+       path("polls/", include("polls.urls")),
+   ]
+
+If you want to test views, you need a :setting:`ROOT_URLCONF` that includes
+your app.
+
+
+You can then invoke the test runner using
+
+.. code-block:: shell
+
+    python -m django test --settings=tests.settings tests
+
+If you need a more complicated setup, you can create a custom ``runtests.py``
+to manually initialize the test runner.
+
 .. code-block:: python
     :caption: ``runtests.py``
 
@@ -446,7 +504,7 @@ Let's take a look inside a couple of those files:
     from django.test.utils import get_runner
 
     if __name__ == "__main__":
-        os.environ["DJANGO_SETTINGS_MODULE"] = "tests.test_settings"
+        os.environ["DJANGO_SETTINGS_MODULE"] = "tests.settings"
         django.setup()
         TestRunner = get_runner(settings)
         test_runner = TestRunner()
@@ -454,33 +512,14 @@ Let's take a look inside a couple of those files:
         sys.exit(bool(failures))
 
 
-This is the script that you invoke to run the test suite. It sets up the
-Django environment, creates the test database and runs the tests.
+You can use use this script to run the test suite. It sets up the Django
+environment, creates the test database and runs the tests.
 
 For the sake of clarity, this example contains only the bare minimum
 necessary to use the Django test runner. You may want to add
 command-line options for controlling verbosity, passing in specific test
 labels to run, etc.
 
-.. code-block:: python
-    :caption: ``tests/test_settings.py``
-
-    SECRET_KEY = "fake-key"
-    INSTALLED_APPS = [
-        "tests",
-    ]
-
-This file contains the :doc:`Django settings </topics/settings>`
-required to run your app's tests.
-
-Again, this is a minimal example; your tests may require additional
-settings to run.
-
-Since the *tests* package is included in :setting:`INSTALLED_APPS` when
-running your tests, you can define test-only models in its ``models.py``
-file.
-
-
 .. _other-testing-frameworks:
 
 Using different testing frameworks