From 0b3c20556d4777f7bb664218f62e166cf1a20471 Mon Sep 17 00:00:00 2001
From: Kees Hink <keeshink@gmail.com>
Date: Thu, 26 Apr 2018 09:31:08 +0200
Subject: [PATCH] Docs: How to create test fixtures for custom Page models

---
 docs/advanced_topics/testing.rst | 63 ++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/docs/advanced_topics/testing.rst b/docs/advanced_topics/testing.rst
index bf34d04a5..e9984c3d3 100644
--- a/docs/advanced_topics/testing.rst
+++ b/docs/advanced_topics/testing.rst
@@ -8,6 +8,7 @@ Wagtail comes with some utilities that simplify writing tests for your site.
 
 .. automodule:: wagtail.tests.utils
 
+
 WagtailPageTests
 ================
 
@@ -102,3 +103,65 @@ Form data helpers
    .. autofunction:: streamfield
 
    .. autofunction:: inline_formset
+
+
+
+Fixtures
+========
+
+Using ``dumpdata``
+------------------
+
+Creating fixtures_ for tests is best done by creating content in a development environment,
+and using Django's dumpdata_ command.
+
+Note that by default ``dumpdata`` will represent ``content_type`` by the primary key; this may cause consistency issues when adding / removing models, as content types are populated separately from fixtures. To prevent this, use the ``--natural-foreign`` switch, which represents content types by ``["app", "model"]`` instead.
+
+
+Manual modification
+-------------------
+
+You could modify the dumped fixtures manually, or even write them all by hand.
+Here are a few things to be wary of.
+
+
+Custom Page models
+~~~~~~~~~~~~~~~~~~
+
+When creating customised Page models in fixtures, you will need to add both a
+``wagtailcore.page`` entry, and one for your custom Page model.
+
+Let's say you have a ``website`` module which defines a ``Homepage(Page)`` class.
+You could create such a homepage in a fixture with:
+
+.. code-block:: json
+
+    [
+      {
+        "model": "wagtailcore.page",
+        "pk": 3,
+        "fields": {
+          "title": "My Customer's Homepage",
+          "content_type": ["website", "homepage"],
+          "depth": 2
+        }
+      },
+      {
+        "model": "website.homepage",
+        "pk": 3,
+        "fields": {}
+      }
+    ]
+
+
+Treebeard fields
+~~~~~~~~~~~~~~~~
+
+Filling in the ``path`` / ``numchild`` / ``depth`` fields is necessary in order for tree operations like ``get_parent()`` to work correctly.
+``url_path`` is another field that can cause errors in some uncommon cases if it isn't filled in.
+
+The `Treebeard docs`_ might help in understanding how this works.
+
+.. _fixtures: https://docs.djangoproject.com/en/2.0/howto/initial-data/
+.. _dumpdata: https://docs.djangoproject.com/en/2.0/ref/django-admin/#django-admin-dumpdata
+.. _Treebeard docs: http://django-treebeard.readthedocs.io/en/latest/mp_tree.html