Add docs for WagtailPageTests

docs/advanced_topics/index.rst

@@ -13,3 +13,4 @@ Advanced topics
     customisation/index
     third_party_tutorials
     jinja2
+    testing

docs/advanced_topics/testing.rst

@@ -0,0 +1,81 @@
+.. _reference:
+
+=========================
+Testing your Wagtail site
+=========================
+
+Wagtail comes with some utilities that simplify writing tests for your site.
+
+.. automodule:: wagtail.tests.utils
+
+WagtailPageTests
+================
+
+.. class:: WagtailPageTests
+
+    ``WagtailPageTests`` extends ``django.test.TestCase``, adding a few new ``assert`` methods. You should extend this class to make use of its methods:
+
+    .. code-block:: python
+
+        from wagtail.tests.utils import WagtailPageTests
+        from myapp.models import MyPage
+
+        class MyPageTests(WagtailPageTests):
+            def test_can_create_a_page(self):
+                ...
+
+    .. automethod:: assertCanCreateAt
+
+        .. code-block:: python
+
+            def test_can_create_under_home_page(self):
+                # You can create a ContentPage under a HomePage
+                self.assertCanCreateAt(HomePage, ContentPage)
+
+    .. automethod:: assertCanNotCreateAt
+
+        .. code-block:: python
+
+            def test_cant_create_under_event_page(self):
+                # You can not create a ContentPage under an EventPage
+                self.assertCanNotCreateAt(EventPage, ContentPage)
+
+    .. automethod:: assertCanCreate
+
+        .. code-block:: python
+
+            def test_can_create_content_page(self):
+                # Get the HomePage
+                root_page = HomePage.objects.get(pk=2)
+
+                # Assert that a ContentPage can be made here, with this POST data
+                self.assertCanCreate(root_page, ContentPage, {
+                    'title': 'About us',
+                    'body': 'Lorem ipsum dolor sit amet')
+
+    .. automethod:: assertAllowedParentPageTypes
+
+        .. code-block:: python
+
+            def test_content_page_parent_pages(self):
+                # A ContentPage can only be created under a HomePage
+                # or another ContentPage
+                self.assertAllowedParentPageTypes(
+                    ContentPage, {HomePage, ContentPage})
+
+                # An EventPage can only be created under an EventIndex
+                self.assertAllowedParentPageTypes(
+                    EventPage, {EventIndex})
+
+    .. automethod:: assertAllowedSubpageTypes
+
+        .. code-block:: python
+
+            def test_content_page_subpages(self):
+                # A ContentPage can only have other ContentPage children
+                self.assertAllowedSubpageTypes(
+                    ContentPage, {ContentPage})
+
+                # A HomePage can have ContentPage and EventIndex children
+                self.assertAllowedParentPageTypes(
+                    HomePage, {ContentPage, EventIndex})

wagtail/tests/utils.py

@@ -73,7 +73,8 @@ class WagtailPageTests(WagtailTestUtils, TestCase):
     def assertCanCreateAt(self, parent_model, child_model, msg=None):
         """
         Assert a particular child Page type can be created under a parent
-        Page type.
+        Page type. ``parent_model`` and ``child_model`` should be the Page
+        classes being tested.
         """
         if not self._testCanCreateAt(parent_model, child_model):
             msg = self._formatMessage(msg, "Can not create a %s.%s under a %s.%s" % (
@@ -84,7 +85,8 @@ class WagtailPageTests(WagtailTestUtils, TestCase):
     def assertCanNotCreateAt(self, parent_model, child_model, msg=None):
         """
         Assert a particular child Page type can not be created under a parent
-        Page type.
+        Page type. ``parent_model`` and ``child_model`` should be the Page
+        classes being tested.
         """
         if self._testCanCreateAt(parent_model, child_model):
             msg = self._formatMessage(msg, "Can create a %s.%s under a %s.%s" % (
@@ -95,7 +97,11 @@ class WagtailPageTests(WagtailTestUtils, TestCase):
     def assertCanCreate(self, parent, child_model, data, msg=None):
         """
         Assert that a child of the given Page type can be created under the
-        parent, using the supplied POST data
+        parent, using the supplied POST data.
+
+        ``parent`` should be a Page instance, and ``child_model`` should be a
+        Page subclass. ``data`` should be a dict that will be POSTed at the
+        Wagtail admin Page creation method.
         """
         self.assertCanCreateAt(parent.specific_class, child_model)