Refs #34043 -- Added --screenshots option to runtests.py and selenium tests.

1 files changed, 31 insertions, 0 deletions

diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt
index 4f5cbeb125..1e86a5802d 100644
--- a/docs/internals/contributing/writing-code/unit-tests.txt
+++ b/docs/internals/contributing/writing-code/unit-tests.txt
@@ -271,6 +271,37 @@ faster and more stable. Add the ``--headless`` option to enable this mode.
 
 .. _selenium.webdriver: https://github.com/SeleniumHQ/selenium/tree/trunk/py/selenium/webdriver
 
+For testing changes to the admin UI, the selenium tests can be run with the
+``--screenshots`` option enabled. Screenshots will be saved to the
+``tests/screenshots/`` directory.
+
+To define when screenshots should be taken during a selenium test, the test
+class must use the ``@django.test.selenium.screenshot_cases`` decorator with a
+list of supported screenshot types (``"desktop_size"``, ``"mobile_size"``,
+``"small_screen_size"``, ``"rtl"``, and ``"dark"``). It can then call
+``self.take_screenshot("unique-screenshot-name")`` at the desired point to
+generate the screenshots. For example::
+
+    from django.test.selenium import SeleniumTestCase, screenshot_cases
+    from django.urls import reverse
+
+
+    class SeleniumTests(SeleniumTestCase):
+        @screenshot_cases(["desktop_size", "mobile_size", "rtl", "dark"])
+        def test_login_button_centered(self):
+            self.selenium.get(self.live_server_url + reverse("admin:login"))
+            self.take_screenshot("login")
+            ...
+
+This generates multiple screenshots of the login page - one for a desktop
+screen, one for a mobile screen, one for right-to-left languages on desktop,
+and one for the dark mode on desktop.
+
+.. versionchanged:: 5.1
+
+     The ``--screenshots`` option and ``@screenshot_cases`` decorator were
+     added.
+
 .. _running-unit-tests-dependencies:
 
 Running all the tests