{"id":2354,"library":"wagtail-factories","title":"Wagtail Factories","description":"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.","status":"active","version":"4.4.0","language":"en","source_language":"en","source_url":"https://github.com/wagtail/wagtail-factories/","tags":["wagtail","testing","factoryboy","django","factories","test data"],"install":[{"cmd":"pip install wagtail-factories","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Core functionality is tied to Wagtail. Ensure `wagtail-factories` version matches your `wagtail` version for compatibility.","package":"wagtail","optional":false},{"reason":"The library is built on top of `factory_boy` for generating model instances.","package":"factory_boy","optional":false}],"imports":[{"symbol":"PageFactory","correct":"from wagtail_factories import PageFactory"},{"symbol":"StreamFieldFactory","correct":"from wagtail_factories import StreamFieldFactory"},{"symbol":"CharBlockFactory","correct":"from wagtail_factories.blocks import CharBlockFactory"},{"symbol":"ImageFactory","correct":"from wagtail_factories import ImageFactory"},{"symbol":"ImageBlockFactory","correct":"from wagtail_factories.blocks import ImageBlockFactory"}],"quickstart":{"code":"import factory\nfrom django.db import models\nfrom wagtail.models import Page\nfrom wagtail.fields import RichTextField, StreamField\nfrom wagtail import blocks\nfrom wagtail_factories import PageFactory, StreamFieldFactory\nfrom wagtail_factories.blocks import CharBlockFactory\n\n# Define a simple Wagtail Page model\nclass MyPage(Page):\n    body = RichTextField(blank=True)\n    content = StreamField([\n        ('heading', blocks.CharBlock(form_classname='full title')),\n        ('paragraph', blocks.RichTextBlock()),\n    ], use_json_field=True, blank=True)\n\n    content_panels = Page.content_panels # Simplified for example\n\n# Define factories for the model and its StreamField blocks\nclass HeadingBlockFactory(CharBlockFactory):\n    class Meta:\n        model = blocks.CharBlock # For CharBlockFactory itself\n\nclass MyPageFactory(PageFactory):\n    class Meta:\n        model = MyPage\n\n    title = factory.Sequence(lambda n: f'Test Page {n}')\n    body = factory.Faker('text')\n    content = StreamFieldFactory({\n        'heading': HeadingBlockFactory,\n        'paragraph': StreamFieldFactory._do_nothing, # For simple blocks or when default behavior is fine\n    })\n\n# Example usage (requires Django environment setup)\n# To run this code, you'd typically need a Django project configured with Wagtail.\n# For testing purposes, you might use Django's test client or a custom setup.\nif __name__ == '__main__':\n    print(\"This quickstart demonstrates factory definition. To create instances, run within a configured Django/Wagtail project.\")\n    print(\"Example: `page = MyPageFactory()` would create a page in your database.\")\n    # Example of creating a page (would run within a Django test or shell):\n    # from django.test import TestCase\n    # class MyTest(TestCase):\n    #    def test_page_creation(self):\n    #        page = MyPageFactory()\n    #        self.assertIsNotNone(page.pk)\n    #        print(f\"Created page: {page.title}\")\n    #        print(f\"StreamField content keys: {[b.block_type for b in page.content]}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"Wagtail 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.","severity":"breaking","affected_versions":"All versions, especially major upgrades"},{"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.","message":"The 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.","severity":"breaking","affected_versions":"<3.0.0"},{"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.","message":"In 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.","severity":"breaking","affected_versions":">=4.0.0 on Wagtail >= 2.16"},{"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.","message":"Dependency 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.","severity":"breaking","affected_versions":"<2.1.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}