From be56c982c0805f62a2948d9d7a3e21215c352174 Mon Sep 17 00:00:00 2001 From: Sarah Boyce <42296566+sarahboyce@users.noreply.github.com> Date: Mon, 16 Oct 2023 12:01:58 +0200 Subject: Refs #34043 -- Added --screenshots option to runtests.py and selenium tests. --- .../contributing/writing-code/unit-tests.txt | 31 ++++++++++++++++++++++ 1 file changed, 31 insertions(+) (limited to 'docs/internals/contributing/writing-code') 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 -- cgit v1.3