Documentation - update testing page with WagtailPageTestCase

- Docs for #9294

docs/advanced_topics/testing.md

@@ -1,23 +1,127 @@
-(reference)=
+(testing_reference)=
 
 # Testing your Wagtail site
 
 Wagtail comes with some utilities that simplify writing tests for your site.
 
-## WagtailPageTests
+## WagtailPageTestCase
 
-**_class_ wagtail.test.utils.WagtailPageTests**
-`WagtailPageTests` extends `django.test.TestCase`, adding a few new `assert` methods. You should extend this class to make use of its methods:
+**_class_ wagtail.test.utils.WagtailPageTestCase**
+`WagtailPageTestCase` extends `django.test.TestCase`, adding a few new `assert` methods. You should extend this class to make use of its methods:
 
 ```python
-from wagtail.test.utils import WagtailPageTests
+from wagtail.test.utils import WagtailPageTestCase
 from myapp.models import MyPage
 
-class MyPageTests(WagtailPageTests):
+class MyPageTests(WagtailPageTestCase):
     def test_can_create_a_page(self):
         ...
 ```
 
+**assertPageIsRoutable(_page, route_path="/", msg=None_)**
+
+Asserts that `page` can be routed to without raising a `Http404` error.
+
+For page types with multiple routes, you can use `route_path` to specify an alternate route to test.
+
+This assertion is great for getting coverage on custom routing logic for page types. Here is an example:
+
+```python
+from wagtail.test.utils import WagtailPageTestCase
+from myapp.models import EventListPage
+
+class EventListPageRoutabilityTests(WagtailPageTestCase):
+    @classmethod
+    def setUpTestData(cls):
+        # create page(s) for testing
+        ...
+
+    def test_default_route(self):
+        self.assertPageIsRoutable(self.page)
+
+    def test_year_archive_route(self):
+        # NOTE: Despite this page type raising a 404 when no events exist for
+        # the specified year, routing should still be successful
+        self.assertPageIsRoutable(self.page, "archive/year/1984/")
+
+```
+
+**assertPageIsRenderable(_page, route_path="/", query_data=None, post_data=None, user=None, accept_404=False, accept_redirect=False, msg=None_)**
+
+Asserts that `page` can be rendered without raising a fatal error.
+
+For page types with multiple routes, you can use `route_path` to specify a partial path to be added to the page's regular `url`.
+
+When `post_data` is provided, the test makes a `POST` request with `post_data` in the request body. Otherwise, a `GET` request is made.
+
+When supplied, `query_data` is always converted to a querystring and added to the request URL.
+
+When `user` is provided, the test is conducted with them as the active user.
+
+By default, the assertion will fail if the request to the page URL results in a 301, 302 or 404 HTTP response. If you are testing a page/route where a 404 response is expected, you can use `accept_404=True` to indicate this, and the assertion will pass when encountering a 404 response. Likewise, if you are testing a page/route where a redirect response is expected, you can use `accept_redirect=True` to indicate this, and the assertion will pass when encountering 301 or 302 response.
+
+This assertion is great for getting coverage on custom rendering logic for page types. Here is an example:
+
+```python
+def test_default_route_rendering(self):
+    self.assertPageIsRenderable(self.page)
+
+def test_year_archive_route_with_zero_matches(self):
+    # NOTE: Should raise a 404 when no events exist for the specified year
+    self.assertPageIsRenderable(self.page, "archive/year/1984/", accept_404=True)
+
+def test_month_archive_route_with_zero_matches(self):
+    # NOTE: Should redirect to year-specific view when no events exist for the specified month
+    self.assertPageIsRenderable(self.page, "archive/year/1984/07/", accept_redirect=True)
+```
+
+**assertPageIsEditable(_page, post_data=None, user=None, msg=None_)**
+
+Asserts that the page edit view works for `page` without raising a fatal error.
+
+When `user` is provided, the test is conducted with them as the active user. Otherwise, a superuser is created and used for the test.
+
+After a successful `GET` request, a `POST` request is made with field data in the request body. If `post_data` is provided, that will be used for this purpose. If not, this data will be extracted from the `GET` response HTML.
+
+This assertion is great for getting coverage on custom fields, panel configuration and custom validation logic. Here is an example:
+
+```python
+def test_editability(self):
+    self.assertPageIsEditable(self.page)
+
+def test_editability_on_post(self):
+    self.assertPageIsEditable(
+        self.page,
+        post_data={
+            "title": "Fabulous events",
+            "slug": "events",
+            "show_featured": True,
+            "show_expired": False,
+            "action-publish": "",
+        }
+    )
+```
+
+**assertPageIsPreviewable(_page, mode="", post_data=None, user=None, msg=None_)**
+
+Asserts that the page preview view can be loaded for `page` without raising a fatal error.
+
+For page types that support different preview modes, you can use `mode` to specify the preview mode to be tested.
+
+When `user` is provided, the test is conducted with them as the active user. Otherwise, a superuser is created and used for the test.
+
+To load the preview, the test client needs to make a `POST` request including all required field data in the request body. If `post_data` is provided, that will be used for this purpose. If not, the method will attempt to extract this data from the page edit view.
+
+This assertion is great for getting coverage on custom preview modes, or getting reassurance that custom rendering logic is compatible with Wagtail's preview mode. Here is an example:
+
+```python
+def test_general_previewability(self):
+    self.assertPageIsPreviewable(self.page)
+
+def test_archive_previewability(self):
+    self.assertPageIsPreviewable(self.page, mode="year-archive")
+```
+
 **assertCanCreateAt(_parent_model, child_model, msg=None_)**
 Assert a particular child Page type can be created under a parent Page type. `parent_model` and `child_model` should be the Page classes being tested.