Registry / testing / wagtail-factories

wagtail-factories

JSON →
library4.5.0pypypi✓ verified 28d ago

Wagtail Factories provides factory_boy classes tailored for generating Wagtail-specific objects like Pages, Images, Documents, and StreamFields, making it easier to create test data or seed development environments. The library is currently at version 4.4.0 and maintains an active release cadence, frequently updating to support new Wagtail versions.

pip install wagtail-factories
INSTALL
IMPORT
SIG · WAGTAIL-FACTORIES
W
wagtail-factories
testingpythonv4.5.0
Install
12.6s avg
Import
—
Disk
238MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v4.5.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 242.3MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 12.6s · import 0.000s · 238MB
238MB installed
● package 238MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PageFactory
✓ from wagtail_factories import PageFactory
✗ from wagtail_factories import PageFactory

This quickstart demonstrates how to define a Wagtail page model with a StreamField and then create corresponding `wagtail-factories` for both the page and its StreamField blocks. It uses `StreamFieldFactory` to populate StreamField content and shows how to define factories for specific block types like `CharBlock`. The example highlights the use of `factory.Faker` for realistic data and `factory.Sequence` for unique titles, and notes that execution requires a Django/Wagtail environment.

import factory from django.db import models from wagtail.models import Page from wagtail.fields import RichTextField, StreamField from wagtail import blocks from wagtail_factories import PageFactory, StreamFieldFactory from wagtail_factories.blocks import CharBlockFactory # Define a simple Wagtail Page model class MyPage(Page): body = RichTextField(blank=True) content = StreamField([ ('heading', blocks.CharBlock(form_classname='full title')), ('paragraph', blocks.RichTextBlock()), ], use_json_field=True, blank=True) content_panels = Page.content_panels # Simplified for example # Define factories for the model and its StreamField blocks class HeadingBlockFactory(CharBlockFactory): class Meta: model = blocks.CharBlock # For CharBlockFactory itself class MyPageFactory(PageFactory): class Meta: model = MyPage title = factory.Sequence(lambda n: f'Test Page {n}') body = factory.Faker('text') content = StreamFieldFactory({ 'heading': HeadingBlockFactory, 'paragraph': StreamFieldFactory._do_nothing, # For simple blocks or when default behavior is fine }) # Example usage (requires Django environment setup) # To run this code, you'd typically need a Django project configured with Wagtail. # For testing purposes, you might use Django's test client or a custom setup. if __name__ == '__main__': print("This quickstart demonstrates factory definition. To create instances, run within a configured Django/Wagtail project.") print("Example: `page = MyPageFactory()` would create a page in your database.") # Example of creating a page (would run within a Django test or shell): # from django.test import TestCase # class MyTest(TestCase): # def test_page_creation(self): # page = MyPageFactory() # self.assertIsNotNone(page.pk) # print(f"Created page: {page.title}") # print(f"StreamField content keys: {[b.block_type for b in page.content]}")
Debug
Known issues
breakingWagtail Factories releases are tightly coupled to Wagtail versions. Upgrading `wagtail` often requires a corresponding upgrade of `wagtail-factories`. For example, v4.1.0 dropped support for Wagtail < 4.1, and v4.4.0 added support for Wagtail 7.
fix
Always check the `wagtail-factories` release notes and README for compatible Wagtail versions before upgrading either library. Ensure your `wagtail-factories` version supports your `wagtail` version.
affects: All versions, especially major upgrades
breakingThe usage of `StreamFieldFactory` was significantly changed in v3.0.0 with the introduction of `StreamBlockFactory`. Prior to this, `StreamFieldFactory` might have handled nested blocks implicitly, but now explicit block factories (e.g., `CharBlockFactory`, `ImageBlockFactory`) or `StreamFieldFactory._do_nothing` are often required for specific block types.
fix
Review your `StreamFieldFactory` definitions when upgrading from versions older than 3.0.0. You will likely need to explicitly define factories for individual StreamBlocks or use `StreamFieldFactory._do_nothing` for blocks where default behavior is desired. Consult the official documentation for updated `StreamFieldFactory` usage.
affects: <3.0.0
breakingIn v4.0.0, `ListBlockFactory` changed its return type for Wagtail versions >= 2.16 from a plain Python `list` to a `wagtail.blocks.list_block.ListValue`. This could affect existing code that expects a standard `list` object.
fix
Update any code that interacts with the output of `ListBlockFactory` to correctly handle `wagtail.blocks.list_block.ListValue` objects, which behave similarly to lists but are not identical.
affects: >=4.0.0 on Wagtail >= 2.16
breakingDependency on `factory_boy` has evolved. `wagtail-factories` v2.0.1 required `factory_boy>=3.0`, and v2.1.0 further required `factory_boy>=3.2`. Using an older `factory_boy` version will lead to compatibility errors.
fix
Ensure `factory_boy` is installed at a compatible version. For recent `wagtail-factories` versions (e.g., 4.x), `factory_boy>=3.2` is generally required. Consult `pyproject.toml` or `setup.py` for exact dependency ranges if issues arise.
affects: <2.1.0
Upgrade
Version history
4.5.0latest on PyPI · released Jun 4, 2026
Audit
Dependencies
wagtailrequiredCore functionality is tied to Wagtail. Ensure `wagtail-factories` version matches your `wagtail` version for compatibility.
factory_boyrequiredThe library is built on top of `factory_boy` for generating model instances.
Agent activity
28 hits · last 30 days
node
24
OpenAI (training)
1
Resources
wagtail-factories — pip install wagtail-factories · libregistry