1FACTORYBOY(1) Factory Boy FACTORYBOY(1)
2
6 factoryboy - Factory Boy Documentation Latest VersionSupported Python
7 versionsWheel statusLicense
8 factory_boy is a fixtures replacement based on thoughtbot’s
10 factory_bot.
11 As a fixtures replacement tool, it aims to replace static, hard to
13 maintain fixtures with easy-to-use factories for complex object.
14 Instead of building an exhaustive test setup with every possible combi‐
16 nation of corner cases, factory_boy allows you to use objects custom‐
17 ized for the current test, while only declaring the test-specific
18 fields:
19 class FooTests(unittest.TestCase):
21 def test_with_factory_boy(self):
23 # We need a 200€, paid order, shipping to australia, for a VIP customer
24 order = OrderFactory(
25 amount=200,
26 status='PAID',
27 customer__is_vip=True,
28 address__country='AU',
29 )
30 # Run the tests here
31 def test_without_factory_boy(self):
33 address = Address(
34 street="42 fubar street",
35 zipcode="42Z42",
36 city="Sydney",
37 country="AU",
38 )
39 customer = Customer(
40 first_name="John",
41 last_name="Doe",
42 phone="+1234",
43 email="john.doe@example.org",
44 active=True,
45 is_vip=True,
46 address=address,
47 )
48 # etc.
49 factory_boy is designed to work well with various ORMs (Django, Mongo,
51 SQLAlchemy), and can easily be extended for other libraries.
52 Its main features include:
54 · Straightforward declarative syntax
56 · Chaining factory calls while retaining the global context
58 · Support for multiple build strategies (saved/unsaved instances,
60 stubbed objects)
61 · Multiple factories per class support, including inheritance
63
65 · Documentation: https://factoryboy.readthedocs.io/
66 · Repository: https://github.com/FactoryBoy/factory_boy
68 · Package: https://pypi.org/project/factory_boy/
70 · Mailing-list: factoryboy@googlegroups.com |
72 https://groups.google.com/forum/#!forum/factoryboy
73 factory_boy supports Python 2.7, 3.4 to 3.7, as well as PyPy 2.7 and
75 5.8.
76
78 PyPI: https://pypi.org/project/factory_boy/
79 $ pip install factory_boy
81 Source: https://github.com/FactoryBoy/factory_boy/
83 $ git clone git://github.com/FactoryBoy/factory_boy/
85 $ python setup.py install
86
88 NOTE:
89 This section provides a quick summary of factory_boy features. A
90 more detailed listing is available in the full documentation.
91 Defining factories
93 Factories declare a set of attributes used to instantiate an object.
94 The class of the object must be defined in the model field of a class
95 Meta: attribute:
96 import factory
98 from . import models
99 class UserFactory(factory.Factory):
101 class Meta:
102 model = models.User
103 first_name = 'John'
105 last_name = 'Doe'
106 admin = False
107 # Another, different, factory for the same object
109 class AdminFactory(factory.Factory):
110 class Meta:
111 model = models.User
112 first_name = 'Admin'
114 last_name = 'User'
115 admin = True
116 Using factories
118 factory_boy supports several different build strategies: build, create,
119 and stub:
120 # Returns a User instance that's not saved
122 user = UserFactory.build()
123 # Returns a saved User instance
125 user = UserFactory.create()
126 # Returns a stub object (just a bunch of attributes)
128 obj = UserFactory.stub()
129 You can use the Factory class as a shortcut for the default build
131 strategy:
132 # Same as UserFactory.create()
134 user = UserFactory()
135 No matter which strategy is used, it’s possible to override the defined
137 attributes by passing keyword arguments:
138 # Build a User instance and override first_name
140 >>> user = UserFactory.build(first_name='Joe')
141 >>> user.first_name
142 "Joe"
143 It is also possible to create a bunch of objects in a single call:
145 >>> users = UserFactory.build_batch(10, first_name="Joe")
147 >>> len(users)
148 10
149 >>> [user.first_name for user in users]
150 ["Joe", "Joe", "Joe", "Joe", "Joe", "Joe", "Joe", "Joe", "Joe", "Joe"]
151 Realistic, random values
153 Demos look better with random yet realistic values; and those realistic
154 values can also help discover bugs. For this, factory_boy relies on
155 the excellent faker library:
156 class RandomUserFactory(factory.Factory):
158 class Meta:
159 model = models.User
160 first_name = factory.Faker('first_name')
162 last_name = factory.Faker('last_name')
163 >>> UserFactory()
165 <User: Lucy Murray>
166 Reproducible random values
168 The use of fully randomized data in tests is quickly a problem for
169 reproducing broken builds. To that purpose, factory_boy provides
170 helpers to handle the random seeds it uses, located in the factory.ran‐
171 dom module:
172 import factory.random
174 def setup_test_environment():
176 factory.random.reseed_random('my_awesome_project')
177 # Other setup here
178 Lazy Attributes
180 Most factory attributes can be added using static values that are eval‐
181 uated when the factory is defined, but some attributes (such as fields
182 whose value is computed from other elements) will need values assigned
183 each time an instance is generated.
184 These “lazy” attributes can be added as follows:
186 class UserFactory(factory.Factory):
188 class Meta:
189 model = models.User
190 first_name = 'Joe'
192 last_name = 'Blow'
193 email = factory.LazyAttribute(lambda a: '{0}.{1}@example.com'.format(a.first_name, a.last_name).lower())
194 date_joined = factory.LazyFunction(datetime.now)
195 >>> UserFactory().email
197 "joe.blow@example.com"
198 NOTE:
200 LazyAttribute calls the function with the object being constructed
201 as an argument, when LazyFunction does not send any argument.
202 Sequences
204 Unique values in a specific format (for example, e-mail addresses) can
205 be generated using sequences. Sequences are defined by using Sequence
206 or the decorator sequence:
207 class UserFactory(factory.Factory):
209 class Meta:
210 model = models.User
211 email = factory.Sequence(lambda n: 'person{0}@example.com'.format(n))
213 >>> UserFactory().email
215 'person0@example.com'
216 >>> UserFactory().email
217 'person1@example.com'
218 Associations
220 Some objects have a complex field, that should itself be defined from a
221 dedicated factories. This is handled by the SubFactory helper:
222 class PostFactory(factory.Factory):
224 class Meta:
225 model = models.Post
226 author = factory.SubFactory(UserFactory)
228 The associated object’s strategy will be used:
230 # Builds and saves a User and a Post
232 >>> post = PostFactory()
233 >>> post.id is None # Post has been 'saved'
234 False
235 >>> post.author.id is None # post.author has been saved
236 False
237 # Builds but does not save a User, and then builds but does not save a Post
239 >>> post = PostFactory.build()
240 >>> post.id is None
241 True
242 >>> post.author.id is None
243 True
244 ORM Support
246 factory_boy has specific support for a few ORMs, through specific fac‐
247 tory.Factory subclasses:
248 · Django, with factory.django.DjangoModelFactory
250 · Mogo, with factory.mogo.MogoFactory
252 · MongoEngine, with factory.mongoengine.MongoEngineFactory
254 · SQLAlchemy, with factory.alchemy.SQLAlchemyModelFactory
256 Debugging factory_boy
258 Debugging factory_boy can be rather complex due to the long chains of
259 calls. Detailed logging is available through the factory logger.
260 A helper, factory.debug(), is available to ease debugging:
262 with factory.debug():
264 obj = TestModel2Factory()
265 import logging
268 logger = logging.getLogger('factory')
269 logger.addHandler(logging.StreamHandler())
270 logger.setLevel(logging.DEBUG)
271 This will yield messages similar to those (artificial indentation):
273 BaseFactory: Preparing tests.test_using.TestModel2Factory(extra={})
275 LazyStub: Computing values for tests.test_using.TestModel2Factory(two=<OrderedDeclarationWrapper for <factory.declarations.SubFactory object at 0x1e15610>>)
276 SubFactory: Instantiating tests.test_using.TestModelFactory(__containers=(<LazyStub for tests.test_using.TestModel2Factory>,), one=4), create=True
277 BaseFactory: Preparing tests.test_using.TestModelFactory(extra={'__containers': (<LazyStub for tests.test_using.TestModel2Factory>,), 'one': 4})
278 LazyStub: Computing values for tests.test_using.TestModelFactory(one=4)
279 LazyStub: Computed values, got tests.test_using.TestModelFactory(one=4)
280 BaseFactory: Generating tests.test_using.TestModelFactory(one=4)
281 LazyStub: Computed values, got tests.test_using.TestModel2Factory(two=<tests.test_using.TestModel object at 0x1e15410>)
282 BaseFactory: Generating tests.test_using.TestModel2Factory(two=<tests.test_using.TestModel object at 0x1e15410>)
283
285 factory_boy is distributed under the MIT License.
286 Issues should be opened through GitHub Issues; whenever possible, a
288 pull request should be included. Questions and suggestions are welcome
289 on the mailing-list.
290 All pull request should pass the test suite, which can be launched sim‐
292 ply with:
293 $ make test
295 In order to test coverage, please use:
297 $ make coverage
299 To test with a specific framework version, you may use a tox target:
301 # list all tox environments
303 $ tox --listenvs
304 # run tests inside a specific environment
306 $ tox -e py36-django20-alchemy13-mongoengine017
307 Valid options are:
309 · DJANGO for Django
311 · MONGOENGINE for mongoengine
313 · ALCHEMY for SQLAlchemy
315 To avoid running mongoengine tests (e.g no mongo server installed),
317 run:
318 $ make SKIP_MONGOENGINE=1 test
320
322 Introduction
323 The purpose of factory_boy is to provide a default way of getting a new
324 instance, while still being able to override some fields on a per-call
325 basis.
326 NOTE:
328 This section will drive you through an overview of factory_boy’s
329 feature. New users are advised to spend a few minutes browsing
330 through this list of useful helpers.
331 Users looking for quick helpers may take a look at recipes, while
333 those needing detailed documentation will be interested in the ref‐
334 erence section.
335 Basic usage
337 Factories declare a set of attributes used to instantiate an object,
338 whose class is defined in the class Meta’s model attribute:
339 · Subclass factory.Factory (or a more suitable subclass)
341 · Add a class Meta: block
343 · Set its model attribute to the target class
345 · Add defaults for keyword args to pass to the associated class’
347 __init__ method
348 import factory
350 from . import base
351 class UserFactory(factory.Factory):
353 class Meta:
354 model = base.User
355 firstname = "John"
357 lastname = "Doe"
358 You may now get base.User instances trivially:
360 >>> john = UserFactory()
362 <User: John Doe>
363 It is also possible to override the defined attributes by passing key‐
365 word arguments to the factory:
366 >>> jack = UserFactory(firstname="Jack")
368 <User: Jack Doe>
369 A given class may be associated to many Factory subclasses:
371 class EnglishUserFactory(factory.Factory):
373 class Meta:
374 model = base.User
375 firstname = "John"
377 lastname = "Doe"
378 lang = 'en'
379 class FrenchUserFactory(factory.Factory):
382 class Meta:
383 model = base.User
384 firstname = "Jean"
386 lastname = "Dupont"
387 lang = 'fr'
388 >>> EnglishUserFactory()
390 <User: John Doe (en)>
391 >>> FrenchUserFactory()
392 <User: Jean Dupont (fr)>
393 Sequences
395 When a field has a unique key, each object generated by the factory
396 should have a different value for that field. This is achieved with
397 the Sequence declaration:
398 class UserFactory(factory.Factory):
400 class Meta:
401 model = models.User
402 username = factory.Sequence(lambda n: 'user%d' % n)
404 >>> UserFactory()
406 <User: user0>
407 >>> UserFactory()
408 <User: user1>
409 NOTE:
411 For more complex situations, you may also use the @sequence() deco‐
412 rator (note that self is not added as first parameter):
413 class UserFactory(factory.Factory):
415 class Meta:
416 model = models.User
417 @factory.sequence
419 def username(n):
420 return 'user%d' % n
421 LazyFunction
423 In simple cases, calling a function is enough to compute the value. If
424 that function doesn’t depend on the object being built, use LazyFunc‐
425 tion to call that function; it should receive a function taking no
426 argument and returning the value for the field:
427 class LogFactory(factory.Factory):
429 class Meta:
430 model = models.Log
431 timestamp = factory.LazyFunction(datetime.now)
433 >>> LogFactory()
435 <Log: log at 2016-02-12 17:02:34>
436 >>> # The LazyFunction can be overriden
438 >>> LogFactory(timestamp=now - timedelta(days=1))
439 <Log: log at 2016-02-11 17:02:34>
440 NOTE:
442 For complex cases when you happen to write a specific function, the
443 @lazy_attribute() decorator should be more appropriate.
444 LazyAttribute
446 Some fields may be deduced from others, for instance the email based on
447 the username. The LazyAttribute handles such cases: it should receive
448 a function taking the object being built and returning the value for
449 the field:
450 class UserFactory(factory.Factory):
452 class Meta:
453 model = models.User
454 username = factory.Sequence(lambda n: 'user%d' % n)
456 email = factory.LazyAttribute(lambda obj: '%s@example.com' % obj.username)
457 >>> UserFactory()
459 <User: user1 (user1@example.com)>
460 >>> # The LazyAttribute handles overridden fields
462 >>> UserFactory(username='john')
463 <User: john (john@example.com)>
464 >>> # They can be directly overridden as well
466 >>> UserFactory(email='doe@example.com')
467 <User: user3 (doe@example.com)>
468 NOTE:
470 As for Sequence, a @lazy_attribute() decorator is available:
471 class UserFactory(factory.Factory):
473 class Meta:
474 model = models.User
475 username = factory.Sequence(lambda n: 'user%d' % n)
477 @factory.lazy_attribute
479 def email(self):
480 return '%s@example.com' % self.username
481 Inheritance
483 Once a “base” factory has been defined for a given class, alternate
484 versions can be easily defined through subclassing.
485 The subclassed Factory will inherit all declarations from its parent,
487 and update them with its own declarations:
488 class UserFactory(factory.Factory):
490 class Meta:
491 model = base.User
492 firstname = "John"
494 lastname = "Doe"
495 group = 'users'
496 class AdminFactory(UserFactory):
498 admin = True
499 group = 'admins'
500 >>> user = UserFactory()
502 >>> user
503 <User: John Doe>
504 >>> user.group
505 'users'
506 >>> admin = AdminFactory()
508 >>> admin
509 <User: John Doe (admin)>
510 >>> admin.group # The AdminFactory field has overridden the base field
511 'admins'
512 Any argument of all factories in the chain can easily be overridden:
514 >>> super_admin = AdminFactory(group='superadmins', lastname="Lennon")
516 >>> super_admin
517 <User: John Lennon (admin)>
518 >>> super_admin.group # Overridden at call time
519 'superadmins'
520 Non-kwarg arguments
522 Some classes take a few, non-kwarg arguments first.
523 This is handled by the inline_args attribute:
525 class MyFactory(factory.Factory):
527 class Meta:
528 model = MyClass
529 inline_args = ('x', 'y')
530 x = 1
532 y = 2
533 z = 3
534 >>> MyFactory(y=4)
536 <MyClass(1, 4, z=3)>
537 Altering a factory’s behaviour: parameters and traits
539 Some classes are better described with a few, simple parameters, that
540 aren’t fields on the actual model. In that case, use a Params declara‐
541 tion:
542 class RentalFactory(factory.Factory):
544 class Meta:
545 model = Rental
546 begin = factory.fuzzy.FuzzyDate(start_date=datetime.date(2000, 1, 1))
548 end = factory.LazyAttribute(lambda o: o.begin + o.duration)
549 class Params:
551 duration = 12
552 >>> RentalFactory(duration=0)
554 <Rental: 2012-03-03 -> 2012-03-03>
555 >>> RentalFactory(duration=10)
556 <Rental: 2008-12-16 -> 2012-12-26>
557 When many fields should be updated based on a flag, use Traits instead:
559 class OrderFactory(factory.Factory):
561 status = 'pending'
562 shipped_by = None
563 shipped_on = None
564 class Meta:
566 model = Order
567 class Params:
569 shipped = factory.Trait(
570 status='shipped',
571 shipped_by=factory.SubFactory(EmployeeFactory),
572 shipped_on=factory.LazyFunction(datetime.date.today),
573 )
574 A trait is toggled by a single boolean value:
576 >>> OrderFactory()
578 <Order: pending>
579 >>> OrderFactory(shipped=True)
580 <Order: shipped by John Doe on 2016-04-02>
581 Strategies
583 All factories support two built-in strategies:
584 · build provides a local object
586 · create instantiates a local object, and saves it to the database.
588 NOTE:
590 For 1.X versions, the create will actually call Associated‐
591 Class.objects.create, as for a Django model.
592 Starting from 2.0, factory.Factory.create() simply calls Associated‐
594 Class(**kwargs). You should use DjangoModelFactory for Django mod‐
595 els.
596 When a Factory includes related fields (SubFactory, RelatedFactory),
598 the parent’s strategy will be pushed onto related factories.
599 Calling a Factory subclass will provide an object through the default
601 strategy:
602 class MyFactory(factory.Factory):
604 class Meta:
605 model = MyClass
606 >>> MyFactory.create()
608 <MyFactory: X (saved)>
609 >>> MyFactory.build()
611 <MyFactory: X (unsaved)>
612 >>> MyFactory() # equivalent to MyFactory.create()
614 <MyClass: X (saved)>
615 The default strategy can be changed by setting the class Meta strategy
617 attribute.
618 Reference
620 This section offers an in-depth description of factory_boy features.
621 For internals and customization points, please refer to the internals
623 section.
624 The Factory class
626 Meta options
627 class factory.FactoryOptions
628 New in version 2.4.0.
629 A Factory’s behaviour can be tuned through a few settings.
632 For convenience, they are declared in a single class Meta
634 attribute:
635 class MyFactory(factory.Factory):
637 class Meta:
638 model = MyObject
639 abstract = False
640 model This optional attribute describes the class of objects to
642 generate.
643 If unset, it will be inherited from parent Factory sub‐
645 classes.
646 New in version 2.4.0.
648 get_model_class()
651 Returns the actual model class (FactoryOptions.model
652 might be the path to the class; this function will always
653 return a proper class).
654 abstract
656 This attribute indicates that the Factory subclass should
657 not be used to generate objects, but instead provides
658 some extra defaults.
659 It will be automatically set to True if neither the
661 Factory subclass nor its parents define the model
662 attribute.
663 WARNING:
665 This flag is reset to False when a Factory subclasses
666 another one if a model is set.
667 New in version 2.4.0.
669 inline_args
672 Some factories require non-keyword arguments to their
673 __init__(). They should be listed, in order, in the
674 inline_args attribute:
675 class UserFactory(factory.Factory):
677 class Meta:
678 model = User
679 inline_args = ('login', 'email')
680 login = 'john'
682 email = factory.LazyAttribute(lambda o: '%s@example.com' % o.login)
683 firstname = "John"
684 >>> UserFactory()
686 <User: john>
687 >>> User('john', 'john@example.com', firstname="John") # actual call
688 New in version 2.4.0.
690 exclude
693 While writing a Factory for some object, it may be useful
694 to have general fields helping defining others, but that
695 should not be passed to the model class; for instance, a
696 field named ‘now’ that would hold a reference time used
697 by other objects.
698 Factory fields whose name are listed in exclude will be
700 removed from the set of args/kwargs passed to the under‐
701 lying class; they can be any valid factory_boy declara‐
702 tion:
703 class OrderFactory(factory.Factory):
705 class Meta:
706 model = Order
707 exclude = ('now',)
708 now = factory.LazyFunction(datetime.datetime.utcnow)
710 started_at = factory.LazyAttribute(lambda o: o.now - datetime.timedelta(hours=1))
711 paid_at = factory.LazyAttribute(lambda o: o.now - datetime.timedelta(minutes=50))
712 >>> OrderFactory() # The value of 'now' isn't passed to Order()
714 <Order: started 2013-04-01 12:00:00, paid 2013-04-01 12:10:00>
715 >>> # An alternate value may be passed for 'now'
717 >>> OrderFactory(now=datetime.datetime(2013, 4, 1, 10))
718 <Order: started 2013-04-01 09:00:00, paid 2013-04-01 09:10:00>
719 New in version 2.4.0.
721 rename Sometimes, a model expects a field with a name already
724 used by one of Factory’s methods.
725 In this case, the rename attributes allows to define
727 renaming rules: the keys of the rename dict are those
728 used in the Factory declarations, and their values the
729 new name:
730 class ImageFactory(factory.Factory):
732 # The model expects "attributes"
733 form_attributes = ['thumbnail', 'black-and-white']
734 class Meta:
736 model = Image
737 rename = {'form_attributes': 'attributes'}
738 strategy
740 Use this attribute to change the strategy used by a
741 Factory. The default is CREATE_STRATEGY.
742 Attributes and methods
744 class factory.Factory
745 Class-level attributes:
746 Meta
748 _meta New in version 2.4.0.
750 The FactoryOptions instance attached to a Factory class
753 is available as a _meta attribute.
754 Params New in version 2.7.0.
756 The extra parameters attached to a Factory are declared
759 through a Params class. See the “Parameters” section for
760 more information.
761 _options_class
763 New in version 2.4.0.
764 If a Factory subclass needs to define additional, extra
767 options, it has to provide a custom FactoryOptions sub‐
768 class.
769 A pointer to that custom class should be provided as
771 _options_class so that the Factory-building metaclass can
772 use it instead.
773 Base functions:
775 The Factory class provides a few methods for getting objects;
777 the usual way being to simply call the class:
778 >>> UserFactory() # Calls UserFactory.create()
780 >>> UserFactory(login='john') # Calls UserFactory.create(login='john')
781 Under the hood, factory_boy will define the Factory __new__()
783 method to call the default strategy of the Factory.
784 A specific strategy for getting instance can be selected by
786 calling the adequate method:
787 classmethod build(cls, **kwargs)
789 Provides a new object, using the ‘build’ strategy.
790 classmethod build_batch(cls, size, **kwargs)
792 Provides a list of size instances from the Factory,
793 through the ‘build’ strategy.
794 classmethod create(cls, **kwargs)
796 Provides a new object, using the ‘create’ strategy.
797 classmethod create_batch(cls, size, **kwargs)
799 Provides a list of size instances from the Factory,
800 through the ‘create’ strategy.
801 classmethod stub(cls, **kwargs)
803 Provides a new stub
804 classmethod stub_batch(cls, size, **kwargs)
806 Provides a list of size stubs from the Factory.
807 classmethod generate(cls, strategy, **kwargs)
809 Provide a new instance, with the provided strategy.
810 classmethod generate_batch(cls, strategy, size, **kwargs)
812 Provides a list of size instances using the specified
813 strategy.
814 classmethod simple_generate(cls, create, **kwargs)
816 Provide a new instance, either built (create=False) or
817 created (create=True).
818 classmethod simple_generate_batch(cls, create, size, **kwargs)
820 Provides a list of size instances, either built or cre‐
821 ated according to create.
822 Extension points:
824 A Factory subclass may override a couple of class methods to
826 adapt its behaviour:
827 classmethod _adjust_kwargs(cls, **kwargs)
829 The _adjust_kwargs() extension point allows for late
830 fields tuning.
831 It is called once keyword arguments have been resolved
833 and post-generation items removed, but before the
834 inline_args extraction phase.
835 class UserFactory(factory.Factory):
837 @classmethod
839 def _adjust_kwargs(cls, **kwargs):
840 # Ensure ``lastname`` is upper-case.
841 kwargs['lastname'] = kwargs['lastname'].upper()
842 return kwargs
843 classmethod _setup_next_sequence(cls)
845 This method will compute the first value to use for the
846 sequence counter of this factory.
847 It is called when the first instance of the factory (or
849 one of its subclasses) is created.
850 Subclasses may fetch the next free ID from the database,
852 for instance.
853 classmethod _build(cls, model_class, *args, **kwargs)
855 This class method is called whenever a new instance needs
856 to be built. It receives the model class (provided to
857 model), and the positional and keyword arguments to use
858 for the class once all has been computed.
859 Subclasses may override this for custom APIs.
861 classmethod _create(cls, model_class, *args, **kwargs)
863 The _create() method is called whenever an instance needs
864 to be created. It receives the same arguments as
865 _build().
866 Subclasses may override this for specific persistence
868 backends:
869 class BaseBackendFactory(factory.Factory):
871 class Meta:
872 abstract = True # Optional
873 @classmethod
875 def _create(cls, model_class, *args, **kwargs):
876 obj = model_class(*args, **kwargs)
877 obj.save()
878 return obj
879 classmethod _after_postgeneration(cls, obj, create,
881 results=None)
882 Parameters
884 · obj (object) – The object just generated
886 · create (bool) – Whether the object was ‘built’
888 or ‘created’
889 · results (dict) – Map of post-generation declara‐
891 tion name to call result
892 The _after_postgeneration() is called once post-genera‐
894 tion declarations have been handled.
895 Its arguments allow to handle specifically some post-gen‐
897 eration return values, for instance.
898 Advanced functions:
900 classmethod reset_sequence(cls, value=None, force=False)
902 Parameters
904 · value (int) – The value to reset the sequence to
906 · force (bool) – Whether to force-reset the
908 sequence
909 Allows to reset the sequence counter for a Factory. The
911 new value can be passed in as the value argument:
912 >>> SomeFactory.build().sequenced_attribute
914 0
915 >>> SomeFactory.reset_sequence(4)
916 >>> SomeFactory.build().sequenced_attribute
917 4
918 Since subclasses of a non-abstract Factory share the same
920 sequence counter, special care needs to be taken when
921 resetting the counter of such a subclass.
922 By default, reset_sequence() will raise a ValueError when
924 called on a subclassed Factory subclass. This can be
925 avoided by passing in the force=True flag:
926 >>> InheritedFactory.reset_sequence()
928 Traceback (most recent call last):
929 File "factory_boy/tests/test_base.py", line 179, in test_reset_sequence_subclass_parent
930 SubTestObjectFactory.reset_sequence()
931 File "factory_boy/factory/base.py", line 250, in reset_sequence
932 "Cannot reset the sequence of a factory subclass. "
933 ValueError: Cannot reset the sequence of a factory subclass. Please call reset_sequence() on the root factory, or call reset_sequence(forward=True).
934 >>> InheritedFactory.reset_sequence(force=True)
936 >>>
937 This is equivalent to calling reset_sequence() on the
939 base factory in the chain.
940 Parameters
942 New in version 2.7.0.
943 Some models have many fields that can be summarized by a few parame‐
946 ters; for instance, a train with many cars — each complete with serial
947 number, manufacturer, …; or an order that can be pend‐
948 ing/shipped/received, with a few fields to describe each step.
949 When building instances of such models, a couple of parameters can be
951 enough to determine all other fields; this is handled by the Params
952 section of a Factory declaration.
953 Simple parameters
955 Some factories only need little data:
956 class ConferenceFactory(factory.Factory):
958 class Meta:
959 model = Conference
960 class Params:
962 duration = 'short' # Or 'long'
963 start_date = factory.fuzzy.FuzzyDate()
965 end_date = factory.LazyAttribute(
966 lambda o: o.start_date + datetime.timedelta(days=2 if o.duration == 'short' else 7)
967 )
968 sprints_start = factory.LazyAttribute(
969 lambda o: o.end_date - datetime.timedelta(days=0 if o.duration == 'short' else 1)
970 )
971 >>> ConferenceFactory(duration='short')
973 <Conference: DUTH 2015 (2015-11-05 - 2015-11-08, sprints 2015-11-08)>
974 >>> ConferenceFactory(duration='long')
975 <Conference: DjangoConEU 2016 (2016-03-30 - 2016-04-03, sprints 2016-04-02)>
976 Any simple parameter provided to the Factory.Params section is avail‐
978 able to the whole factory, but not passed to the final class (similar
979 to the exclude behavior).
980 Traits
982 class factory.Trait(**kwargs)
983 New in version 2.7.0.
984 A trait’s parameters are the fields it should alter when
987 enabled.
988 For more complex situations, it is helpful to override a few fields at
990 once:
991 class OrderFactory(factory.Factory):
993 class Meta:
994 model = Order
995 state = 'pending'
997 shipped_on = None
998 shipped_by = None
999 class Params:
1001 shipped = factory.Trait(
1002 state='shipped',
1003 shipped_on=datetime.date.today(),
1004 shipped_by=factory.SubFactory(EmployeeFactory),
1005 )
1006 Such a Trait is activated or disabled by a single boolean field:
1008 >>> OrderFactory()
1010 <Order: pending>
1011 Order(state='pending')
1012 >>> OrderFactory(shipped=True)
1013 <Order: shipped by John Doe on 2016-04-02>
1014 A Trait can be enabled/disabled by a Factory subclass:
1016 class ShippedOrderFactory(OrderFactory):
1018 shipped = True
1019 Values set in a Trait can be overridden by call-time values:
1021 >>> OrderFactory(shipped=True, shipped_on=last_year)
1023 <Order: shipped by John Doe on 2015-04-20>
1024 Traits can be chained:
1026 class OrderFactory(factory.Factory):
1028 class Meta:
1029 model = Order
1030 # Can be pending/shipping/received
1032 state = 'pending'
1033 shipped_on = None
1034 shipped_by = None
1035 received_on = None
1036 received_by = None
1037 class Params:
1039 shipped = factory.Trait(
1040 state='shipped',
1041 shipped_on=datetime.date.today,
1042 shipped_by=factory.SubFactory(EmployeeFactory),
1043 )
1044 received = factory.Trait(
1045 shipped=True,
1046 state='received',
1047 shipped_on=datetime.date.today - datetime.timedelta(days=4),
1048 received_on=datetime.date.today,
1049 received_by=factory.SubFactory(CustomerFactory),
1050 )
1051 >>> OrderFactory(received=True)
1053 <Order: shipped by John Doe on 2016-03-20, received by Joan Smith on 2016-04-02>
1054 A Trait might be overridden in Factory subclasses:
1056 class LocalOrderFactory(OrderFactory):
1058 class Params:
1060 received = factory.Trait(
1061 shipped=True,
1062 state='received',
1063 shipped_on=datetime.date.today - datetime.timedelta(days=1),
1064 received_on=datetime.date.today,
1065 received_by=factory.SubFactory(CustomerFactory),
1066 )
1067 >>> LocalOrderFactory(received=True)
1069 <Order: shipped by John Doe on 2016-04-01, received by Joan Smith on 2016-04-02>
1070 NOTE:
1072 When overriding a Trait, the whole declaration MUST be replaced.
1073 Strategies
1075 factory_boy supports two main strategies for generating instances, plus
1076 stubs.
1077 factory.BUILD_STRATEGY
1079 The ‘build’ strategy is used when an instance should be created,
1080 but not persisted to any datastore.
1081 It is usually a simple call to the __init__() method of the
1083 model class.
1084 factory.CREATE_STRATEGY
1086 The ‘create’ strategy builds and saves an instance into its
1087 appropriate datastore.
1088 This is the default strategy of factory_boy; it would typically
1090 instantiate an object, then save it:
1091 >>> obj = self._associated_class(*args, **kwargs)
1093 >>> obj.save()
1094 >>> return obj
1095 WARNING:
1097 For backward compatibility reasons, the default behaviour of
1098 factory_boy is to call MyClass.objects.create(*args,
1099 **kwargs) when using the create strategy.
1100 That policy will be used if the associated class has an
1102 objects attribute and the _create() classmethod of the
1103 Factory wasn’t overridden.
1104 factory.use_strategy(strategy)
1106 Decorator
1107 Change the default strategy of the decorated Factory to the cho‐
1109 sen strategy:
1110 @use_strategy(factory.BUILD_STRATEGY)
1112 class UserBuildingFactory(UserFactory):
1113 pass
1114 factory.STUB_STRATEGY
1116 The ‘stub’ strategy is an exception in the factory_boy world: it
1117 doesn’t return an instance of the model class, and actually
1118 doesn’t require one to be present.
1119 Instead, it returns an instance of StubObject whose attributes
1121 have been set according to the declarations.
1122 class factory.StubObject(object)
1124 A plain, stupid object. No method, no helpers, simply a bunch of
1125 attributes.
1126 It is typically instantiated, then has its attributes set:
1128 >>> obj = StubObject()
1130 >>> obj.x = 1
1131 >>> obj.y = 2
1132 class factory.StubFactory(Factory)
1134 An abstract Factory, with a default strategy set to
1135 STUB_STRATEGY.
1136 factory.debug(logger='factory', stream=None)
1138 Parameters
1140 · logger (str) – The name of the logger to enable debug
1142 for
1143 · stream (file) – The stream to send debug output to,
1145 defaults to sys.stderr
1146 Context manager to help debugging factory_boy behavior. It will
1148 temporarily put the target logger (e.g 'factory') in debug mode,
1149 sending all output to :obj`~sys.stderr`; upon leaving the con‐
1150 text, the logging levels are reset.
1151 A typical use case is to understand what happens during a single
1153 factory call:
1154 with factory.debug():
1156 obj = TestModel2Factory()
1157 This will yield messages similar to those (artificial indenta‐
1159 tion):
1160 BaseFactory: Preparing tests.test_using.TestModel2Factory(extra={})
1162 LazyStub: Computing values for tests.test_using.TestModel2Factory(two=<OrderedDeclarationWrapper for <factory.declarations.SubFactory object at 0x1e15610>>)
1163 SubFactory: Instantiating tests.test_using.TestModelFactory(__containers=(<LazyStub for tests.test_using.TestModel2Factory>,), one=4), create=True
1164 BaseFactory: Preparing tests.test_using.TestModelFactory(extra={'__containers': (<LazyStub for tests.test_using.TestModel2Factory>,), 'one': 4})
1165 LazyStub: Computing values for tests.test_using.TestModelFactory(one=4)
1166 LazyStub: Computed values, got tests.test_using.TestModelFactory(one=4)
1167 BaseFactory: Generating tests.test_using.TestModelFactory(one=4)
1168 LazyStub: Computed values, got tests.test_using.TestModel2Factory(two=<tests.test_using.TestModel object at 0x1e15410>)
1169 BaseFactory: Generating tests.test_using.TestModel2Factory(two=<tests.test_using.TestModel object at 0x1e15410>)
1170 Declarations
1172 Faker
1173 class factory.Faker(provider, locale=None, **kwargs)
1174 In order to easily define realistic-looking factories, use the
1175 Faker attribute declaration.
1176 This is a wrapper around faker; its argument is the name of a
1178 faker provider:
1179 class UserFactory(factory.Factory):
1181 class Meta:
1182 model = User
1183 name = factory.Faker('name')
1185 >>> user = UserFactory()
1187 >>> user.name
1188 'Lucy Cechtelar'
1189 locale If a custom locale is required for one specific field,
1191 use the locale parameter:
1192 class UserFactory(factory.Factory):
1194 class Meta:
1195 model = User
1196 name = factory.Faker('name', locale='fr_FR')
1198 >>> user = UserFactory()
1200 >>> user.name
1201 'Jean Valjean'
1202 classmethod override_default_locale(cls, locale)
1204 If the locale needs to be overridden for a whole test,
1205 use override_default_locale():
1206 >>> with factory.Faker.override_default_locale('de_DE'):
1208 ... UserFactory()
1209 <User: Johannes Brahms>
1210 classmethod add_provider(cls, locale=None)
1212 Some projects may need to fake fields beyond those pro‐
1213 vided by faker; in such cases, use
1214 factory.Faker.add_provider() to declare additional
1215 providers for those fields:
1216 factory.Faker.add_provider(SmileyProvider)
1218 class FaceFactory(factory.Factory):
1220 class Meta:
1221 model = Face
1222 smiley = factory.Faker('smiley')
1224 LazyFunction
1226 class factory.LazyFunction(method_to_call)
1227 The LazyFunction is the simplest case where the value of an attribute
1229 does not depend on the object being built.
1230 It takes as argument a method to call (function, lambda…); that method
1232 should not take any argument, though keyword arguments are safe but
1233 unused, and return a value.
1234 class LogFactory(factory.Factory):
1236 class Meta:
1237 model = models.Log
1238 timestamp = factory.LazyFunction(datetime.now)
1240 >>> LogFactory()
1242 <Log: log at 2016-02-12 17:02:34>
1243 >>> # The LazyFunction can be overriden
1245 >>> LogFactory(timestamp=now - timedelta(days=1))
1246 <Log: log at 2016-02-11 17:02:34>
1247 LazyFunction is also useful for assigning copies of mutable objects
1249 (like lists) to an object’s property. Example:
1250 DEFAULT_TEAM = ['Player1', 'Player2']
1252 class TeamFactory(factory.Factory):
1254 class Meta:
1255 model = models.Team
1256 teammates = factory.LazyFunction(lambda: list(DEFAULT_TEAM))
1258 Decorator
1260 The class LazyFunction does not provide a decorator.
1261 For complex cases, use LazyAttribute.lazy_attribute() directly.
1263 LazyAttribute
1265 class factory.LazyAttribute(method_to_call)
1266 The LazyAttribute is a simple yet extremely powerful building brick for
1268 extending a Factory.
1269 It takes as argument a method to call (usually a lambda); that method
1271 should accept the object being built as sole argument, and return a
1272 value.
1273 class UserFactory(factory.Factory):
1275 class Meta:
1276 model = User
1277 username = 'john'
1279 email = factory.LazyAttribute(lambda o: '%s@example.com' % o.username)
1280 >>> u = UserFactory()
1282 >>> u.email
1283 'john@example.com'
1284 >>> u = UserFactory(username='leo')
1286 >>> u.email
1287 'leo@example.com'
1288 The object passed to LazyAttribute is not an instance of the target
1290 class, but instead a Resolver: a temporary container that computes the
1291 value of all declared fields.
1292 Decorator
1294 factory.lazy_attribute()
1295 If a simple lambda isn’t enough, you may use the lazy_attribute() deco‐
1297 rator instead.
1298 This decorates an instance method that should take a single argument,
1300 self; the name of the method will be used as the name of the attribute
1301 to fill with the return value of the method:
1302 class UserFactory(factory.Factory)
1304 class Meta:
1305 model = User
1306 name = u"Jean"
1308 @factory.lazy_attribute
1310 def email(self):
1311 # Convert to plain ascii text
1312 clean_name = (unicodedata.normalize('NFKD', self.name)
1313 .encode('ascii', 'ignore')
1314 .decode('utf8'))
1315 return u'%s@example.com' % clean_name
1316 >>> joel = UserFactory(name=u"Joël")
1318 >>> joel.email
1319 u'joel@example.com'
1320 Sequence
1322 class factory.Sequence(lambda)
1323 If a field should be unique, and thus different for all built
1325 instances, use a Sequence.
1326 This declaration takes a single argument, a function accepting a single
1328 parameter - the current sequence counter - and returning the related
1329 value.
1330 class UserFactory(factory.Factory)
1332 class Meta:
1333 model = User
1334 phone = factory.Sequence(lambda n: '123-555-%04d' % n)
1336 >>> UserFactory().phone
1338 '123-555-0001'
1339 >>> UserFactory().phone
1340 '123-555-0002'
1341 Decorator
1343 factory.sequence()
1344 As with lazy_attribute(), a decorator is available for complex situa‐
1346 tions.
1347 sequence() decorates an instance method, whose self method will actu‐
1349 ally be the sequence counter - this might be confusing:
1350 class UserFactory(factory.Factory)
1352 class Meta:
1353 model = User
1354 @factory.sequence
1356 def phone(n):
1357 a = n // 10000
1358 b = n % 10000
1359 return '%03d-555-%04d' % (a, b)
1360 >>> UserFactory().phone
1362 '000-555-9999'
1363 >>> UserFactory().phone
1364 '001-555-0000'
1365 Sharing
1367 The sequence counter is shared across all Sequence attributes of the
1368 Factory:
1369 class UserFactory(factory.Factory):
1371 class Meta:
1372 model = User
1373 phone = factory.Sequence(lambda n: '%04d' % n)
1375 office = factory.Sequence(lambda n: 'A23-B%03d' % n)
1376 >>> u = UserFactory()
1378 >>> u.phone, u.office
1379 '0041', 'A23-B041'
1380 >>> u2 = UserFactory()
1381 >>> u2.phone, u2.office
1382 '0042', 'A23-B042'
1383 Inheritance
1385 When a Factory inherits from another Factory and the model of the sub‐
1386 class inherits from the model of the parent, the sequence counter is
1387 shared across the Factory classes:
1388 class UserFactory(factory.Factory):
1390 class Meta:
1391 model = User
1392 phone = factory.Sequence(lambda n: '123-555-%04d' % n)
1394 class EmployeeFactory(UserFactory):
1397 office_phone = factory.Sequence(lambda n: '%04d' % n)
1398 >>> u = UserFactory()
1400 >>> u.phone
1401 '123-555-0001'
1402 >>> e = EmployeeFactory()
1404 >>> e.phone, e.office_phone
1405 '123-555-0002', '0002'
1406 >>> u2 = UserFactory()
1408 >>> u2.phone
1409 '123-555-0003'
1410 Forcing a sequence counter
1412 If a specific value of the sequence counter is required for one
1413 instance, the __sequence keyword argument should be passed to the fac‐
1414 tory method.
1415 This will force the sequence counter during the call, without altering
1417 the class-level value.
1418 class UserFactory(factory.Factory):
1420 class Meta:
1421 model = User
1422 uid = factory.Sequence(int)
1424 >>> UserFactory()
1426 <User: 0>
1427 >>> UserFactory()
1428 <User: 1>
1429 >>> UserFactory(__sequence=42)
1430 <User: 42>
1431 WARNING:
1433 The impact of setting __sequence=n on a _batch call is undefined.
1434 Each generated instance may share a same counter, or use incremental
1435 values starting from the forced value.
1436 LazyAttributeSequence
1438 class factory.LazyAttributeSequence(method_to_call)
1439 The LazyAttributeSequence declaration merges features of Sequence and
1441 LazyAttribute.
1442 It takes a single argument, a function whose two parameters are, in
1444 order:
1445 · The object being built
1447 · The sequence counter
1449 class UserFactory(factory.Factory):
1451 class Meta:
1452 model = User
1453 login = 'john'
1455 email = factory.LazyAttributeSequence(lambda o, n: '%s@s%d.example.com' % (o.login, n))
1456 >>> UserFactory().email
1458 'john@s1.example.com'
1459 >>> UserFactory(login='jack').email
1460 'jack@s2.example.com'
1461 Decorator
1463 factory.lazy_attribute_sequence(method_to_call)
1464 As for lazy_attribute() and sequence(), the lazy_attribute_sequence()
1466 handles more complex cases:
1467 class UserFactory(factory.Factory):
1469 class Meta:
1470 model = User
1471 login = 'john'
1473 @lazy_attribute_sequence
1475 def email(self, n):
1476 bucket = n % 10
1477 return '%s@s%d.example.com' % (self.login, bucket)
1478 SubFactory
1480 class factory.SubFactory(factory, **kwargs)
1481 This attribute declaration calls another Factory subclass, selecting
1483 the same build strategy and collecting extra kwargs in the process.
1484 The SubFactory attribute should be called with:
1486 · A Factory subclass as first argument, or the fully qualified import
1488 path to that Factory (see Circular imports)
1489 · An optional set of keyword arguments that should be passed when call‐
1491 ing that factory
1492 NOTE:
1494 When passing an actual Factory for the factory argument, make sure
1495 to pass the class and not instance (i.e no () after the class):
1496 class FooFactory(factory.Factory):
1498 class Meta:
1499 model = Foo
1500 bar = factory.SubFactory(BarFactory) # Not BarFactory()
1502 Definition
1504 # A standard factory
1505 class UserFactory(factory.Factory):
1506 class Meta:
1507 model = User
1508 # Various fields
1510 first_name = 'John'
1511 last_name = factory.Sequence(lambda n: 'D%se' % ('o' * n)) # De, Doe, Dooe, Doooe, ...
1512 email = factory.LazyAttribute(lambda o: '%s.%s@example.org' % (o.first_name.lower(), o.last_name.lower()))
1513 # A factory for an object with a 'User' field
1515 class CompanyFactory(factory.Factory):
1516 class Meta:
1517 model = Company
1518 name = factory.Sequence(lambda n: 'FactoryBoyz' + 'z' * n)
1520 # Let's use our UserFactory to create that user, and override its first name.
1522 owner = factory.SubFactory(UserFactory, first_name='Jack')
1523 Calling
1525 The wrapping factory will call of the inner factory:
1526 >>> c = CompanyFactory()
1528 >>> c
1529 <Company: FactoryBoyz>
1530 # Notice that the first_name was overridden
1532 >>> c.owner
1533 <User: Jack De>
1534 >>> c.owner.email
1535 jack.de@example.org
1536 Fields of the SubFactory may be overridden from the external factory:
1538 >>> c = CompanyFactory(owner__first_name='Henry')
1540 >>> c.owner
1541 <User: Henry Doe>
1542 # Notice that the updated first_name was propagated to the email LazyAttribute.
1544 >>> c.owner.email
1545 henry.doe@example.org
1546 # It is also possible to override other fields of the SubFactory
1548 >>> c = CompanyFactory(owner__last_name='Jones')
1549 >>> c.owner
1550 <User: Henry Jones>
1551 >>> c.owner.email
1552 henry.jones@example.org
1553 Strategies
1555 The strategy chosen for the external factory will be propagated to all
1556 subfactories:
1557 >>> c = CompanyFactory()
1559 >>> c.pk # Saved to the database
1560 3
1561 >>> c.owner.pk # Saved to the database
1562 8
1563 >>> c = CompanyFactory.build()
1565 >>> c.pk # Not saved
1566 None
1567 >>> c.owner.pk # Not saved either
1568 None
1569 Circular imports
1571 Some factories may rely on each other in a circular manner. This issue
1572 can be handled by passing the absolute import path to the target
1573 Factory to the SubFactory.
1574 New in version 1.3.0.
1576 class UserFactory(factory.Factory):
1579 class Meta:
1580 model = User
1581 username = 'john'
1583 main_group = factory.SubFactory('users.factories.GroupFactory')
1584 class GroupFactory(factory.Factory):
1586 class Meta:
1587 model = Group
1588 name = "MyGroup"
1590 owner = factory.SubFactory(UserFactory)
1591 Obviously, such circular relationships require careful handling of
1593 loops:
1594 >>> owner = UserFactory(main_group=None)
1596 >>> UserFactory(main_group__owner=owner)
1597 <john (group: MyGroup)>
1598 SelfAttribute
1600 class factory.SelfAttribute(dotted_path_to_attribute)
1601 Some fields should reference another field of the object being con‐
1603 structed, or an attribute thereof.
1604 This is performed by the SelfAttribute declaration. That declaration
1606 takes a single argument, a dot-delimited path to the attribute to
1607 fetch:
1608 class UserFactory(factory.Factory):
1610 class Meta:
1611 model = User
1612 birthdate = factory.Sequence(lambda n: datetime.date(2000, 1, 1) + datetime.timedelta(days=n))
1614 birthmonth = factory.SelfAttribute('birthdate.month')
1615 >>> u = UserFactory()
1617 >>> u.birthdate
1618 date(2000, 3, 15)
1619 >>> u.birthmonth
1620 3
1621 Parents
1623 When used in conjunction with SubFactory, the SelfAttribute gains an
1624 “upward” semantic through the double-dot notation, as used in Python
1625 imports.
1626 factory.SelfAttribute('..country.language') means “Select the language
1628 of the country of the Factory calling me”.
1629 class UserFactory(factory.Factory):
1631 class Meta:
1632 model = User
1633 language = 'en'
1635 class CompanyFactory(factory.Factory):
1638 class Meta:
1639 model = Company
1640 country = factory.SubFactory(CountryFactory)
1642 owner = factory.SubFactory(UserFactory, language=factory.SelfAttribute('..country.language'))
1643 >>> company = CompanyFactory()
1645 >>> company.country.language
1646 'fr'
1647 >>> company.owner.language
1648 'fr'
1649 Obviously, this “follow parents” ability also handles overriding some
1651 attributes on call:
1652 >>> company = CompanyFactory(country=china)
1654 >>> company.owner.language
1655 'cn'
1656 This feature is also available to LazyAttribute and
1658 LazyAttributeSequence, through the factory_parent attribute of the
1659 passed-in object:
1660 class CompanyFactory(factory.Factory):
1662 class Meta:
1663 model = Company
1664 country = factory.SubFactory(CountryFactory)
1665 owner = factory.SubFactory(UserFactory,
1666 language=factory.LazyAttribute(lambda user: user.factory_parent.country.language),
1667 )
1668 Iterator
1670 class factory.Iterator(iterable, cycle=True, getter=None)
1671 The Iterator declaration takes successive values from the given
1672 iterable. When it is exhausted, it starts again from zero
1673 (unless cycle=False).
1674 cycle The cycle argument is only useful for advanced cases,
1676 where the provided iterable has no end (as wishing to
1677 cycle it means storing values in memory…).
1678 New in version 1.3.0: The cycle argument is available as
1680 of v1.3.0; previous versions had a behaviour equivalent
1681 to cycle=False.
1682 getter A custom function called on each value returned by the
1685 iterable. See the Getter section for details.
1686 New in version 1.3.0.
1688 reset()
1691 Reset the internal iterator used by the attribute, so
1692 that the next value will be the first value generated by
1693 the iterator.
1694 May be called several times.
1696 Each call to the factory will receive the next value from the iterable:
1698 class UserFactory(factory.Factory)
1700 lang = factory.Iterator(['en', 'fr', 'es', 'it', 'de'])
1701 >>> UserFactory().lang
1703 'en'
1704 >>> UserFactory().lang
1705 'fr'
1706 When a value is passed in for the argument, the iterator will not be
1708 advanced:
1709 >>> UserFactory().lang
1711 'en'
1712 >>> UserFactory(lang='cn').lang
1713 'cn'
1714 >>> UserFactory().lang
1715 'fr'
1716 Getter
1718 Some situations may reuse an existing iterable, using only some compo‐
1719 nent. This is handled by the getter attribute: this is a function that
1720 accepts as sole parameter a value from the iterable, and returns an
1721 adequate value.
1722 class UserFactory(factory.Factory):
1724 class Meta:
1725 model = User
1726 # CATEGORY_CHOICES is a list of (key, title) tuples
1728 category = factory.Iterator(User.CATEGORY_CHOICES, getter=lambda c: c[0])
1729 Decorator
1731 factory.iterator(func)
1732 When generating items of the iterator gets too complex for a simple
1734 list comprehension, use the iterator() decorator:
1735 WARNING:
1737 The decorated function takes no argument, notably no self parameter.
1738 class UserFactory(factory.Factory):
1740 class Meta:
1741 model = User
1742 @factory.iterator
1744 def name():
1745 with open('test/data/names.dat', 'r') as f:
1746 for line in f:
1747 yield line
1748 WARNING:
1750 Values from the underlying iterator are kept in memory; once the
1751 initial iterator has been emptied, saved values are used instead of
1752 executing the function instead.
1753 Use factory.Iterator(my_func, cycle=False) to disable value recy‐
1755 cling.
1756 Resetting
1758 In order to start back at the first value in an Iterator, simply call
1759 the reset() method of that attribute (accessing it from the bare
1760 Factory subclass):
1761 >>> UserFactory().lang
1763 'en'
1764 >>> UserFactory().lang
1765 'fr'
1766 >>> UserFactory.lang.reset()
1767 >>> UserFactory().lang
1768 'en'
1769 Dict and List
1771 When a factory expects lists or dicts as arguments, such values can be
1772 generated through the whole range of factory_boy declarations, with the
1773 Dict and List attributes:
1774 class factory.Dict(params[, dict_factory=factory.DictFactory])
1776 The Dict class is used for dict-like attributes. It receives as
1777 non-keyword argument a dictionary of fields to define, whose
1778 value may be any factory-enabled declarations:
1779 class UserFactory(factory.Factory):
1781 class Meta:
1782 model = User
1783 is_superuser = False
1785 roles = factory.Dict({
1786 'role1': True,
1787 'role2': False,
1788 'role3': factory.Iterator([True, False]),
1789 'admin': factory.SelfAttribute('..is_superuser'),
1790 })
1791 NOTE:
1793 Declarations used as a Dict values are evaluated within that
1794 Dict’s context; this means that you must use the ..foo syntax
1795 to access fields defined at the factory level.
1796 On the other hand, the Sequence counter is aligned on the
1798 containing factory’s one.
1799 The Dict behaviour can be tuned through the following parame‐
1801 ters:
1802 dict_factory
1804 The actual factory to use for generating the dict can be
1805 set as a keyword argument, if an exotic dictionary-like
1806 object (SortedDict, …) is required.
1807 class factory.List(items[, list_factory=factory.ListFactory])
1809 The List can be used for list-like attributes.
1810 Internally, the fields are converted into a index=value dict,
1812 which makes it possible to override some values at use time:
1813 class UserFactory(factory.Factory):
1815 class Meta:
1816 model = User
1817 flags = factory.List([
1819 'user',
1820 'active',
1821 'admin',
1822 ])
1823 >>> u = UserFactory(flags__2='superadmin')
1825 >>> u.flags
1826 ['user', 'active', 'superadmin']
1827 The List behaviour can be tuned through the following parame‐
1829 ters:
1830 list_factory
1832 The actual factory to use for generating the list can be
1833 set as a keyword argument, if another type (tuple, set,
1834 …) is required.
1835 Maybe
1837 class factory.Maybe(decider, yes_declaration, no_declaration)
1838 Sometimes, the way to build a given field depends on the value of
1840 another, for instance of a parameter.
1841 In those cases, use the Maybe declaration: it takes the name of a
1843 “decider” boolean field, and two declarations; depending on the value
1844 of the field whose name is held in the ‘decider’ parameter, it will
1845 apply the effects of one or the other declaration:
1846 class UserFactory(factory.Factory):
1848 class Meta:
1849 model = User
1850 is_active = True
1852 deactivation_date = factory.Maybe(
1853 'is_active',
1854 yes_declaration=None,
1855 no_declaration=factory.fuzzy.FuzzyDateTime(timezone.now() - datetime.timedelta(days=10)),
1856 )
1857 >>> u = UserFactory(is_active=True)
1859 >>> u.deactivation_date
1860 None
1861 >>> u = UserFactory(is_active=False)
1862 >>> u.deactivation_date
1863 datetime.datetime(2017, 4, 1, 23, 21, 23, tzinfo=UTC)
1864 NOTE:
1866 If the condition for the decider is complex, use a LazyAttribute
1867 defined in the Params section of your factory to handle the computa‐
1868 tion.
1869 Post-generation hooks
1871 Some objects expect additional method calls or complex processing for
1872 proper definition. For instance, a User may need to have a related
1873 Profile, where the Profile is built from the User object.
1874 To support this pattern, factory_boy provides the following tools:
1876 · PostGenerationMethodCall: allows you to hook a particular
1878 attribute to a function call
1879 · PostGeneration: this class allows calling a given function
1881 with the generated object as argument
1882 · post_generation(): decorator performing the same functions as
1884 PostGeneration
1885 · RelatedFactory: this builds or creates a given factory after
1887 building/creating the first Factory.
1888 · RelatedFactoryList: this builds or creates a list of the given
1890 factory after building/creating the first Factory.
1891 Post-generation hooks are called in the same order they are declared in
1893 the factory class, so that functions can rely on the side effects
1894 applied by the previous post-generation hook.
1895 Extracting parameters
1897 All post-building hooks share a common base for picking parameters from
1898 the set of attributes passed to the Factory.
1899 For instance, a PostGeneration hook is declared as post:
1901 class SomeFactory(factory.Factory):
1903 class Meta:
1904 model = SomeObject
1905 @post_generation
1907 def post(obj, create, extracted, **kwargs):
1908 obj.set_origin(create)
1909 When calling the factory, some arguments will be extracted for this
1911 method:
1912 · If a post argument is passed, it will be passed as the extracted
1914 field
1915 · Any argument starting with post__XYZ will be extracted, its post__
1917 prefix removed, and added to the kwargs passed to the post-generation
1918 hook.
1919 Extracted arguments won’t be passed to the model class.
1921 Thus, in the following call:
1923 >>> SomeFactory(
1925 post=1,
1926 post_x=2,
1927 post__y=3,
1928 post__z__t=42,
1929 )
1930 The post hook will receive 1 as extracted and {'y': 3, 'z__t': 42} as
1932 keyword arguments; {'post_x': 2} will be passed to SomeFac‐
1933 tory._meta.model.
1934 RelatedFactory
1936 class factory.RelatedFactory(factory, factory_related_name='',
1937 **kwargs)
1938 A RelatedFactory behaves mostly like a SubFactory, with the main
1939 difference that the related Factory will be generated after the
1940 base Factory.
1941 factory
1943 As for SubFactory, the factory argument can be:
1944 · A Factory subclass
1946 · Or the fully qualified path to a Factory subclass (see
1948 Circular imports for details)
1949 name The generated object (where the RelatedFactory attribute
1951 will set) may be passed to the related factory if the
1952 factory_related_name parameter is set.
1953 It will be passed as a keyword argument, using the name
1955 value as keyword:
1956 NOTE:
1958 When passing an actual Factory for the factory argument, make sure
1959 to pass the class and not instance (i.e no () after the class):
1960 class FooFactory(factory.Factory):
1962 class Meta:
1963 model = Foo
1964 bar = factory.RelatedFactory(BarFactory) # Not BarFactory()
1966 class CityFactory(factory.Factory):
1968 class Meta:
1969 model = City
1970 capital_of = None
1972 name = "Toronto"
1973 class CountryFactory(factory.Factory):
1975 class Meta:
1976 model = Country
1977 lang = 'fr'
1979 capital_city = factory.RelatedFactory(CityFactory, 'capital_of', name="Paris")
1980 >>> france = CountryFactory()
1982 >>> City.objects.get(capital_of=france)
1983 <City: Paris>
1984 Extra kwargs may be passed to the related factory, through the usual
1986 ATTR__SUBATTR syntax:
1987 >>> england = CountryFactory(lang='en', capital_city__name="London")
1989 >>> City.objects.get(capital_of=england)
1990 <City: London>
1991 If a value is passed for the RelatedFactory attribute, this disables
1993 RelatedFactory generation:
1994 >>> france = CountryFactory()
1996 >>> paris = City.objects.get()
1997 >>> paris
1998 <City: Paris>
1999 >>> reunion = CountryFactory(capital_city=paris)
2000 >>> City.objects.count() # No new capital_city generated
2001 1
2002 >>> guyane = CountryFactory(capital_city=paris, capital_city__name='Kourou')
2003 >>> City.objects.count() # No new capital_city generated, ``name`` ignored.
2004 1
2005 NOTE:
2007 The target of the RelatedFactory is evaluated after the initial fac‐
2008 tory has been instantiated. However, the build context is passed
2009 down to that factory; this means that calls to factory.SelfAttribute
2010 can go back to the calling factorry’s context:
2011 class CountryFactory(factory.Factory):
2013 class Meta:
2014 model = Country
2015 lang = 'fr'
2017 capital_city = factory.RelatedFactory(CityFactory, 'capital_of',
2018 # Would also work with SelfAttribute('capital_of.lang')
2019 main_lang=factory.SelfAttribute('..lang'),
2020 )
2021 RelatedFactoryList
2023 class factory.RelatedFactoryList(factory, factory_related_name='',
2024 size=2, **kwargs)
2025 A RelatedFactoryList behaves like a RelatedFactory, only it
2026 returns a list of factories. This is useful for simulating
2027 one-to-many relations, rather than the one-to-one relation
2028 generated by RelatedFactory.
2029 factory
2031 As for SubFactory, the factory argument can be:
2032 · A Factory subclass
2034 · Or the fully qualified path to a Factory subclass
2036 (see Circular imports for details)
2037 name The generated object (where the RelatedFactory
2039 attribute will set) may be passed to the related fac‐
2040 tories if the factory_related_name parameter is set.
2041 It will be passed as a keyword argument, using the
2043 name value as keyword:
2044 size Either an int, or a lambda that returns an int, which
2046 will define the number of related Factories to be gen‐
2047 erated for each parent object.
2048 New in version 2.12: Note that the API for RelatedFactoryList is
2050 considered experimental, and might change in a future version
2051 for increased consistency with other declarations.
2052 NOTE:
2055 Note that using a lambda for size allows the number of related
2056 objects per parents object to vary. This is useful for testing, when
2057 you likely don’t want your mock data to have parent objects with the
2058 exact same, static number of related objects.
2059 LIST_SIZES = [1, 2, 3, 4, 5]
2061 class FooFactory(factory.Factory):
2063 class Meta:
2064 model = Foo
2065 # Generate a list of `factory` objects of random size, ranging from 1 -> 5
2066 bar = factory.RelatedFactoryList(BarFactory,
2067 size=lambda: LIST_SIZES[random.randint(0,5)])
2068 # Each Foo object will have exactly 3 Bar objects generated for its foobar attribute.
2069 foobar = factory.RelatedFactoryList(BarFactory, size=3])
2070 PostGeneration
2072 class factory.PostGeneration(callable)
2073 The PostGeneration declaration performs actions once the model object
2075 has been generated.
2076 Its sole argument is a callable, that will be called once the base
2078 object has been generated.
2079 Once the base object has been generated, the provided callable will be
2081 called as callable(obj, create, extracted, **kwargs), where:
2082 · obj is the base object previously generated
2084 · create is a boolean indicating which strategy was used
2086 · extracted is None unless a value was passed in for the PostGeneration
2088 declaration at Factory declaration time
2089 · kwargs are any extra parameters passed as attr__key=value when call‐
2091 ing the Factory:
2092 class UserFactory(factory.Factory):
2094 class Meta:
2095 model = User
2096 login = 'john'
2098 make_mbox = factory.PostGeneration(
2099 lambda obj, create, extracted, **kwargs: os.makedirs(obj.login))
2100 Decorator
2102 factory.post_generation()
2103 A decorator is also provided, decorating a single method accepting the
2105 same obj, create, extracted and keyword arguments as PostGeneration.
2106 class UserFactory(factory.Factory):
2108 class Meta:
2109 model = User
2110 login = 'john'
2112 @factory.post_generation
2114 def mbox(obj, create, extracted, **kwargs):
2115 if not create:
2116 return
2117 path = extracted or os.path.join('/tmp/mbox/', self.login)
2118 os.path.makedirs(path)
2119 return path
2120 >>> UserFactory.build() # Nothing was created
2122 >>> UserFactory.create() # Creates dir /tmp/mbox/john
2123 >>> UserFactory.create(login='jack') # Creates dir /tmp/mbox/jack
2124 >>> UserFactory.create(mbox='/tmp/alt') # Creates dir /tmp/alt
2125 PostGenerationMethodCall
2127 class factory.PostGenerationMethodCall(method_name, *arg, **kwargs)
2128 The PostGenerationMethodCall declaration will call a method on
2129 the generated object just after instantiation. This declaration
2130 class provides a friendly means of generating attributes of a
2131 factory instance during initialization. The declaration is cre‐
2132 ated using the following arguments:
2133 method_name
2135 The name of the method to call on the model object
2136 arg The default, optional, positional argument to pass to the
2138 method given in method_name
2139 kwargs The default set of keyword arguments to pass to the
2141 method given in method_name
2142 Once the factory instance has been generated, the method specified in
2144 method_name will be called on the generated object with any arguments
2145 specified in the PostGenerationMethodCall declaration, by default.
2146 For example, to set a default password on a generated User instance
2148 during instantiation, we could make a declaration for a password
2149 attribute like below:
2150 class UserFactory(factory.Factory):
2152 class Meta:
2153 model = User
2154 username = 'user'
2156 password = factory.PostGenerationMethodCall('set_password',
2157 'defaultpassword')
2158 When we instantiate a user from the UserFactory, the factory will cre‐
2160 ate a password attribute by calling User.set_password('defaultpass‐
2161 word'). Thus, by default, our users will have a password set to
2162 'defaultpassword'.
2163 >>> u = UserFactory() # Calls user.set_password('defaultpassword')
2165 >>> u.check_password('defaultpassword')
2166 True
2167 If the PostGenerationMethodCall declaration contained no arguments or
2169 one argument, an overriding value can be passed directly to the method
2170 through a keyword argument matching the attribute name. For example we
2171 can override the default password specified in the declaration above by
2172 simply passing in the desired password as a keyword argument to the
2173 factory during instantiation.
2174 >>> other_u = UserFactory(password='different') # Calls user.set_password('different')
2176 >>> other_u.check_password('defaultpassword')
2177 False
2178 >>> other_u.check_password('different')
2179 True
2180 NOTE:
2182 For Django models, unless the object method called by
2183 PostGenerationMethodCall saves the object back to the database, we
2184 will have to explicitly remember to save the object back if we per‐
2185 formed a create().
2186 >>> u = UserFactory.create() # u.password has not been saved back to the database
2188 >>> u.save() # we must remember to do it ourselves
2189 We can avoid this by subclassing from DjangoModelFactory, instead,
2191 e.g.,
2192 class UserFactory(factory.django.DjangoModelFactory):
2194 class Meta:
2195 model = User
2196 username = 'user'
2198 password = factory.PostGenerationMethodCall('set_password',
2199 'defaultpassword')
2200 WARNING:
2202 In order to keep a consistent and simple API, a
2203 PostGenerationMethodCall allows at most one positional argument; all
2204 other parameters should be passed as keyword arguments.
2205 Keywords extracted from the factory arguments are merged into the
2207 defaults present in the PostGenerationMethodCall declaration.
2208 >>> UserFactory(password__disabled=True) # Calls user.set_password('', 'sha1', disabled=True)
2210 Module-level functions
2212 Beyond the Factory class and the various Declarations classes and meth‐
2213 ods, factory_boy exposes a few module-level functions, mostly useful
2214 for lightweight factory generation.
2215 Lightweight factory declaration
2217 factory.make_factory(klass, **kwargs)
2218 The make_factory() function takes a class, declarations as key‐
2219 word arguments, and generates a new Factory for that class
2220 accordingly:
2221 UserFactory = make_factory(User,
2223 login='john',
2224 email=factory.LazyAttribute(lambda u: '%s@example.com' % u.login),
2225 )
2226 # This is equivalent to:
2228 class UserFactory(factory.Factory):
2230 class Meta:
2231 model = User
2232 login = 'john'
2234 email = factory.LazyAttribute(lambda u: '%s@example.com' % u.login)
2235 An alternate base class to Factory can be specified in the FAC‐
2237 TORY_CLASS argument:
2238 UserFactory = make_factory(models.User,
2240 login='john',
2241 email=factory.LazyAttribute(lambda u: '%s@example.com' % u.login),
2242 FACTORY_CLASS=factory.django.DjangoModelFactory,
2243 )
2244 # This is equivalent to:
2246 class UserFactory(factory.django.DjangoModelFactory):
2248 class Meta:
2249 model = models.User
2250 login = 'john'
2252 email = factory.LazyAttribute(lambda u: '%s@example.com' % u.login)
2253 New in version 2.0.0: The FACTORY_CLASS kwarg was added in
2255 2.0.0.
2256 Instance building
2259 The factory module provides a bunch of shortcuts for creating a factory
2260 and extracting instances from them:
2261 factory.build(klass, FACTORY_CLASS=None, **kwargs)
2263 factory.build_batch(klass, size, FACTORY_CLASS=None, **kwargs)
2265 Create a factory for klass using declarations passed in kwargs;
2266 return an instance built from that factory, or a list of size
2267 instances (for build_batch()).
2268 Parameters
2270 · klass (class) – Class of the instance to build
2272 · size (int) – Number of instances to build
2274 · kwargs – Declarations to use for the generated factory
2276 · FACTORY_CLASS – Alternate base class (instead of
2278 Factory)
2279 factory.create(klass, FACTORY_CLASS=None, **kwargs)
2281 factory.create_batch(klass, size, FACTORY_CLASS=None, **kwargs)
2283 Create a factory for klass using declarations passed in kwargs;
2284 return an instance created from that factory, or a list of size
2285 instances (for create_batch()).
2286 Parameters
2288 · klass (class) – Class of the instance to create
2290 · size (int) – Number of instances to create
2292 · kwargs – Declarations to use for the generated factory
2294 · FACTORY_CLASS – Alternate base class (instead of
2296 Factory)
2297 factory.stub(klass, FACTORY_CLASS=None, **kwargs)
2299 factory.stub_batch(klass, size, FACTORY_CLASS=None, **kwargs)
2301 Create a factory for klass using declarations passed in kwargs;
2302 return an instance stubbed from that factory, or a list of size
2303 instances (for stub_batch()).
2304 Parameters
2306 · klass (class) – Class of the instance to stub
2308 · size (int) – Number of instances to stub
2310 · kwargs – Declarations to use for the generated factory
2312 · FACTORY_CLASS – Alternate base class (instead of
2314 Factory)
2315 factory.generate(klass, strategy, FACTORY_CLASS=None, **kwargs)
2317 factory.generate_batch(klass, strategy, size, FACTORY_CLASS=None,
2319 **kwargs)
2320 Create a factory for klass using declarations passed in kwargs;
2321 return an instance generated from that factory with the strategy
2322 strategy, or a list of size instances (for generate_batch()).
2323 Parameters
2325 · klass (class) – Class of the instance to generate
2327 · strategy (str) – The strategy to use
2329 · size (int) – Number of instances to generate
2331 · kwargs – Declarations to use for the generated factory
2333 · FACTORY_CLASS – Alternate base class (instead of
2335 Factory)
2336 factory.simple_generate(klass, create, FACTORY_CLASS=None, **kwargs)
2338 factory.simple_generate_batch(klass, create, size, FACTORY_CLASS=None,
2340 **kwargs)
2341 Create a factory for klass using declarations passed in kwargs;
2342 return an instance generated from that factory according to the
2343 create flag, or a list of size instances (for
2344 simple_generate_batch()).
2345 Parameters
2347 · klass (class) – Class of the instance to generate
2349 · create (bool) – Whether to build (False) or create
2351 (True) instances
2352 · size (int) – Number of instances to generate
2354 · kwargs – Declarations to use for the generated factory
2356 · FACTORY_CLASS – Alternate base class (instead of
2358 Factory)
2359 Randomness management
2361 Using random in factories allows to “fuzz” a program efficiently. How‐
2362 ever, it’s sometimes required to reproduce a failing test.
2363 factory.fuzzy and factory.Faker share a dedicated instance of ran‐
2365 dom.Random, which can be managed through the factory.random module:
2366 factory.random.get_random_state()
2368 Call get_random_state() to retrieve the random generator’s cur‐
2369 rent state. The returned object is implementation-specific.
2370 factory.random.set_random_state(state)
2372 Use set_random_state() to set a custom state into the random
2373 generator (fetched from get_random_state() in a previous run,
2374 for instance)
2375 factory.random.reseed_random(seed)
2377 The reseed_random() function allows to load a chosen seed into
2378 the random generator. That seed can be anything accepted by
2379 random.seed().
2380 See recipe-random-management for help in using those methods in a test
2382 setup.
2383 Using factory_boy with ORMs
2385 factory_boy provides custom Factory subclasses for various ORMs, adding
2386 dedicated features.
2387 Django
2389 The first versions of factory_boy were designed specifically for
2390 Django, but the library has now evolved to be framework-independent.
2391 Most features should thus feel quite familiar to Django users.
2393 The DjangoModelFactory subclass
2395 All factories for a Django Model should use the DjangoModelFactory base
2396 class.
2397 class factory.django.DjangoModelFactory(factory.Factory)
2399 Dedicated class for Django Model factories.
2400 This class provides the following features:
2402 · The model attribute also supports the 'app.Model' syntax
2404 · create() uses Model.objects.create()
2406 · When using RelatedFactory or PostGeneration attributes, the
2408 base object will be saved once all post-generation hooks have
2409 run.
2410 NOTE:
2412 With Django versions 1.8.0 to 1.8.3, it was no longer possible to
2413 call .build() on a factory if this factory used a SubFactory point‐
2414 ing to another model: Django refused to set a ForeignKey to an
2415 unsaved Model instance.
2416 See https://code.djangoproject.com/ticket/10811 and
2418 https://code.djangoproject.com/ticket/25160 for details.
2419 class factory.django.DjangoOptions(factory.base.FactoryOptions)
2421 The class Meta on a DjangoModelFactory supports extra parame‐
2422 ters:
2423 database
2425 New in version 2.5.0.
2426 All queries to the related model will be routed to the
2429 given database. It defaults to 'default'.
2430 django_get_or_create
2432 New in version 2.4.0.
2433 Fields whose name are passed in this list will be used to
2436 perform a Model.objects.get_or_create() instead of the
2437 usual Model.objects.create():
2438 class UserFactory(factory.django.DjangoModelFactory):
2440 class Meta:
2441 model = 'myapp.User' # Equivalent to ``model = myapp.models.User``
2442 django_get_or_create = ('username',)
2443 username = 'john'
2445 >>> User.objects.all()
2447 []
2448 >>> UserFactory() # Creates a new user
2449 <User: john>
2450 >>> User.objects.all()
2451 [<User: john>]
2452 >>> UserFactory() # Fetches the existing user
2454 <User: john>
2455 >>> User.objects.all() # No new user!
2456 [<User: john>]
2457 >>> UserFactory(username='jack') # Creates another user
2459 <User: jack>
2460 >>> User.objects.all()
2461 [<User: john>, <User: jack>]
2462 Extra fields
2464 class factory.django.FileField
2465 Custom declarations for django.db.models.FileField
2466 __init__(self, from_path='', from_file='', from_func='',
2468 data=b'', filename='example.dat')
2469 Parameters
2471 · from_path (str) – Use data from the file located
2473 at from_path, and keep its filename
2474 · from_file (file) – Use the contents of the pro‐
2476 vided file object; use its filename if avail‐
2477 able, unless filename is also provided.
2478 · from_func (func) – Use function that returns a
2480 file object
2481 · data (bytes) – Use the provided bytes as file
2483 contents
2484 · filename (str) – The filename for the FileField
2486 NOTE:
2488 If the value None was passed for the FileField field, this will dis‐
2489 able field generation:
2490 class MyFactory(factory.django.DjangoModelFactory):
2492 class Meta:
2493 model = models.MyModel
2494 the_file = factory.django.FileField(filename='the_file.dat')
2496 >>> MyFactory(the_file__data=b'uhuh').the_file.read()
2498 b'uhuh'
2499 >>> MyFactory(the_file=None).the_file
2500 None
2501 class factory.django.ImageField
2503 Custom declarations for django.db.models.ImageField
2504 __init__(self, from_path='', from_file='', from_func='', file‐
2506 name='example.jpg', width=100, height=100, color='green', for‐
2507 mat='JPEG')
2508 Parameters
2510 · from_path (str) – Use data from the file located
2512 at from_path, and keep its filename
2513 · from_file (file) – Use the contents of the pro‐
2515 vided file object; use its filename if available
2516 · from_func (func) – Use function that returns a
2518 file object
2519 · filename (str) – The filename for the ImageField
2521 · width (int) – The width of the generated image
2523 (default: 100)
2524 · height (int) – The height of the generated image
2526 (default: 100)
2527 · color (str) – The color of the generated image
2529 (default: 'green')
2530 · format (str) – The image format (as supported by
2532 PIL) (default: 'JPEG')
2533 NOTE:
2535 If the value None was passed for the FileField field, this will dis‐
2536 able field generation:
2537 NOTE:
2539 Just as Django’s django.db.models.ImageField requires the Python
2540 Imaging Library, this ImageField requires it too.
2541 class MyFactory(factory.django.DjangoModelFactory):
2543 class Meta:
2544 model = models.MyModel
2545 the_image = factory.django.ImageField(color='blue')
2547 >>> MyFactory(the_image__width=42).the_image.width
2549 42
2550 >>> MyFactory(the_image=None).the_image
2551 None
2552 Disabling signals
2554 Signals are often used to plug some custom code into external compo‐
2555 nents code; for instance to create Profile objects on-the-fly when a
2556 new User object is saved.
2557 This may interfere with finely tuned factories, which would create both
2559 using RelatedFactory.
2560 To work around this problem, use the mute_signals() decorator/context
2562 manager:
2563 factory.django.mute_signals(signal1, ...)
2565 Disable the list of selected signals when calling the factory,
2566 and reactivate them upon leaving.
2567 # foo/factories.py
2569 import factory
2571 from . import models
2573 from . import signals
2574 @factory.django.mute_signals(signals.pre_save, signals.post_save)
2576 class FooFactory(factory.django.DjangoModelFactory):
2577 class Meta:
2578 model = models.Foo
2579 # ...
2581 def make_chain():
2583 with factory.django.mute_signals(signals.pre_save, signals.post_save):
2584 # pre_save/post_save won't be called here.
2585 return SomeFactory(), SomeOtherFactory()
2586 Mogo
2588 factory_boy supports Mogo-style models, through the MogoFactory class.
2589 Mogo is a wrapper around the pymongo library for MongoDB.
2591 class factory.mogo.MogoFactory(factory.Factory)
2593 Dedicated class for Mogo models.
2594 This class provides the following features:
2596 · build() calls a model’s new() method
2598 · create() builds an instance through new() then saves it.
2600 MongoEngine
2602 factory_boy supports MongoEngine-style models, through the
2603 MongoEngineFactory class.
2604 mongoengine is a wrapper around the pymongo library for MongoDB.
2606 class factory.mongoengine.MongoEngineFactory(factory.Factory)
2608 Dedicated class for MongoEngine models.
2609 This class provides the following features:
2611 · build() calls a model’s __init__ method
2613 · create() builds an instance through __init__ then saves it.
2615 NOTE:
2617 If the associated class <factory.FactoryOptions.model is a
2618 mongoengine.EmbeddedDocument, the create() function won’t
2619 “save” it, since this wouldn’t make sense.
2620 This feature makes it possible to use SubFactory to create
2622 embedded document.
2623 A minimalist example:
2625 import mongoengine
2627 class Address(mongoengine.EmbeddedDocument):
2629 street = mongoengine.StringField()
2630 class Person(mongoengine.Document):
2632 name = mongoengine.StringField()
2633 address = mongoengine.EmbeddedDocumentField(Address)
2634 import factory
2636 class AddressFactory(factory.mongoengine.MongoEngineFactory):
2638 class Meta:
2639 model = Address
2640 street = factory.Sequence(lambda n: 'street%d' % n)
2642 class PersonFactory(factory.mongoengine.MongoEngineFactory):
2644 class Meta:
2645 model = Person
2646 name = factory.Sequence(lambda n: 'name%d' % n)
2648 address = factory.SubFactory(AddressFactory)
2649 SQLAlchemy
2651 Factory_boy also supports SQLAlchemy models through the
2652 SQLAlchemyModelFactory class.
2653 To work, this class needs an SQLAlchemy session object affected to the
2655 Meta.sqlalchemy_session attribute.
2656 class factory.alchemy.SQLAlchemyModelFactory(factory.Factory)
2658 Dedicated class for SQLAlchemy models.
2659 This class provides the following features:
2661 · create() uses sqlalchemy.orm.session.Session.add()
2663 class factory.alchemy.SQLAlchemyOptions(factory.base.FactoryOptions)
2665 In addition to the usual parameters available in class Meta, a
2666 SQLAlchemyModelFactory also supports the following settings:
2667 sqlalchemy_session
2669 SQLAlchemy session to use to communicate with the data‐
2670 base when creating an object through this
2671 SQLAlchemyModelFactory.
2672 sqlalchemy_session_persistence
2674 Control the action taken by sqlalchemy session at the end
2675 of a create call.
2676 Valid values are:
2678 · None: do nothing
2680 · 'flush': perform a session flush()
2682 · 'commit': perform a session commit()
2684 The default value is None.
2686 If force_flush is set to True, it overrides this option.
2688 force_flush
2690 Force a session flush() at the end of _create().
2691 NOTE:
2693 This option is deprecated. Use sqlalchemy_session_per‐
2694 sistence instead.
2695 A (very) simple example:
2697 from sqlalchemy import Column, Integer, Unicode, create_engine
2699 from sqlalchemy.ext.declarative import declarative_base
2700 from sqlalchemy.orm import scoped_session, sessionmaker
2701 engine = create_engine('sqlite://')
2703 session = scoped_session(sessionmaker(bind=engine))
2704 Base = declarative_base()
2705 class User(Base):
2708 """ A SQLAlchemy simple model class who represents a user """
2709 __tablename__ = 'UserTable'
2710 id = Column(Integer(), primary_key=True)
2712 name = Column(Unicode(20))
2713 Base.metadata.create_all(engine)
2715 import factory
2717 class UserFactory(factory.alchemy.SQLAlchemyModelFactory):
2719 class Meta:
2720 model = User
2721 sqlalchemy_session = session # the SQLAlchemy session object
2722 id = factory.Sequence(lambda n: n)
2724 name = factory.Sequence(lambda n: u'User %d' % n)
2725 >>> session.query(User).all()
2727 []
2728 >>> UserFactory()
2729 <User: User 1>
2730 >>> session.query(User).all()
2731 [<User: User 1>]
2732 Managing sessions
2734 Since SQLAlchemy is a general purpose library, there is no “global”
2735 session management system.
2736 The most common pattern when working with unit tests and factory_boy is
2738 to use SQLAlchemy’s sqlalchemy.orm.scoping.scoped_session:
2739 · The test runner configures some project-wide scoped_session
2741 · Each SQLAlchemyModelFactory subclass uses this scoped_session as its
2743 sqlalchemy_session
2744 · The tearDown() method of tests calls Session.remove to reset the ses‐
2746 sion.
2747 NOTE:
2749 See the excellent SQLAlchemy guide on scoped_session for details of
2750 scoped_session’s usage.
2751 The basic idea is that declarative parts of the code (including fac‐
2753 tories) need a simple way to access the “current session”, but that
2754 session will only be created and configured at a later point.
2755 The scoped_session handles this, by virtue of only creating the ses‐
2757 sion when a query is sent to the database.
2758 Here is an example layout:
2760 · A global (test-only?) file holds the scoped_session:
2762 # myprojet/test/common.py
2764 from sqlalchemy import orm
2766 Session = orm.scoped_session(orm.sessionmaker())
2767 · All factory access it:
2769 # myproject/factories.py
2771 import factory
2773 from . import models
2775 from .test import common
2776 class UserFactory(factory.alchemy.SQLAlchemyModelFactory):
2778 class Meta:
2779 model = models.User
2780 # Use the not-so-global scoped_session
2782 # Warning: DO NOT USE common.Session()!
2783 sqlalchemy_session = common.Session
2784 name = factory.Sequence(lambda n: "User %d" % n)
2786 · The test runner configures the scoped_session when it starts:
2788 # myproject/test/runtests.py
2790 import sqlalchemy
2792 from . import common
2794 def runtests():
2796 engine = sqlalchemy.create_engine('sqlite://')
2797 # It's a scoped_session, and now is the time to configure it.
2799 common.Session.configure(bind=engine)
2800 run_the_tests
2802 · test cases use this scoped_session, and clear it after each test (for
2804 isolation):
2805 # myproject/test/test_stuff.py
2807 import unittest
2809 from . import common
2811 class MyTest(unittest.TestCase):
2813 def setUp(self):
2815 # Prepare a new, clean session
2816 self.session = common.Session()
2817 def test_something(self):
2819 u = factories.UserFactory()
2820 self.assertEqual([u], self.session.query(User).all())
2821 def tearDown(self):
2823 # Rollback the session => no changes to the database
2824 self.session.rollback()
2825 # Remove it, so that the next test gets a new Session()
2826 common.Session.remove()
2827 Common recipes
2829 NOTE:
2830 Most recipes below take on Django model examples, but can also be
2831 used on their own.
2832 Dependent objects (ForeignKey)
2834 When one attribute is actually a complex field (e.g a ForeignKey to
2835 another Model), use the SubFactory declaration:
2836 # models.py
2838 class User(models.Model):
2839 first_name = models.CharField()
2840 group = models.ForeignKey(Group)
2841 # factories.py
2844 import factory
2845 from . import models
2846 class UserFactory(factory.django.DjangoModelFactory):
2848 class Meta:
2849 model = models.User
2850 first_name = factory.Sequence(lambda n: "Agent %03d" % n)
2852 group = factory.SubFactory(GroupFactory)
2853 Choosing from a populated table
2855 If the target of the ForeignKey should be chosen from a pre-populated
2856 table (e.g django.contrib.contenttypes.models.ContentType), simply use
2857 a factory.Iterator on the chosen queryset:
2858 import factory, factory.django
2860 from . import models
2861 class UserFactory(factory.django.DjangoModelFactory):
2863 class Meta:
2864 model = models.User
2865 language = factory.Iterator(models.Language.objects.all())
2867 Here, models.Language.objects.all() won’t be evaluated until the first
2869 call to UserFactory; thus avoiding DB queries at import time.
2870 Reverse dependencies (reverse ForeignKey)
2872 When a related object should be created upon object creation (e.g a
2873 reverse ForeignKey from another Model), use a RelatedFactory declara‐
2874 tion:
2875 # models.py
2877 class User(models.Model):
2878 pass
2879 class UserLog(models.Model):
2881 user = models.ForeignKey(User)
2882 action = models.CharField()
2883 # factories.py
2886 class UserFactory(factory.django.DjangoModelFactory):
2887 class Meta:
2888 model = models.User
2889 log = factory.RelatedFactory(UserLogFactory, 'user', action=models.UserLog.ACTION_CREATE)
2891 When a UserFactory is instantiated, factory_boy will call UserLogFac‐
2893 tory(user=that_user, action=...) just before returning the created
2894 User.
2895 Example: Django’s Profile
2897 Django (<1.5) provided a mechanism to attach a Profile to a User
2898 instance, using a OneToOneField from the Profile to the User.
2899 A typical way to create those profiles was to hook a post-save signal
2901 to the User model.
2902 Prior to version 2.9, the solution to this was to override the _gener‐
2904 ate() method on the factory.
2905 Since version 2.9, the mute_signals() decorator should be used:
2907 @factory.django.mute_signals(post_save)
2909 class ProfileFactory(factory.django.DjangoModelFactory):
2910 class Meta:
2911 model = my_models.Profile
2912 title = 'Dr'
2914 # We pass in profile=None to prevent UserFactory from creating another profile
2915 # (this disables the RelatedFactory)
2916 user = factory.SubFactory('app.factories.UserFactory', profile=None)
2917 @factory.django.mute_signals(post_save)
2919 class UserFactory(factory.django.DjangoModelFactory):
2920 class Meta:
2921 model = auth_models.User
2922 username = factory.Sequence(lambda n: "user_%d" % n)
2924 # We pass in 'user' to link the generated Profile to our just-generated User
2926 # This will call ProfileFactory(user=our_new_user), thus skipping the SubFactory.
2927 profile = factory.RelatedFactory(ProfileFactory, 'user')
2928 >>> u = UserFactory(profile__title=u"Lord")
2930 >>> u.get_profile().title
2931 u"Lord"
2932 Such behaviour can be extended to other situations where a signal
2934 interferes with factory_boy related factories.
2935 Any factories that call these classes with SubFactory will also need to
2937 be decorated in the same manner.
2938 NOTE:
2940 When any RelatedFactory or post_generation attribute is defined on
2941 the DjangoModelFactory subclass, a second save() is performed after
2942 the call to _create().
2943 Code working with signals should thus use the mute_signals() decora‐
2945 tor
2946 Simple Many-to-many relationship
2948 Building the adequate link between two models depends heavily on the
2949 use case; factory_boy doesn’t provide a “all in one tools” as for Sub‐
2950 Factory or RelatedFactory, users will have to craft their own depending
2951 on the model.
2952 The base building block for this feature is the post_generation hook:
2954 # models.py
2956 class Group(models.Model):
2957 name = models.CharField()
2958 class User(models.Model):
2960 name = models.CharField()
2961 groups = models.ManyToManyField(Group)
2962 # factories.py
2965 class GroupFactory(factory.django.DjangoModelFactory):
2966 class Meta:
2967 model = models.Group
2968 name = factory.Sequence(lambda n: "Group #%s" % n)
2970 class UserFactory(factory.django.DjangoModelFactory):
2972 class Meta:
2973 model = models.User
2974 name = "John Doe"
2976 @factory.post_generation
2978 def groups(self, create, extracted, **kwargs):
2979 if not create:
2980 # Simple build, do nothing.
2981 return
2982 if extracted:
2984 # A list of groups were passed in, use them
2985 for group in extracted:
2986 self.groups.add(group)
2987 When calling UserFactory() or UserFactory.build(), no group binding
2989 will be created.
2990 But when UserFactory.create(groups=(group1, group2, group3)) is called,
2992 the groups declaration will add passed in groups to the set of groups
2993 for the user.
2994 Many-to-many relation with a ‘through’
2996 If only one link is required, this can be simply performed with a
2997 RelatedFactory. If more links are needed, simply add more RelatedFac‐
2998 tory declarations:
2999 # models.py
3001 class User(models.Model):
3002 name = models.CharField()
3003 class Group(models.Model):
3005 name = models.CharField()
3006 members = models.ManyToManyField(User, through='GroupLevel')
3007 class GroupLevel(models.Model):
3009 user = models.ForeignKey(User)
3010 group = models.ForeignKey(Group)
3011 rank = models.IntegerField()
3012 # factories.py
3015 class UserFactory(factory.django.DjangoModelFactory):
3016 class Meta:
3017 model = models.User
3018 name = "John Doe"
3020 class GroupFactory(factory.django.DjangoModelFactory):
3022 class Meta:
3023 model = models.Group
3024 name = "Admins"
3026 class GroupLevelFactory(factory.django.DjangoModelFactory):
3028 class Meta:
3029 model = models.GroupLevel
3030 user = factory.SubFactory(UserFactory)
3032 group = factory.SubFactory(GroupFactory)
3033 rank = 1
3034 class UserWithGroupFactory(UserFactory):
3036 membership = factory.RelatedFactory(GroupLevelFactory, 'user')
3037 class UserWith2GroupsFactory(UserFactory):
3039 membership1 = factory.RelatedFactory(GroupLevelFactory, 'user', group__name='Group1')
3040 membership2 = factory.RelatedFactory(GroupLevelFactory, 'user', group__name='Group2')
3041 Whenever the UserWithGroupFactory is called, it will, as a post-genera‐
3043 tion hook, call the GroupLevelFactory, passing the generated user as a
3044 user field:
3045 1. UserWithGroupFactory() generates a User instance, obj
3047 2. It calls GroupLevelFactory(user=obj)
3049 3. It returns obj
3051 When using the UserWith2GroupsFactory, that behavior becomes:
3053 1. UserWith2GroupsFactory() generates a User instance, obj
3055 2. It calls GroupLevelFactory(user=obj, group__name='Group1')
3057 3. It calls GroupLevelFactory(user=obj, group__name='Group2')
3059 4. It returns obj
3061 Copying fields to a SubFactory
3063 When a field of a related class should match one of the container:
3064 # models.py
3066 class Country(models.Model):
3067 name = models.CharField()
3068 lang = models.CharField()
3069 class User(models.Model):
3071 name = models.CharField()
3072 lang = models.CharField()
3073 country = models.ForeignKey(Country)
3074 class Company(models.Model):
3076 name = models.CharField()
3077 owner = models.ForeignKey(User)
3078 country = models.ForeignKey(Country)
3079 Here, we want:
3081 · The User to have the lang of its country (factory.SelfAt‐
3083 tribute('country.lang'))
3084 · The Company owner to live in the country of the company (fac‐
3086 tory.SelfAttribute('..country'))
3087 # factories.py
3089 class CountryFactory(factory.django.DjangoModelFactory):
3090 class Meta:
3091 model = models.Country
3092 name = factory.Iterator(["France", "Italy", "Spain"])
3094 lang = factory.Iterator(['fr', 'it', 'es'])
3095 class UserFactory(factory.django.DjangoModelFactory):
3097 class Meta:
3098 model = models.User
3099 name = "John"
3101 lang = factory.SelfAttribute('country.lang')
3102 country = factory.SubFactory(CountryFactory)
3103 class CompanyFactory(factory.django.DjangoModelFactory):
3105 class Meta:
3106 model = models.Company
3107 name = "ACME, Inc."
3109 country = factory.SubFactory(CountryFactory)
3110 owner = factory.SubFactory(UserFactory, country=factory.SelfAttribute('..country'))
3111 If the value of a field on the child factory is indirectly derived from
3113 a field on the parent factory, you will need to use LazyAttribute and
3114 poke the “factory_parent” attribute.
3115 This time, we want the company owner to live in a country neighboring
3117 the country of the company:
3118 class CompanyFactory(factory.django.DjangoModelFactory):
3120 class Meta:
3121 model = models.Company
3122 name = "ACME, Inc."
3124 country = factory.SubFactory(CountryFactory)
3125 owner = factory.SubFactory(UserFactory,
3126 country=factory.LazyAttribute(lambda o: get_random_neighbor(o.factory_parent.country)))
3127 Custom manager methods
3129 Sometimes you need a factory to call a specific manager method other
3130 then the default Model.objects.create() method:
3131 class UserFactory(factory.django.DjangoModelFactory):
3133 class Meta:
3134 model = UserenaSignup
3135 username = "l7d8s"
3137 email = "my_name@example.com"
3138 password = "my_password"
3139 @classmethod
3141 def _create(cls, model_class, *args, **kwargs):
3142 """Override the default ``_create`` with our custom call."""
3143 manager = cls._get_manager(model_class)
3144 # The default would use ``manager.create(*args, **kwargs)``
3145 return manager.create_user(*args, **kwargs)
3146 Forcing the sequence counter
3148 A common pattern with factory_boy is to use a factory.Sequence declara‐
3149 tion to provide varying values to attributes declared as unique.
3150 However, it is sometimes useful to force a given value to the counter,
3152 for instance to ensure that tests are properly reproductible.
3153 factory_boy provides a few hooks for this:
3155 Forcing the value on a per-call basis
3157 In order to force the counter for a specific Factory instantia‐
3158 tion, just pass the value in the __sequence=42 parameter:
3159 class AccountFactory(factory.Factory):
3161 class Meta:
3162 model = Account
3163 uid = factory.Sequence(lambda n: n)
3164 name = "Test"
3165 >>> obj1 = AccountFactory(name="John Doe", __sequence=10)
3167 >>> obj1.uid # Taken from the __sequence counter
3168 10
3169 >>> obj2 = AccountFactory(name="Jane Doe")
3170 >>> obj2.uid # The base sequence counter hasn't changed
3171 1
3172 Resetting the counter globally
3174 If all calls for a factory must start from a deterministic num‐
3175 ber, use factory.Factory.reset_sequence(); this will reset the
3176 counter to its initial value (as defined by factory.Fac‐
3177 tory._setup_next_sequence()).
3178 >>> AccountFactory().uid
3180 1
3181 >>> AccountFactory().uid
3182 2
3183 >>> AccountFactory.reset_sequence()
3184 >>> AccountFactory().uid # Reset to the initial value
3185 1
3186 >>> AccountFactory().uid
3187 2
3188 It is also possible to reset the counter to a specific value:
3190 >>> AccountFactory.reset_sequence(10)
3192 >>> AccountFactory().uid
3193 10
3194 >>> AccountFactory().uid
3195 11
3196 This recipe is most useful in a TestCase’s setUp() method.
3198 Forcing the initial value for all projects
3200 The sequence counter of a Factory can also be set automatically
3201 upon the first call through the _setup_next_sequence() method;
3202 this helps when the objects’s attributes mustn’t conflict with
3203 pre-existing data.
3204 A typical example is to ensure that running a Python script
3206 twice will create non-conflicting objects, by setting up the
3207 counter to “max used value plus one”:
3208 class AccountFactory(factory.django.DjangoModelFactory):
3210 class Meta:
3211 model = models.Account
3212 @classmethod
3214 def _setup_next_sequence(cls):
3215 try:
3216 return models.Accounts.objects.latest('uid').uid + 1
3217 except models.Account.DoesNotExist:
3218 return 1
3219 >>> Account.objects.create(uid=42, name="Blah")
3221 >>> AccountFactory.create() # Sets up the account number based on the latest uid
3222 <Account uid=43, name=Test>
3223 Using reproducible randomness
3225 Although using random values is great, it can provoke test flakyness.
3226 factory_boy provides a few helpers for this.
3227 NOTE:
3229 Those methods will seed the random engine used in both factory.Faker
3230 and factory.fuzzy objects.
3231 Seeding the random engine
3233 The simplest way to manage randomness is to push a selected seed
3234 when starting tests:
3235 import factory.random
3237 # Pass in any value
3238 factory.random.reseed_random('my awesome project')
3239 Reproducing unseeded tests
3241 A project might choose not to use an explicit random seed (for
3242 better fuzzing), but still wishes to have reproducible tests.
3243 For such cases, use a combination of factory.random.get_ran‐
3245 dom_state() and factory.random.set_random_state().
3246 Since the random state structure is implementation-specific, we
3248 recommand passing it around as a base64-encoded pickle dump.
3249 class MyTestRunner:
3251 def setup_test_environment(self):
3253 state = os.environ.get('TEST_RANDOM_STATE')
3254 if state:
3255 try:
3256 decoded_state = pickle.loads(base64.b64decode(state.encode('ascii')))
3257 except ValueError:
3258 decoded_state = None
3259 if decoded_state:
3260 factory.random.set_random_state(decoded_state)
3261 else:
3262 encoded_state = base64.b64encode(pickle.dumps(factory.random.get_random_state()))
3263 print("Current random state: %s" % encoded_state.decode('ascii'))
3264 super().setup_test_environment()
3265 Converting a factory’s output to a dict
3267 In order to inject some data to, say, a REST API, it can be useful to
3268 fetch the factory’s data as a dict.
3269 Internally, a factory will:
3271 1. Merge declarations and overrides from all sources (class definition,
3273 call parameters, …)
3274 2. Resolve them into a dict
3276 3. Pass that dict as keyword arguments to the model’s build / create
3278 function
3279 In order to get a dict, we’ll just have to swap the model; the easiest
3281 way is to use factory.build():
3282 class UserFactory(factory.django.DjangoModelFactory):
3284 class Meta:
3285 model = models.User
3286 first_name = factory.Sequence(lambda n: "Agent %03d" % n)
3288 username = factory.Faker('user_name')
3289 >>> factory.build(dict, FACTORY_CLASS=UserFactory)
3291 {'first_name': "Agent 001", 'username': 'john_doe'}
3292 Fuzzying Django model field choices
3294 When defining a FuzzyChoice you can reuse the same choice list from the
3295 model field descriptor.
3296 Use the getter kwarg to select the first element from each choice
3298 tuple.
3299 class UserFactory(factory.Factory):
3301 class Meta:
3302 model = User
3303 # CATEGORY_CHOICES is a list of (key, title) tuples
3305 category = factory.fuzzy.FuzzyChoice(User.CATEGORY_CHOICES, getter=lambda c: c[0])
3306 Django models with GenericForeignKeys
3308 For model which uses GenericForeignKey
3309 from __future__ import unicode_literals
3311 from django.db import models
3313 from django.contrib.contenttypes.models import ContentType
3314 from django.contrib.contenttypes.fields import GenericForeignKey
3315 class TaggedItem(models.Model):
3318 """Example GenericForeignKey model from django docs"""
3319 tag = models.SlugField()
3320 content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE)
3321 object_id = models.PositiveIntegerField()
3322 content_object = GenericForeignKey('content_type', 'object_id')
3323 def __str__(self): # __unicode__ on Python 2
3325 return self.tag
3326 We can create factories like this:
3329 import factory
3331 from django.contrib.auth.models import User, Group
3332 from django.contrib.contenttypes.models import ContentType
3333 from .models import TaggedItem
3335 class UserFactory(factory.django.DjangoModelFactory):
3338 first_name = 'Adam'
3339 class Meta:
3341 model = User
3342 class GroupFactory(factory.django.DjangoModelFactory):
3345 name = 'group'
3346 class Meta:
3348 model = Group
3349 class TaggedItemFactory(factory.django.DjangoModelFactory):
3352 object_id = factory.SelfAttribute('content_object.id')
3353 content_type = factory.LazyAttribute(
3354 lambda o: ContentType.objects.get_for_model(o.content_object))
3355 class Meta:
3357 exclude = ['content_object']
3358 abstract = True
3359 class TaggedUserFactory(TaggedItemFactory):
3362 content_object = factory.SubFactory(UserFactory)
3363 class Meta:
3365 model = TaggedItem
3366 class TaggedGroupFactory(TaggedItemFactory):
3369 content_object = factory.SubFactory(GroupFactory)
3370 class Meta:
3372 model = TaggedItem
3373 Fuzzy attributes
3376 NOTE:
3377 Now that FactoryBoy includes the factory.Faker class, most of these
3378 built-in fuzzers are deprecated in favor of their Faker equivalents.
3379 Further discussion here:
3380 https://github.com/FactoryBoy/factory_boy/issues/271/
3381 Some tests may be interested in testing with fuzzy, random values.
3383 This is handled by the factory.fuzzy module, which provides a few ran‐
3385 dom declarations.
3386 NOTE:
3388 Use import factory.fuzzy to load this module.
3389 FuzzyAttribute
3391 class factory.fuzzy.FuzzyAttribute
3392 The FuzzyAttribute uses an arbitrary callable as fuzzer. It is
3393 expected that successive calls of that function return various
3394 values.
3395 fuzzer The callable that generates random values
3397 FuzzyText
3399 class factory.fuzzy.FuzzyText(length=12, chars=string.ascii_letters,
3400 prefix='')
3401 The FuzzyText fuzzer yields random strings beginning with the
3402 given prefix, followed by length charactes chosen from the chars
3403 character set, and ending with the given suffix.
3404 length int, the length of the random part
3406 prefix text, an optional prefix to prepend to the random part
3408 suffix text, an optional suffix to append to the random part
3410 chars
3412 char iterable, the chars to choose from; defaults to the
3414 list of ascii
3415 letters and numbers.
3416 FuzzyChoice
3418 class factory.fuzzy.FuzzyChoice(choices)
3419 The FuzzyChoice fuzzer yields random choices from the given
3420 iterable.
3421 NOTE:
3423 The passed in choices will be converted into a list upon
3424 first use, not at declaration time.
3425 This allows passing in, for instance, a Django queryset that
3427 will only hit the database during the database, not at import
3428 time.
3429 WARNING:
3431 When using Python2 and list comprehension, use private vari‐
3432 able names as in:
3433 [_x.name for _x in items]
3435 instead of:
3437 [x.name for x in items]
3439 choices
3441 The list of choices to select randomly
3442 FuzzyInteger
3444 class factory.fuzzy.FuzzyInteger(low[, high[, step]])
3445 The FuzzyInteger fuzzer generates random integers within a given
3446 inclusive range.
3447 The low bound may be omitted, in which case it defaults to 0:
3449 >>> fi = FuzzyInteger(0, 42)
3451 >>> fi.low, fi.high
3452 0, 42
3453 >>> fi = FuzzyInteger(42)
3455 >>> fi.low, fi.high
3456 0, 42
3457 low int, the inclusive lower bound of generated integers
3459 high int, the inclusive higher bound of generated integers
3461 step int, the step between values in the range; for instance,
3463 a FuzzyInteger(0, 42, step=3) might only yield values
3464 from [0, 3, 6, 9, 12, 15, 18, 21, 24, 27, 30, 33, 36, 39,
3465 42].
3466 FuzzyDecimal
3468 class factory.fuzzy.FuzzyDecimal(low[, high[, precision=2]])
3469 The FuzzyDecimal fuzzer generates random decimals within a given
3470 inclusive range.
3471 The low bound may be omitted, in which case it defaults to 0:
3473 >>> FuzzyDecimal(0.5, 42.7)
3475 >>> fi.low, fi.high
3476 0.5, 42.7
3477 >>> fi = FuzzyDecimal(42.7)
3479 >>> fi.low, fi.high
3480 0.0, 42.7
3481 >>> fi = FuzzyDecimal(0.5, 42.7, 3)
3483 >>> fi.low, fi.high, fi.precision
3484 0.5, 42.7, 3
3485 low decimal, the inclusive lower bound of generated decimals
3487 high decimal, the inclusive higher bound of generated decimals
3489 precision
3491 int, the number of digits to generate after the dot. The default
3493 is 2 digits.
3494 FuzzyFloat
3496 class factory.fuzzy.FuzzyFloat(low[, high])
3497 The FuzzyFloat fuzzer provides random float objects within a
3498 given inclusive range.
3499 >>> FuzzyFloat(0.5, 42.7)
3501 >>> fi.low, fi.high
3502 0.5, 42.7
3503 >>> fi = FuzzyFloat(42.7)
3505 >>> fi.low, fi.high
3506 0.0, 42.7
3507 low decimal, the inclusive lower bound of generated floats
3509 high decimal, the inclusive higher bound of generated floats
3511 FuzzyDate
3513 class factory.fuzzy.FuzzyDate(start_date[, end_date])
3514 The FuzzyDate fuzzer generates random dates within a given
3515 inclusive range.
3516 The end_date bound may be omitted, in which case it defaults to
3518 the current date:
3519 >>> fd = FuzzyDate(datetime.date(2008, 1, 1))
3521 >>> fd.start_date, fd.end_date
3522 datetime.date(2008, 1, 1), datetime.date(2013, 4, 16)
3523 start_date
3525 datetime.date, the inclusive lower bound of generated
3526 dates
3527 end_date
3529 datetime.date, the inclusive higher bound of generated
3530 dates
3531 FuzzyDateTime
3533 class factory.fuzzy.FuzzyDateTime(start_dt[, end_dt], force_year=None,
3534 force_month=None, force_day=None, force_hour=None, force_minute=None,
3535 force_second=None, force_microsecond=None)
3536 The FuzzyDateTime fuzzer generates random timezone-aware date‐
3537 time within a given inclusive range.
3538 The end_dt bound may be omitted, in which case it defaults to
3540 datetime.datetime.now() localized into the UTC timezone.
3541 >>> fdt = FuzzyDateTime(datetime.datetime(2008, 1, 1, tzinfo=UTC))
3543 >>> fdt.start_dt, fdt.end_dt
3544 datetime.datetime(2008, 1, 1, tzinfo=UTC), datetime.datetime(2013, 4, 21, 19, 13, 32, 458487, tzinfo=UTC)
3545 The force_XXX keyword arguments force the related value of gen‐
3547 erated datetimes:
3548 >>> fdt = FuzzyDateTime(datetime.datetime(2008, 1, 1, tzinfo=UTC), datetime.datetime(2009, 1, 1, tzinfo=UTC),
3550 ... force_day=3, force_second=42)
3551 >>> fdt.evaluate(2, None, False) # Actual code used by ``SomeFactory.build()``
3552 datetime.datetime(2008, 5, 3, 12, 13, 42, 124848, tzinfo=UTC)
3553 start_dt
3555 datetime.datetime, the inclusive lower bound of generated
3556 datetimes
3557 end_dt datetime.datetime, the inclusive upper bound of generated
3559 datetimes
3560 force_year
3562 int or None; if set, forces the year of generated date‐
3563 time.
3564 force_month
3566 int or None; if set, forces the month of generated date‐
3567 time.
3568 force_day
3570 int or None; if set, forces the day of generated date‐
3571 time.
3572 force_hour
3574 int or None; if set, forces the hour of generated date‐
3575 time.
3576 force_minute
3578 int or None; if set, forces the minute of generated date‐
3579 time.
3580 force_second
3582 int or None; if set, forces the second of generated date‐
3583 time.
3584 force_microsecond
3586 int or None; if set, forces the microsecond of generated
3587 datetime.
3588 FuzzyNaiveDateTime
3590 class factory.fuzzy.FuzzyNaiveDateTime(start_dt[, end_dt],
3591 force_year=None, force_month=None, force_day=None, force_hour=None,
3592 force_minute=None, force_second=None, force_microsecond=None)
3593 The FuzzyNaiveDateTime fuzzer generates random naive datetime
3594 within a given inclusive range.
3595 The end_dt bound may be omitted, in which case it defaults to
3597 datetime.datetime.now():
3598 >>> fdt = FuzzyNaiveDateTime(datetime.datetime(2008, 1, 1))
3600 >>> fdt.start_dt, fdt.end_dt
3601 datetime.datetime(2008, 1, 1), datetime.datetime(2013, 4, 21, 19, 13, 32, 458487)
3602 The force_XXX keyword arguments force the related value of gen‐
3604 erated datetimes:
3605 >>> fdt = FuzzyNaiveDateTime(datetime.datetime(2008, 1, 1), datetime.datetime(2009, 1, 1),
3607 ... force_day=3, force_second=42)
3608 >>> fdt.evaluate(2, None, False) # Actual code used by ``SomeFactory.build()``
3609 datetime.datetime(2008, 5, 3, 12, 13, 42, 124848)
3610 start_dt
3612 datetime.datetime, the inclusive lower bound of generated
3613 datetimes
3614 end_dt datetime.datetime, the inclusive upper bound of generated
3616 datetimes
3617 force_year
3619 int or None; if set, forces the year of generated date‐
3620 time.
3621 force_month
3623 int or None; if set, forces the month of generated date‐
3624 time.
3625 force_day
3627 int or None; if set, forces the day of generated date‐
3628 time.
3629 force_hour
3631 int or None; if set, forces the hour of generated date‐
3632 time.
3633 force_minute
3635 int or None; if set, forces the minute of generated date‐
3636 time.
3637 force_second
3639 int or None; if set, forces the second of generated date‐
3640 time.
3641 force_microsecond
3643 int or None; if set, forces the microsecond of generated
3644 datetime.
3645 Custom fuzzy fields
3647 Alternate fuzzy fields may be defined. They should inherit from the
3648 BaseFuzzyAttribute class, and override its fuzz() method.
3649 class factory.fuzzy.BaseFuzzyAttribute
3651 Base class for all fuzzy attributes.
3652 fuzz(self)
3654 The method responsible for generating random values.
3655 Must be overridden in subclasses.
3656 WARNING:
3658 Custom BaseFuzzyAttribute subclasses MUST use factory.ran‐
3659 dom.randgen as a randomness source; this ensures that data
3660 they generate can be regenerated using the simple state from
3661 get_random_state().
3662 Examples
3664 Here are some real-world examples of using FactoryBoy.
3665 Objects
3667 First, let’s define a couple of objects:
3668 class Account(object):
3670 def __init__(self, username, email, date_joined):
3671 self.username = username
3672 self.email = email
3673 self.date_joined = date_joined
3674 def __str__(self):
3676 return '%s (%s)' % (self.username, self.email)
3677 class Profile(object):
3680 GENDER_MALE = 'm'
3682 GENDER_FEMALE = 'f'
3683 GENDER_UNKNOWN = 'u' # If the user refused to give it
3684 def __init__(self, account, gender, firstname, lastname, planet='Earth'):
3686 self.account = account
3687 self.gender = gender
3688 self.firstname = firstname
3689 self.lastname = lastname
3690 self.planet = planet
3691 def __unicode__(self):
3693 return u'%s %s (%s)' % (
3694 unicode(self.firstname),
3695 unicode(self.lastname),
3696 unicode(self.account.username),
3697 )
3698 Factories
3700 And now, we’ll define the related factories:
3701 import datetime
3703 import factory
3704 import random
3705 from . import objects
3707 class AccountFactory(factory.Factory):
3710 class Meta:
3711 model = objects.Account
3712 username = factory.Sequence(lambda n: 'john%s' % n)
3714 email = factory.LazyAttribute(lambda o: '%s@example.org' % o.username)
3715 date_joined = factory.LazyFunction(datetime.datetime.now)
3716 class ProfileFactory(factory.Factory):
3719 class Meta:
3720 model = objects.Profile
3721 account = factory.SubFactory(AccountFactory)
3723 gender = factory.Iterator([objects.Profile.GENDER_MALE, objects.Profile.GENDER_FEMALE])
3724 firstname = u'John'
3725 lastname = u'Doe'
3726 We have now defined basic factories for our Account and Profile
3728 classes.
3729 If we commonly use a specific variant of our objects, we can refine a
3731 factory accordingly:
3732 class FemaleProfileFactory(ProfileFactory):
3734 gender = objects.Profile.GENDER_FEMALE
3735 firstname = u'Jane'
3736 user__username = factory.Sequence(lambda n: 'jane%s' % n)
3737 Using the factories
3739 We can now use our factories, for tests:
3740 import unittest
3742 from . import business_logic
3744 from . import factories
3745 from . import objects
3746 class MyTestCase(unittest.TestCase):
3749 def test_send_mail(self):
3751 account = factories.AccountFactory()
3752 email = business_logic.prepare_email(account, subject='Foo', text='Bar')
3753 self.assertEqual(email.to, account.email)
3755 def test_get_profile_stats(self):
3757 profiles = []
3758 profiles.extend(factories.ProfileFactory.create_batch(4))
3760 profiles.extend(factories.FemaleProfileFactory.create_batch(2))
3761 profiles.extend(factories.ProfileFactory.create_batch(2, planet="Tatooine"))
3762 stats = business_logic.profile_stats(profiles)
3764 self.assertEqual({'Earth': 6, 'Mars': 2}, stats.planets)
3765 self.assertLess(stats.genders[objects.Profile.GENDER_FEMALE], 2)
3766 Or for fixtures:
3768 from . import factories
3770 def make_objects():
3772 factories.ProfileFactory.create_batch(size=50)
3773 # Let's create a few, known objects.
3775 factories.ProfileFactory(
3776 gender=objects.Profile.GENDER_MALE,
3777 firstname='Luke',
3778 lastname='Skywalker',
3779 planet='Tatooine',
3780 )
3781 factories.ProfileFactory(
3783 gender=objects.Profile.GENDER_FEMALE,
3784 firstname='Leia',
3785 lastname='Organa',
3786 planet='Alderaan',
3787 )
3788 Internals
3790 Behind the scenes: steps performed when parsing a factory declaration,
3791 and when calling it.
3792 This section will be based on the following factory declaration:
3794 class UserFactory(factory.Factory):
3796 class Meta:
3797 model = User
3798 class Params:
3800 # Allow us to quickly enable staff/superuser flags
3801 superuser = factory.Trait(
3802 is_superuser=True,
3803 is_staff=True,
3804 )
3805 # Meta parameter handling all 'enabled'-related fields
3806 enabled = True
3807 # Classic fields
3809 username = factory.Faker('user_name')
3810 full_name = factory.Faker('name')
3811 creation_date = factory.fuzzy.FuzzyDateTime(
3812 datetime.datetime(2000, 1, 1, tzinfo=UTC),
3813 datetime.datetime(2015, 12, 31, 20, tzinfo=UTC)
3814 )
3815 # Conditional flags
3817 is_active = factory.SelfAttribute('enabled')
3818 deactivation_date = factory.Maybe(
3819 'enabled',
3820 None,
3821 factory.fuzzy.FuzzyDateTime(
3822 datetime.datetime.now().replace(tzinfo=UTC) - datetime.timedelta(days=10),
3823 datetime.datetime.now().replace(tzinfo=UTC) - datetime.timedelta(days=1),
3824 ),
3825 )
3826 # Related logs
3828 creation_log = factory.RelatedFactory(
3829 UserLogFactory, 'user',
3830 action='create', timestamp=factory.SelfAttribute('user.creation_date'),
3831 )
3832 Parsing, Step 1: Metaclass and type declaration
3835 1. Python parses the declaration and calls (thanks to the metaclass
3836 declaration):
3837 factory.base.BaseFactory.__new__(
3839 'UserFactory',
3840 (factory.Factory,),
3841 attributes,
3842 )
3843 2. That metaclass removes Meta and Params from the class attributes,
3845 then generate the actual factory class (according to standard Python
3846 rules)
3847 3. It initializes a FactoryOptions object, and links it to the class
3849 Parsing, Step 2: adapting the class definition
3851 1. The FactoryOptions reads the options from the class Meta declaration
3852 2. It finds a few specific pointer (loading the model class, finding
3854 the reference factory for the sequence counter, etc.)
3855 3. It copies declarations and parameters from parent classes
3857 4. It scans current class attributes (from vars()) to detect pre/post
3859 declarations
3860 5. Declarations are split among pre-declarations and post-declarations
3862 (a raw value shadowing a post-declaration is seen as a post-declara‐
3863 tion)
3864 NOTE:
3866 A declaration for foo__bar will be converted into parameter bar for
3867 declaration foo.
3868 Instantiating, Step 1: Converging entrypoints
3870 First, decide the strategy:
3871 · If the entrypoint is specific to a strategy (build(), create_batch(),
3873 …), use it
3874 · If it is generic (generate(), Factory.__call__()), use the strategy
3876 defined at the class Meta level
3877 Then, we’ll pass the strategy and passed-in overrides to the _gener‐
3879 ate() method.
3880 NOTE:
3882 According to the project roadmap, a future version will use a _gen‐
3883 erate_batch`() at its core instead.
3884 A factory’s _generate() function actually delegates to a StepBuilder()
3886 object. This object will carry the overall “build an object” context
3887 (strategy, depth, and possibly other).
3888 Instantiating, Step 2: Preparing values
3890 1. The StepBuilder merges overrides with the class-level declarations
3891 2. The sequence counter for this instance is initialized
3893 3. A Resolver is set up with all those declarations, and parses them in
3895 order; it will call each value’s evaluate() method, including extra
3896 parameters.
3897 4. If needed, the Resolver might recurse (through the StepBuilder, e.g
3899 when encountering a SubFactory.
3900 Instantiating, Step 3: Building the object
3902 1. The StepBuilder fetches the attributes computed by the Resolver.
3903 2. It applies renaming/adjustment rules
3905 3. It passes them to the FactoryOptions.instantiate() method, which
3907 forwards to the proper methods.
3908 4. Post-declaration are applied (in declaration order)
3910 NOTE:
3912 This document discusses implementation details; there is no guaran‐
3913 tee that the described methods names and signatures will be kept as
3914 is.
3915 ChangeLog
3917 2.12.0 (2019-05-11)
3918 New:
3919 · Add support for Python 3.7
3921 · Add support for Django 2.1
3923 · Add getter to FuzzyChoice that mimics the behavior of getter in
3925 Iterator
3926 · Make the extra_kwargs parameter of generate() optional
3928 · Add RelatedFactoryList class for one-to-many support, thanks Sean
3930 Harrington.
3931 · Make the locale argument for Faker keyword-only
3933 Bugfix:
3935 · Allow renamed arguments to be optional, thanks to Justin Crown.
3937 · Fix django_get_or_create behavior when using multiple fields with
3939 unique=True, thanks to @YPCrumble <https://github.com/YPCrumble>
3940 2.11.1 (2018-05-05)
3942 Bugfix:
3943 · Fix passing deep context to a SubFactory (Foo(x__y__z=fac‐
3945 tory.Faker('name'))
3946 2.11.0 (2018-05-05)
3948 Bugfix:
3949 · Fix FuzzyFloat to return a 15 decimal digits precision float by
3951 default
3952 · issue #451: Restore FileField to a ParameteredAttribute, relying
3954 on composition to parse the provided parameters.
3955 · issue #389: Fix random state management with faker.
3957 · issue #466: Restore mixing Trait and post_generation().
3959 2.10.0 (2018-01-28)
3961 Bugfix:
3962 · issue #443: Don’t crash when calling factory.Iterator.reset() on a
3964 brand new iterator.
3965 New:
3967 · issue #397: Allow a factory.Maybe to contain a PostGenerationDec‐
3969 laration. This also applies to factory.Trait, since they use a
3970 factory.Maybe declaration internally.
3971 2.9.2 (2017-08-03)
3973 Bugfix:
3974 · Fix declaration corruption bug when a factory defined
3976 foo__bar__baz=1 and a caller provided a foo__bar=x parameter at
3977 call time: this got merged into the factory’s base declarations.
3978 2.9.1 (2017-08-02)
3980 Bugfix:
3981 · Fix packaging issues (see
3983 https://github.com/zestsoftware/zest.releaser/issues/212)
3984 · Don’t crash when debugging PostGenerationDeclaration
3986 2.9.0 (2017-07-30)
3988 This version brings massive changes to the core engine, thus reducing
3989 the number of corner cases and weird behaviourrs.
3990 New:
3992 · issue #275: factory.fuzzy and factory.faker now use the same ran‐
3994 dom seed.
3995 · Add factory.Maybe, which chooses among two possible declarations
3997 based on another field’s value (powers the Trait feature).
3998 · PostGenerationMethodCall only allows to pass one positional argu‐
4000 ment; use keyword arguments for extra parameters.
4001 Deprecation:
4003 · factory.fuzzy.get_random_state is deprecated, factory.ran‐
4005 dom.get_random_state should be used instead.
4006 · factory.fuzzy.set_random_state is deprecated, factory.ran‐
4008 dom.set_random_state should be used instead.
4009 · factory.fuzzy.reseed_random is deprecated, factory.ran‐
4011 dom.reseed_random should be used instead.
4012 2.8.1 (2016-12-17)
4014 Bugfix:
4015 · Fix packaging issues.
4017 2.8.0 (2016-12-17)
4019 New:
4020 · issue #240: Call post-generation declarations in the order they
4022 were declared, thanks to Oleg Pidsadnyi.
4023 · issue #309: Provide new options for SQLAlchemy session persistence
4025 Bugfix:
4027 · issue #334: Adjust for the package change in faker
4029 2.7.0 (2016-04-19)
4031 New:
4032 · pull request #267: Add factory.LazyFunction to remove unneeded
4034 lambda parameters, thanks to Hervé Cauwelier.
4035 · issue #251: Add parameterized factories and traits
4037 · pull request #256, pull request #292: Improve error messages in
4039 corner cases
4040 Removed:
4042 · pull request #278: Formally drop support for Python2.6
4044 WARNING:
4046 Version 2.7.0 moves all error classes to factory.errors. This breaks
4047 existing import statements for any error classes except those
4048 importing FactoryError directly from the factory module.
4049 2.6.1 (2016-02-10)
4051 New:
4052 · pull request #262: Allow optional forced flush on SQLAlchemy,
4054 courtesy of Minjung.
4055 2.6.0 (2015-10-20)
4057 New:
4058 · Add factory.FactoryOptions.rename to help handle conflicting names
4060 (issue #206)
4061 · Add support for random-yet-realistic values through fake-factory,
4063 through the factory.Faker class.
4064 · factory.Iterator no longer begins iteration of its argument at
4066 import time, thus allowing to pass in a lazy iterator such as a
4067 Django queryset (i.e factory.Iterator(mod‐
4068 els.MyThingy.objects.all())).
4069 · Simplify imports for ORM layers, now available through a simple
4071 factory import, at factory.alchemy.SQLAlchemyModelFactory / fac‐
4072 tory.django.DjangoModelFactory / factory.mongoengine.MongoEngine‐
4073 Factory.
4074 Bugfix:
4076 · issue #201: Properly handle custom Django managers when dealing
4078 with abstract Django models.
4079 · issue #212: Fix factory.django.mute_signals() to handle Django’s
4081 signal caching
4082 · issue #228: Don’t load django.apps.apps.get_model() until required
4084 · pull request #219: Stop using mogo.model.Model.new(), deprecated 4
4086 years ago.
4087 2.5.2 (2015-04-21)
4089 Bugfix:
4090 · Add support for Django 1.7/1.8
4092 · Add support for mongoengine>=0.9.0 / pymongo>=2.1
4094 2.5.1 (2015-03-27)
4096 Bugfix:
4097 · Respect custom managers in DjangoModelFactory (see issue #192)
4099 · Allow passing declarations (e.g Sequence) as parameters to File‐
4101 Field and ImageField.
4102 2.5.0 (2015-03-26)
4104 New:
4105 · Add support for getting/setting factory.fuzzy’s random state (see
4107 issue #175, issue #185).
4108 · Support lazy evaluation of iterables in factory.fuzzy.FuzzyChoice
4110 (see issue #184).
4111 · Support non-default databases at the factory level (see issue
4113 #171)
4114 · Make factory.django.FileField and factory.django.ImageField
4116 non-post_generation, i.e normal fields also available in save()
4117 (see issue #141).
4118 Bugfix:
4120 · Avoid issues when using factory.django.mute_signals() on a base
4122 factory class (see issue #183).
4123 · Fix limitations of factory.StubFactory, that can now use fac‐
4125 tory.SubFactory and co (see issue #131).
4126 Deprecation:
4128 · Remove deprecated features from 2.4.0 (2014-06-21)
4130 · Remove the auto-magical sequence setup (based on the latest pri‐
4132 mary key value in the database) for Django and SQLAlchemy; this
4133 relates to issues issue #170, issue #153, issue #111, issue #103,
4134 issue #92, issue #78. See
4135 https://github.com/FactoryBoy/factory_boy/commit/13d310f for tech‐
4136 nical details.
4137 WARNING:
4139 Version 2.5.0 removes the ‘auto-magical sequence setup’ bug-and-fea‐
4140 ture. This could trigger some bugs when tests expected a non-zero
4141 sequence reference.
4142 Upgrading
4144 WARNING:
4145 Version 2.5.0 removes features that were marked as deprecated in
4146 v2.4.0.
4147 All FACTORY_*-style attributes are now declared in a class Meta: sec‐
4149 tion:
4150 # Old-style, deprecated
4152 class MyFactory(factory.Factory):
4153 FACTORY_FOR = models.MyModel
4154 FACTORY_HIDDEN_ARGS = ['a', 'b', 'c']
4155 # New-style
4157 class MyFactory(factory.Factory):
4158 class Meta:
4159 model = models.MyModel
4160 exclude = ['a', 'b', 'c']
4161 A simple shell command to upgrade the code would be:
4163 # sed -i: inplace update
4165 # grep -l: only file names, not matching lines
4166 sed -i 's/FACTORY_FOR =/class Meta:\n model =/' $(grep -l FACTORY_FOR $(find . -name '*.py'))
4167 This takes care of all FACTORY_FOR occurrences; the files containing
4169 other attributes to rename can be found with grep -R FACTORY .
4170 2.4.1 (2014-06-23)
4172 Bugfix:
4173 · Fix overriding deeply inherited attributes (set in one factory,
4175 overridden in a subclass, used in a sub-sub-class).
4176 2.4.0 (2014-06-21)
4178 New:
4179 · Add support for factory.fuzzy.FuzzyInteger.step, thanks to
4181 ilya-pirogov (pull request #120)
4182 · Add mute_signals() decorator to temporarily disable some signals,
4184 thanks to ilya-pirogov (pull request #122)
4185 · Add FuzzyFloat (issue #124)
4187 · Declare target model and other non-declaration fields in a class
4189 Meta section.
4190 Deprecation:
4192 · Use of FACTORY_FOR and other FACTORY class-level attributes is
4194 deprecated and will be removed in 2.5. Those attributes should
4195 now declared within the class Meta attribute:
4196 For factory.Factory:
4198 · Rename FACTORY_FOR to model
4200 · Rename ABSTRACT_FACTORY to abstract
4202 · Rename FACTORY_STRATEGY to strategy
4204 · Rename FACTORY_ARG_PARAMETERS to inline_args
4206 · Rename FACTORY_HIDDEN_ARGS to exclude
4208 For factory.django.DjangoModelFactory:
4210 · Rename FACTORY_DJANGO_GET_OR_CREATE to django_get_or_create
4212 For factory.alchemy.SQLAlchemyModelFactory:
4214 · Rename FACTORY_SESSION to sqlalchemy_session
4216 2.3.1 (2014-01-22)
4218 Bugfix:
4219 · Fix badly written assert containing state-changing code, spotted
4221 by chsigi (pull request #126)
4222 · Don’t crash when handling objects whose __repr__ is non-pure-ascii
4224 bytes on Py2, discovered by mbertheau (issue #123) and strycore (‐
4225 pull request #127)
4226 2.3.0 (2013-12-25)
4228 New:
4229 · Add FuzzyText, thanks to jdufresne (pull request #97)
4231 · Add FuzzyDecimal, thanks to thedrow (pull request #94)
4233 · Add support for EmbeddedDocument, thanks to imiric (pull request
4235 #100)
4236 2.2.1 (2013-09-24)
4238 Bugfix:
4239 · Fixed sequence counter for DjangoModelFactory when a factory
4241 inherits from another factory relating to an abstract model.
4242 2.2.0 (2013-09-24)
4244 Bugfix:
4245 · Removed duplicated SQLAlchemyModelFactory lurking in factory (pull
4247 request #83)
4248 · Properly handle sequences within object inheritance chains. If
4250 FactoryA inherits from FactoryB, and their associated classes
4251 share the same link, sequence counters will be shared (issue #93)
4252 · Properly handle nested SubFactory overrides
4254 New:
4256 · The DjangoModelFactory now supports the FACTORY_FOR =
4258 'myapp.MyModel' syntax, making it easier to shove all factories in
4259 a single module (issue #66).
4260 · Add factory.debug() helper for easier backtrace analysis
4262 · Adding factory support for mongoengine with MongoEngineFactory.
4264 2.1.2 (2013-08-14)
4266 New:
4267 · The ABSTRACT_FACTORY keyword is now optional, and automatically
4269 set to True if neither the Factory subclass nor its parent declare
4270 the FACTORY_FOR attribute (issue #74)
4271 2.1.1 (2013-07-02)
4273 Bugfix:
4274 · Properly retrieve the color keyword argument passed to ImageField
4276 2.1.0 (2013-06-26)
4278 New:
4279 · Add FuzzyDate thanks to saulshanabrook
4281 · Add FuzzyDateTime and FuzzyNaiveDateTime.
4283 · Add a factory_parent attribute to the Resolver passed to LazyAt‐
4285 tribute, in order to access fields defined in wrapping factories.
4286 · Move DjangoModelFactory and MogoFactory to their own modules (fac‐
4288 tory.django and factory.mogo)
4289 · Add the reset_sequence() classmethod to Factory to ease resetting
4291 the sequence counter for a given factory.
4292 · Add debug messages to factory logger.
4294 · Add a reset() method to Iterator (issue #63)
4296 · Add support for the SQLAlchemy ORM through SQLAlchemyModelFactory
4298 (pull request #64, thanks to Romain Commandé)
4299 · Add factory.django.FileField and factory.django.ImageField hooks
4301 for related Django model fields (issue #52)
4302 Bugfix
4304 · Properly handle non-integer pks in DjangoModelFactory (issue #57).
4306 · Disable RelatedFactory generation when a specific value was passed
4308 (issue #62, thanks to Gabe Koscky)
4309 Deprecation:
4311 · Rename RelatedFactory’s name argument to factory_related_name (See
4313 issue #58)
4314 2.0.2 (2013-04-16)
4316 New:
4317 · When FACTORY_DJANGO_GET_OR_CREATE is empty, use Model.objects.cre‐
4319 ate() instead of Model.objects.get_or_create.
4320 2.0.1 (2013-04-16)
4322 New:
4323 · Don’t push defaults to get_or_create when FAC‐
4325 TORY_DJANGO_GET_OR_CREATE is not set.
4326 2.0.0 (2013-04-15)
4328 New:
4329 · Allow overriding the base factory class for make_factory() and
4331 friends.
4332 · Add support for Python3 (Thanks to kmike and nkryptic)
4334 · The default type for Sequence is now int
4336 · Fields listed in FACTORY_HIDDEN_ARGS won’t be passed to the asso‐
4338 ciated class’ constructor
4339 · Add support for get_or_create in DjangoModelFactory, through FAC‐
4341 TORY_DJANGO_GET_OR_CREATE.
4342 · Add support for fuzzy attribute definitions.
4344 · The Sequence counter can be overridden when calling a generating
4346 function
4347 · Add Dict and List declarations (Closes issue #18).
4349 Removed:
4351 · Remove associated class discovery
4353 · Remove InfiniteIterator and infinite_iterator()
4355 · Remove CircularSubFactory
4357 · Remove extract_prefix kwarg to post-generation hooks.
4359 · Stop defaulting to Django’s Foo.objects.create() when “creating”
4361 instances
4362 · Remove STRATEGY_*
4364 · Remove set_building_function() / set_creation_function()
4366 1.3.0 (2013-03-11)
4368 WARNING:
4369 This version deprecates many magic or unexplicit features that will
4370 be removed in v2.0.0.
4371 Please read the Upgrading section, then run your tests with python
4373 -W default to see all remaining warnings.
4374 New
4376 ·
4377 Global:
4379 · Rewrite the whole documentation
4381 · Provide a dedicated MogoFactory subclass of Factory
4383 ·
4385 The Factory class:
4387 · Better creation/building customization hooks at factory.Fac‐
4389 tory._build() and factory.Factory.create()
4390 · Add support for passing non-kwarg parameters to a Factory
4392 wrapped class through FACTORY_ARG_PARAMETERS.
4393 · Keep the FACTORY_FOR attribute in Factory classes
4395 ·
4397 Declarations:
4399 · Allow SubFactory to solve circular dependencies between fac‐
4401 tories
4402 · Enhance SelfAttribute to handle “container” attribute fetch‐
4404 ing
4405 · Add a getter to Iterator declarations
4407 · A Iterator may be prevented from cycling by setting its
4409 cycle argument to False
4410 · Allow overriding default arguments in a PostGeneration‐
4412 MethodCall when generating an instance of the factory
4413 · An object created by a DjangoModelFactory will be saved
4415 again after PostGeneration hooks execution
4416 Pending deprecation
4418 The following features have been deprecated and will be removed in an
4419 upcoming release.
4420 ·
4422 Declarations:
4424 · InfiniteIterator is deprecated in favor of Iterator
4426 · CircularSubFactory is deprecated in favor of SubFactory
4428 · The extract_prefix argument to post_generation() is now dep‐
4430 recated
4431 ·
4433 Factory:
4435 · Usage of set_creation_function() and set_building_function()
4437 are now deprecated
4438 · Implicit associated class discovery is no longer supported,
4440 you must set the FACTORY_FOR attribute on all Factory sub‐
4441 classes
4442 Upgrading
4444 This version deprecates a few magic or undocumented features. All
4445 warnings will turn into errors starting from v2.0.0.
4446 In order to upgrade client code, apply the following rules:
4448 · Add a FACTORY_FOR attribute pointing to the target class to each Fac‐
4450 tory, instead of relying on automagic associated class discovery
4451 · When using factory_boy for Django models, have each factory inherit
4453 from DjangoModelFactory
4454 · Replace factory.CircularSubFactory('some.module', 'Symbol') with fac‐
4456 tory.SubFactory('some.module.Symbol')
4457 · Replace factory.InfiniteIterator(iterable) with factory.Itera‐
4459 tor(iterable)
4460 · Replace @factory.post_generation() with @factory.post_generation
4462 · Replace factory.set_building_function(SomeFactory, building_function)
4464 with an override of the _build() method of SomeFactory
4465 · Replace factory.set_creation_function(SomeFactory, creation_function)
4467 with an override of the _create() method of SomeFactory
4468 1.2.0 (2012-09-08)
4470 New:
4471 · Add CircularSubFactory to solve circular dependencies between fac‐
4473 tories
4474 1.1.5 (2012-07-09)
4476 Bugfix:
4477 · Fix PostGenerationDeclaration and derived classes.
4479 1.1.4 (2012-06-19)
4481 New:
4482 · Add use_strategy() decorator to override a Factory’s default
4484 strategy
4485 · Improve test running (tox, python2.6/2.7)
4487 · Introduce PostGeneration and RelatedFactory
4489 1.1.3 (2012-03-09)
4491 Bugfix:
4492 · Fix packaging rules
4494 1.1.2 (2012-02-25)
4496 New:
4497 · Add Iterator and InfiniteIterator for Factory attribute declara‐
4499 tions.
4500 · Provide generate() and simple_generate(), that allow specifying
4502 the instantiation strategy directly. Also provides gener‐
4503 ate_batch() and simple_generate_batch().
4504 1.1.1 (2012-02-24)
4506 New:
4507 · Add build_batch(), create_batch() and stub_batch(), to instantiate
4509 factories in batch
4510 1.1.0 (2012-02-24)
4512 New:
4513 · Improve the SelfAttribute syntax to fetch sub-attributes using the
4515 foo.bar syntax;
4516 · Add ContainerAttribute to fetch attributes from the container of a
4518 SubFactory.
4519 · Provide the make_factory() helper: MyClassFactory = make_fac‐
4521 tory(MyClass, x=3, y=4)
4522 · Add build(), create(), stub() helpers
4524 Bugfix:
4526 · Allow classmethod/staticmethod on factories
4528 Deprecation:
4530 · Auto-discovery of FACTORY_FOR based on class name is now depre‐
4532 cated
4533 1.0.4 (2011-12-21)
4535 New:
4536 · Improve the algorithm for populating a Factory attributes dict
4538 · Add python setup.py test command to run the test suite
4540 · Allow custom build functions
4542 · Introduce MOGO_BUILD build function
4544 · Add support for inheriting from multiple Factory
4546 · Base Factory classes can now be declared abstract.
4548 · Provide DjangoModelFactory, whose Sequence counter starts at the
4550 next free database id
4551 · Introduce SelfAttribute, a shortcut for factory.LazyAt‐
4553 tribute(lambda o: o.foo.bar.baz.
4554 Bugfix:
4556 · Handle nested SubFactory
4558 · Share sequence counter between parent and subclasses
4560 · Fix SubFactory / Sequence interferences
4562 1.0.2 (2011-05-16)
4564 New:
4565 · Introduce SubFactory
4567 1.0.1 (2011-05-13)
4569 New:
4570 · Allow Factory inheritance
4572 · Improve handling of custom build/create functions
4574 Bugfix:
4576 · Fix concurrency between LazyAttribute and Sequence
4578 1.0.0 (2010-08-22)
4580 New:
4581 · First version of factory_boy
4583 Credits
4585 · Initial version by Mark Sandstrom (2010)
4586 · Developed by Raphaël Barrois since 2011
4588 Credits
4590 Maintainers
4591 The factory_boy project is operated and maintained by:
4592 · Jeff Widman <jeff@jeffwidman.com> (https://github.com/jeffwidman)
4594 · Raphaël Barrois <raphael.barrois+fboy@polytechnique.org> (‐
4596 https://github.com/rbarrois)
4597 Contributors
4599 The project was initially created by Mark Sandstrom <‐
4600 mark@deliciouslynerdy.com>.
4601 The project has received contributions from (in alphabetical order):
4603 · Adam Chainz <adam@adamj.eu>
4605 · Alejandro <tovarich@gmail.com>
4607 · Alexey Kotlyarov <a@koterpillar.com>
4609 · Amit Shah <amit@amwam.me>
4611 · Anas Zahim <zanass0@gmail.com> (https://github.com/kamotos)
4613 · Andrey Voronov <voronov84@gmail.com>
4615 · Branko Majic <branko@majic.rs>
4617 · Carl Meyer <carl@oddbird.net>
4619 · Chris Lasher <chris.lasher@gmail.com>
4621 · Chris Seto <chriskseto@gmail.com>
4623 · Christoph Sieghart <sigi@0x2a.at>
4625 · David Baumgold <david@davidbaumgold.com>
4627 · Demur Nodia <demur.nodia@gmail.com> (https://github.com/demonno)
4629 · Eduard Iskandarov <edikexp@gmail.com>
4631 · Federico Bond <federicobond@gmail.com> (‐
4633 https://github.com/federicobond)
4634 · Flavio Curella <flavio.curella@gmail.com>
4636 · François Freitag <mail@franek.fr>
4638 · George Hickman <george@ghickman.co.uk>
4640 · Hervé Cauwelier <herve.cauwelier@polyconseil.fr>
4642 · Ilya Baryshev <baryshev@gmail.com>
4644 · Ilya Pirogov <ilja.pirogov@gmail.com>
4646 · Ionuț Arțăriși <ionut@artarisi.eu>
4648 · Issa Jubril <issa.jubril@andela.com>
4650 · Ivan Miric <imiric@gmail.com>
4652 · Janusz Skonieczny <wooyek@users.noreply.github.com>
4654 · Jeff Widman <jeff@jeffwidman.com> (https://github.com/jeffwidman)
4656 · Jon Dufresne <jon.dufresne@gmail.com>
4658 · Jonathan Tushman <jtushman@pipewave.com>
4660 · Joshua Carp <jm.carp@gmail.com>
4662 · Leonardo Lazzaro <llazzaro@dc.uba.ar>
4664 · Luke GB <github@lukegb.com>
4666 · Marc Abramowitz <marc@marc-abramowitz.com>
4668 · Mark Sandstrom <mark@deliciouslynerdy.com>
4670 · Martin Bächtold <martin+factoryboy@baechtold.me> (‐
4672 https://github.com/mbaechtold)
4673 · Michael Joseph <michaeljoseph+github@gmail.com>
4675 · Mikhail Korobov <kmike84@gmail.com>
4677 · Oleg Pidsadnyi <oleg.pidsadnyi@gmail.com>
4679 · Omer <omer@stokeet.com>
4681 · Pauly Fenwar <fenney@gmail.com>
4683 · Peter Marsh <pete@skimlinks.com>
4685 · Puneeth Chaganti <punchagan@muse-amuse.in>
4687 · QuantumGhost <obelisk.reg+github@gmail.com>
4689 · Raphaël Barrois <raphael.barrois+fboy@polytechnique.org> (‐
4691 https://github.com/rbarrois)
4692 · Rich Rauenzahn <rich@vmware.com>
4694 · Richard Moch <richard@mbp.polyconseil.fr>
4696 · Rob Zyskowski <zyskowski.rob@gmail.com>
4698 · Robrecht De Rouck <Robrecht.De.Rouck@gmail.com>
4700 · Samuel Paccoud <samuel@sampaccoud.com>
4702 · Saul Shanabrook <s.shanabrook@gmail.com>
4704 · Sean Löfgren <SeanBE@users.noreply.github.com>
4706 · Tom <tom@tomleo.com>
4708 · alex-netquity <alex@netquity.com>
4710 · anentropic <ego@anentropic.com>
4712 · minimumserious <commande.romain@gmail.com>
4714 · mluszczyk <mluszczyk@users.noreply.github.com>
4716 · nkryptic <nkryptic@gmail.com>
4718 · obiwanus <ivan@ivanovs.info>
4720 · tsouvarev <tsouvarev@mail.ru>
4722 · yamaneko <yamaneko1212@gmail.com>
4724 Contributor license agreement
4726 NOTE:
4727 This agreement is required to allow redistribution of submitted con‐
4728 tributions. See http://oss-watch.ac.uk/resources/cla for an expla‐
4729 nation.
4730 Any contributor proposing updates to the code or documentation of this
4732 project MUST add its name to the list in the Contributors section,
4733 thereby “signing” the following contributor license agreement:
4734 They accept and agree to the following terms for their present end
4736 future contributions submitted to the factory_boy project:
4737 · They represent that they are legally entitled to grant this license,
4739 and that their contributions are their original creation
4740 · They grant the factory_boy project a perpetual, worldwide, non-exclu‐
4742 sive, no-charge, royalty-free, irrevocable copyright license to
4743 reproduce, prepare derivative works of, publicly display, sublicense
4744 and distribute their contributions and such derivative works.
4745 · They are not expected to provide support for their contributions,
4747 except to the extent they desire to provide support.
4748 NOTE:
4750 The above agreement is inspired by the Apache Contributor License
4751 Agreement.
4752 Ideas
4754 This is a list of future features that may be incorporated into fac‐
4755 tory_boy:
4756 · When a Factory is built or created, pass the calling context through‐
4758 out the calling chain instead of custom solutions everywhere
4759 · Define a proper set of rules for the support of third-party ORMs
4761 · Properly evaluate nested declarations (e.g factory.fuzzy.Fuzzy‐
4763 Date(start_date=factory.SelfAttribute('since')))
4764 · genindex
4766 · modindex
4768 · search
4770
4772 Raphaël Barrois, Mark Sandstrom
4773
4775 2011-2020, Raphaël Barrois, Mark Sandstrom
47762.12 Jan 30, 2020 FACTORYBOY(1)