How do I generate test data for Wagtail pages with wagtail-factories?

Use the PageFactory class to create Wagtail Page instances; define a factory subclass with your model and customize fields via keyword arguments, as shown in the MyTestPageFactory example in the README. This simplifies setting parent pages, titles, and nested StreamField data.

Can wagtail-factories handle Wagtail's ImageChooserBlock?

Yes, it provides an ImageChooserBlockFactory for generating image instances in tests. You can nest it within other factories, like in the MyCarouselItemFactory example, and customize attributes such as image titles using deep object syntax.

What's the best way to create nested StreamField blocks with wagtail-factories?

Use StreamBlockFactory subclasses with SubFactory wrappers for child blocks, as demonstrated in the MyStreamBlockFactory example. This allows building complex StreamValues with declarative syntax, though note that nested stream blocks require the new syntax from version 3.0.

How does wagtail-factories compare to using Django's built-in test fixtures?

Wagtail-factories is programmatic and dynamic, ideal for generating varied test data on-the-fly, while Django fixtures are static files better for consistent data. For Wagtail's complex models, factories reduce maintenance, but fixtures might be simpler for basic, unchanging data.

Is there a guide for upgrading wagtail-factories to version 3.0?

The README highlights key changes, such as requiring SubFactory wrappers for block factories in StreamFieldFactory definitions. Review the 'Alternative StreamFieldFactory declaration syntax' section and update old code to wrap factories like MyBlockFactory in factory.SubFactory() to avoid errors.

Does wagtail-factories work with custom Wagtail block models?

Yes, you can create custom factory classes by subclassing StructBlockFactory or other block factories and setting the model attribute in Meta, as shown with MyCarouselFactory. This allows generating instances of any Wagtail block type with customizable fields.

Wagtail Factories — Factory Boy for Wagtail CMS

What is Wagtail Factories?

Wagtail Factories is a Python library that provides Factory Boy classes for generating test data in Wagtail CMS projects. It allows developers to easily create instances of Wagtail pages, blocks, and other models for testing purposes. The library simplifies the process of setting up complex data structures like StreamFields with nested blocks.

Target Audience

Wagtail developers and Django developers who need to write tests for Wagtail-based applications and want a structured way to generate test fixtures.

Value Proposition

It offers a declarative and reusable approach to creating test data specifically tailored for Wagtail's data models, reducing boilerplate code and improving test reliability. Developers choose it because it integrates seamlessly with factory_boy and provides specialized factories for Wagtail's unique block and page structures.

Factory boy classes for wagtail

Use Cases

Best For

Generating test data for Wagtail Page models
Creating complex StreamField fixtures with nested blocks
Writing unit tests for Wagtail block components
Setting up test databases with realistic Wagtail content
Automating test data creation for Wagtail-based applications
Testing Wagtail's ListBlock and StructBlock implementations

Not Ideal For

Projects not built on Wagtail CMS, as the library is tightly coupled to Wagtail's data models and block system.
Teams that prefer static fixture files (e.g., JSON or YAML) for test data, since it relies on programmatic factory generation.
Simple Wagtail sites with minimal custom pages or blocks, where the overhead of setting up factories may outweigh the benefits.

Pros & Cons

Pros

StreamField and Block Support

Offers dedicated factories for Wagtail's complex StreamField and block types like StructBlock and ListBlock, enabling easy creation of nested data structures as shown in the README's carousel example.

Factory Boy Integration

Seamlessly builds on factory_boy, allowing developers to use its declarative syntax and deep object declaration for setting nested field values, reducing test boilerplate.

Reduces Test Boilerplate

Eliminates manual setup of Wagtail models in tests, making code cleaner and more maintainable through reusable factory classes, as demonstrated in the provided usage snippets.

Flexible Data Generation

Supports customizable field values via keyword arguments, giving precise control over test data, such as overriding defaults in nested blocks like in the body__0__carousel example.

Cons

Incomplete Documentation

The README explicitly states that documentation is 'still in progress', forcing users to rely on test examples, which can slow onboarding and increase debugging time.

Breaking Syntax Changes

Version 3.0 introduced mandatory updates, such as requiring SubFactory wrappers for block factories in the alternative StreamFieldFactory syntax, potentially breaking existing test code.

Dependency on External Library

Tightly coupled to factory_boy, so teams not already using it must adopt an additional dependency, adding complexity to the toolchain and learning curve.

Frequently Asked Questions

What is Wagtail Factories?

Target Audience

Wagtail developers and Django developers who need to write tests for Wagtail-based applications and want a structured way to generate test fixtures.

Value Proposition

Use Cases

Best For

Generating test data for Wagtail Page models
Creating complex StreamField fixtures with nested blocks
Writing unit tests for Wagtail block components
Setting up test databases with realistic Wagtail content
Automating test data creation for Wagtail-based applications
Testing Wagtail's ListBlock and StructBlock implementations

Not Ideal For

Projects not built on Wagtail CMS, as the library is tightly coupled to Wagtail's data models and block system.
Teams that prefer static fixture files (e.g., JSON or YAML) for test data, since it relies on programmatic factory generation.
Simple Wagtail sites with minimal custom pages or blocks, where the overhead of setting up factories may outweigh the benefits.

Pros & Cons

Pros

StreamField and Block Support

Factory Boy Integration

Seamlessly builds on factory_boy, allowing developers to use its declarative syntax and deep object declaration for setting nested field values, reducing test boilerplate.

Reduces Test Boilerplate

Eliminates manual setup of Wagtail models in tests, making code cleaner and more maintainable through reusable factory classes, as demonstrated in the provided usage snippets.

Flexible Data Generation

Supports customizable field values via keyword arguments, giving precise control over test data, such as overriding defaults in nested blocks like in the body__0__carousel example.

Cons

Incomplete Documentation

The README explicitly states that documentation is 'still in progress', forcing users to rely on test examples, which can slow onboarding and increase debugging time.

Breaking Syntax Changes

Version 3.0 introduced mandatory updates, such as requiring SubFactory wrappers for block factories in the alternative StreamFieldFactory syntax, potentially breaking existing test code.

Dependency on External Library

Tightly coupled to factory_boy, so teams not already using it must adopt an additional dependency, adding complexity to the toolchain and learning curve.

Frequently Asked Questions

Wagtail Factories

What is Wagtail Factories?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

Wagtail Factories

What is Wagtail Factories?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?