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.6, 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 NOTE:
168 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.
171 Lazy Attributes
173 Most factory attributes can be added using static values that are eval‐
174 uated when the factory is defined, but some attributes (such as fields
175 whose value is computed from other elements) will need values assigned
176 each time an instance is generated.
177 These “lazy” attributes can be added as follows:
179 class UserFactory(factory.Factory):
181 class Meta:
182 model = models.User
183 first_name = 'Joe'
185 last_name = 'Blow'
186 email = factory.LazyAttribute(lambda a: '{0}.{1}@example.com'.format(a.first_name, a.last_name).lower())
187 date_joined = factory.LazyFunction(datetime.now)
188 >>> UserFactory().email
190 "joe.blow@example.com"
191 NOTE:
193 LazyAttribute calls the function with the object being constructed
194 as an argument, when LazyFunction does not send any argument.
195 Sequences
197 Unique values in a specific format (for example, e-mail addresses) can
198 be generated using sequences. Sequences are defined by using Sequence
199 or the decorator sequence:
200 class UserFactory(factory.Factory):
202 class Meta:
203 model = models.User
204 email = factory.Sequence(lambda n: 'person{0}@example.com'.format(n))
206 >>> UserFactory().email
208 'person0@example.com'
209 >>> UserFactory().email
210 'person1@example.com'
211 Associations
213 Some objects have a complex field, that should itself be defined from a
214 dedicated factories. This is handled by the SubFactory helper:
215 class PostFactory(factory.Factory):
217 class Meta:
218 model = models.Post
219 author = factory.SubFactory(UserFactory)
221 The associated object’s strategy will be used:
223 # Builds and saves a User and a Post
225 >>> post = PostFactory()
226 >>> post.id is None # Post has been 'saved'
227 False
228 >>> post.author.id is None # post.author has been saved
229 False
230 # Builds but does not save a User, and then builds but does not save a Post
232 >>> post = PostFactory.build()
233 >>> post.id is None
234 True
235 >>> post.author.id is None
236 True
237 ORM Support
239 factory_boy has specific support for a few ORMs, through specific fac‐
240 tory.Factory subclasses:
241 · Django, with factory.django.DjangoModelFactory
243 · Mogo, with factory.mogo.MogoFactory
245 · MongoEngine, with factory.mongoengine.MongoEngineFactory
247 · SQLAlchemy, with factory.alchemy.SQLAlchemyModelFactory
249 Debugging factory_boy
251 Debugging factory_boy can be rather complex due to the long chains of
252 calls. Detailed logging is available through the factory logger.
253 A helper, factory.debug(), is available to ease debugging:
255 with factory.debug():
257 obj = TestModel2Factory()
258 import logging
261 logger = logging.getLogger('factory')
262 logger.addHandler(logging.StreamHandler())
263 logger.setLevel(logging.DEBUG)
264 This will yield messages similar to those (artificial indentation):
266 BaseFactory: Preparing tests.test_using.TestModel2Factory(extra={})
268 LazyStub: Computing values for tests.test_using.TestModel2Factory(two=<OrderedDeclarationWrapper for <factory.declarations.SubFactory object at 0x1e15610>>)
269 SubFactory: Instantiating tests.test_using.TestModelFactory(__containers=(<LazyStub for tests.test_using.TestModel2Factory>,), one=4), create=True
270 BaseFactory: Preparing tests.test_using.TestModelFactory(extra={'__containers': (<LazyStub for tests.test_using.TestModel2Factory>,), 'one': 4})
271 LazyStub: Computing values for tests.test_using.TestModelFactory(one=4)
272 LazyStub: Computed values, got tests.test_using.TestModelFactory(one=4)
273 BaseFactory: Generating tests.test_using.TestModelFactory(one=4)
274 LazyStub: Computed values, got tests.test_using.TestModel2Factory(two=<tests.test_using.TestModel object at 0x1e15410>)
275 BaseFactory: Generating tests.test_using.TestModel2Factory(two=<tests.test_using.TestModel object at 0x1e15410>)
276
278 factory_boy is distributed under the MIT License.
279 Issues should be opened through GitHub Issues; whenever possible, a
281 pull request should be included. Questions and suggestions are welcome
282 on the mailing-list.
283 All pull request should pass the test suite, which can be launched sim‐
285 ply with:
286 $ make test
288 In order to test coverage, please use:
290 $ make coverage
292 To test with a specific framework version, you may use a tox target:
294 $ tox --listenvs
296 py27-django111-alchemy12-mongoengine015
297 py27-django20-alchemy12-mongoengine015
298 # ...
299 pypy3-django20-alchemy12-mongoengine015
300 examples
301 lint
302 $ tox -e py36-django20-alchemy12-mongoengine015
304 Valid options are:
306 · DJANGO for Django
308 · MONGOENGINE for mongoengine
310 · ALCHEMY for SQLAlchemy
312 To avoid running mongoengine tests (e.g no mongo server installed),
314 run:
315 $ make SKIP_MONGOENGINE=1 test
317
319 Introduction
320 The purpose of factory_boy is to provide a default way of getting a new
321 instance, while still being able to override some fields on a per-call
322 basis.
323 NOTE:
325 This section will drive you through an overview of factory_boy’s
326 feature. New users are advised to spend a few minutes browsing
327 through this list of useful helpers.
328 Users looking for quick helpers may take a look at recipes, while
330 those needing detailed documentation will be interested in the ref‐
331 erence section.
332 Basic usage
334 Factories declare a set of attributes used to instantiate an object,
335 whose class is defined in the class Meta’s model attribute:
336 · Subclass factory.Factory (or a more suitable subclass)
338 · Add a class Meta: block
340 · Set its model attribute to the target class
342 · Add defaults for keyword args to pass to the associated class’
344 __init__ method
345 import factory
347 from . import base
348 class UserFactory(factory.Factory):
350 class Meta:
351 model = base.User
352 firstname = "John"
354 lastname = "Doe"
355 You may now get base.User instances trivially:
357 >>> john = UserFactory()
359 <User: John Doe>
360 It is also possible to override the defined attributes by passing key‐
362 word arguments to the factory:
363 >>> jack = UserFactory(firstname="Jack")
365 <User: Jack Doe>
366 A given class may be associated to many Factory subclasses:
368 class EnglishUserFactory(factory.Factory):
370 class Meta:
371 model = base.User
372 firstname = "John"
374 lastname = "Doe"
375 lang = 'en'
376 class FrenchUserFactory(factory.Factory):
379 class Meta:
380 model = base.User
381 firstname = "Jean"
383 lastname = "Dupont"
384 lang = 'fr'
385 >>> EnglishUserFactory()
387 <User: John Doe (en)>
388 >>> FrenchUserFactory()
389 <User: Jean Dupont (fr)>
390 Sequences
392 When a field has a unique key, each object generated by the factory
393 should have a different value for that field. This is achieved with
394 the Sequence declaration:
395 class UserFactory(factory.Factory):
397 class Meta:
398 model = models.User
399 username = factory.Sequence(lambda n: 'user%d' % n)
401 >>> UserFactory()
403 <User: user0>
404 >>> UserFactory()
405 <User: user1>
406 NOTE:
408 For more complex situations, you may also use the @sequence() deco‐
409 rator (note that self is not added as first parameter):
410 class UserFactory(factory.Factory):
412 class Meta:
413 model = models.User
414 @factory.sequence
416 def username(n):
417 return 'user%d' % n
418 LazyFunction
420 In simple cases, calling a function is enough to compute the value. If
421 that function doesn’t depend on the object being built, use LazyFunc‐
422 tion to call that function; it should receive a function taking no
423 argument and returning the value for the field:
424 class LogFactory(factory.Factory):
426 class Meta:
427 model = models.Log
428 timestamp = factory.LazyFunction(datetime.now)
430 >>> LogFactory()
432 <Log: log at 2016-02-12 17:02:34>
433 >>> # The LazyFunction can be overriden
435 >>> LogFactory(timestamp=now - timedelta(days=1))
436 <Log: log at 2016-02-11 17:02:34>
437 NOTE:
439 For complex cases when you happen to write a specific function, the
440 @lazy_attribute() decorator should be more appropriate.
441 LazyAttribute
443 Some fields may be deduced from others, for instance the email based on
444 the username. The LazyAttribute handles such cases: it should receive
445 a function taking the object being built and returning the value for
446 the field:
447 class UserFactory(factory.Factory):
449 class Meta:
450 model = models.User
451 username = factory.Sequence(lambda n: 'user%d' % n)
453 email = factory.LazyAttribute(lambda obj: '%s@example.com' % obj.username)
454 >>> UserFactory()
456 <User: user1 (user1@example.com)>
457 >>> # The LazyAttribute handles overridden fields
459 >>> UserFactory(username='john')
460 <User: john (john@example.com)>
461 >>> # They can be directly overridden as well
463 >>> UserFactory(email='doe@example.com')
464 <User: user3 (doe@example.com)>
465 NOTE:
467 As for Sequence, a @lazy_attribute() decorator is available:
468 class UserFactory(factory.Factory):
470 class Meta:
471 model = models.User
472 username = factory.Sequence(lambda n: 'user%d' % n)
474 @factory.lazy_attribute
476 def email(self):
477 return '%s@example.com' % self.username
478 Inheritance
480 Once a “base” factory has been defined for a given class, alternate
481 versions can be easily defined through subclassing.
482 The subclassed Factory will inherit all declarations from its parent,
484 and update them with its own declarations:
485 class UserFactory(factory.Factory):
487 class Meta:
488 model = base.User
489 firstname = "John"
491 lastname = "Doe"
492 group = 'users'
493 class AdminFactory(UserFactory):
495 admin = True
496 group = 'admins'
497 >>> user = UserFactory()
499 >>> user
500 <User: John Doe>
501 >>> user.group
502 'users'
503 >>> admin = AdminFactory()
505 >>> admin
506 <User: John Doe (admin)>
507 >>> admin.group # The AdminFactory field has overridden the base field
508 'admins'
509 Any argument of all factories in the chain can easily be overridden:
511 >>> super_admin = AdminFactory(group='superadmins', lastname="Lennon")
513 >>> super_admin
514 <User: John Lennon (admin)>
515 >>> super_admin.group # Overridden at call time
516 'superadmins'
517 Non-kwarg arguments
519 Some classes take a few, non-kwarg arguments first.
520 This is handled by the inline_args attribute:
522 class MyFactory(factory.Factory):
524 class Meta:
525 model = MyClass
526 inline_args = ('x', 'y')
527 x = 1
529 y = 2
530 z = 3
531 >>> MyFactory(y=4)
533 <MyClass(1, 4, z=3)>
534 Altering a factory’s behaviour: parameters and traits
536 Some classes are better described with a few, simple parameters, that
537 aren’t fields on the actual model. In that case, use a Params declara‐
538 tion:
539 class RentalFactory(factory.Factory):
541 class Meta:
542 model = Rental
543 begin = factory.fuzzy.FuzzyDate(start_date=datetime.date(2000, 1, 1))
545 end = factory.LazyAttribute(lambda o: o.begin + o.duration)
546 class Params:
548 duration = 12
549 >>> RentalFactory(duration=0)
551 <Rental: 2012-03-03 -> 2012-03-03>
552 >>> RentalFactory(duration=10)
553 <Rental: 2008-12-16 -> 2012-12-26>
554 When many fields should be updated based on a flag, use Traits instead:
556 class OrderFactory(factory.Factory):
558 status = 'pending'
559 shipped_by = None
560 shipped_on = None
561 class Meta:
563 model = Order
564 class Params:
566 shipped = factory.Trait(
567 status='shipped',
568 shipped_by=factory.SubFactory(EmployeeFactory),
569 shipped_on=factory.LazyFunction(datetime.date.today),
570 )
571 A trait is toggled by a single boolean value:
573 >>> OrderFactory()
575 <Order: pending>
576 >>> OrderFactory(shipped=True)
577 <Order: shipped by John Doe on 2016-04-02>
578 Strategies
580 All factories support two built-in strategies:
581 · build provides a local object
583 · create instantiates a local object, and saves it to the database.
585 NOTE:
587 For 1.X versions, the create will actually call Associated‐
588 Class.objects.create, as for a Django model.
589 Starting from 2.0, factory.Factory.create() simply calls Associated‐
591 Class(**kwargs). You should use DjangoModelFactory for Django mod‐
592 els.
593 When a Factory includes related fields (SubFactory, RelatedFactory),
595 the parent’s strategy will be pushed onto related factories.
596 Calling a Factory subclass will provide an object through the default
598 strategy:
599 class MyFactory(factory.Factory):
601 class Meta:
602 model = MyClass
603 >>> MyFactory.create()
605 <MyFactory: X (saved)>
606 >>> MyFactory.build()
608 <MyFactory: X (unsaved)>
609 >>> MyFactory() # equivalent to MyFactory.create()
611 <MyClass: X (saved)>
612 The default strategy can be changed by setting the class Meta strategy
614 attribute.
615 Reference
617 This section offers an in-depth description of factory_boy features.
618 For internals and customization points, please refer to the internals
620 section.
621 The Factory class
623 Meta options
624 class factory.FactoryOptions
625 New in version 2.4.0.
626 A Factory’s behaviour can be tuned through a few settings.
629 For convenience, they are declared in a single class Meta
631 attribute:
632 class MyFactory(factory.Factory):
634 class Meta:
635 model = MyObject
636 abstract = False
637 model This optional attribute describes the class of objects to
639 generate.
640 If unset, it will be inherited from parent Factory sub‐
642 classes.
643 New in version 2.4.0.
645 get_model_class()
648 Returns the actual model class (FactoryOptions.model
649 might be the path to the class; this function will always
650 return a proper class).
651 abstract
653 This attribute indicates that the Factory subclass should
654 not be used to generate objects, but instead provides
655 some extra defaults.
656 It will be automatically set to True if neither the
658 Factory subclass nor its parents define the model
659 attribute.
660 WARNING:
662 This flag is reset to False when a Factory subclasses
663 another one if a model is set.
664 New in version 2.4.0.
666 inline_args
669 Some factories require non-keyword arguments to their
670 __init__(). They should be listed, in order, in the
671 inline_args attribute:
672 class UserFactory(factory.Factory):
674 class Meta:
675 model = User
676 inline_args = ('login', 'email')
677 login = 'john'
679 email = factory.LazyAttribute(lambda o: '%s@example.com' % o.login)
680 firstname = "John"
681 >>> UserFactory()
683 <User: john>
684 >>> User('john', 'john@example.com', firstname="John") # actual call
685 New in version 2.4.0.
687 exclude
690 While writing a Factory for some object, it may be useful
691 to have general fields helping defining others, but that
692 should not be passed to the model class; for instance, a
693 field named ‘now’ that would hold a reference time used
694 by other objects.
695 Factory fields whose name are listed in exclude will be
697 removed from the set of args/kwargs passed to the under‐
698 lying class; they can be any valid factory_boy declara‐
699 tion:
700 class OrderFactory(factory.Factory):
702 class Meta:
703 model = Order
704 exclude = ('now',)
705 now = factory.LazyFunction(datetime.datetime.utcnow)
707 started_at = factory.LazyAttribute(lambda o: o.now - datetime.timedelta(hours=1))
708 paid_at = factory.LazyAttribute(lambda o: o.now - datetime.timedelta(minutes=50))
709 >>> OrderFactory() # The value of 'now' isn't passed to Order()
711 <Order: started 2013-04-01 12:00:00, paid 2013-04-01 12:10:00>
712 >>> # An alternate value may be passed for 'now'
714 >>> OrderFactory(now=datetime.datetime(2013, 4, 1, 10))
715 <Order: started 2013-04-01 09:00:00, paid 2013-04-01 09:10:00>
716 New in version 2.4.0.
718 rename Sometimes, a model expects a field with a name already
721 used by one of Factory’s methods.
722 In this case, the rename attributes allows to define
724 renaming rules: the keys of the rename dict are those
725 used in the Factory declarations, and their values the
726 new name:
727 class ImageFactory(factory.Factory):
729 # The model expects "attributes"
730 form_attributes = ['thumbnail', 'black-and-white']
731 class Meta:
733 model = Image
734 rename = {'form_attributes': 'attributes'}
735 strategy
737 Use this attribute to change the strategy used by a
738 Factory. The default is CREATE_STRATEGY.
739 Attributes and methods
741 class factory.Factory
742 Class-level attributes:
743 Meta
745 _meta New in version 2.4.0.
747 The FactoryOptions instance attached to a Factory class
750 is available as a _meta attribute.
751 Params New in version 2.7.0.
753 The extra parameters attached to a Factory are declared
756 through a Params class. See the “Parameters” section for
757 more information.
758 _options_class
760 New in version 2.4.0.
761 If a Factory subclass needs to define additional, extra
764 options, it has to provide a custom FactoryOptions sub‐
765 class.
766 A pointer to that custom class should be provided as
768 _options_class so that the Factory-building metaclass can
769 use it instead.
770 Base functions:
772 The Factory class provides a few methods for getting objects;
774 the usual way being to simply call the class:
775 >>> UserFactory() # Calls UserFactory.create()
777 >>> UserFactory(login='john') # Calls UserFactory.create(login='john')
778 Under the hood, factory_boy will define the Factory __new__()
780 method to call the default strategy of the Factory.
781 A specific strategy for getting instance can be selected by
783 calling the adequate method:
784 classmethod build(cls, **kwargs)
786 Provides a new object, using the ‘build’ strategy.
787 classmethod build_batch(cls, size, **kwargs)
789 Provides a list of size instances from the Factory,
790 through the ‘build’ strategy.
791 classmethod create(cls, **kwargs)
793 Provides a new object, using the ‘create’ strategy.
794 classmethod create_batch(cls, size, **kwargs)
796 Provides a list of size instances from the Factory,
797 through the ‘create’ strategy.
798 classmethod stub(cls, **kwargs)
800 Provides a new stub
801 classmethod stub_batch(cls, size, **kwargs)
803 Provides a list of size stubs from the Factory.
804 classmethod generate(cls, strategy, **kwargs)
806 Provide a new instance, with the provided strategy.
807 classmethod generate_batch(cls, strategy, size, **kwargs)
809 Provides a list of size instances using the specified
810 strategy.
811 classmethod simple_generate(cls, create, **kwargs)
813 Provide a new instance, either built (create=False) or
814 created (create=True).
815 classmethod simple_generate_batch(cls, create, size, **kwargs)
817 Provides a list of size instances, either built or cre‐
818 ated according to create.
819 Extension points:
821 A Factory subclass may override a couple of class methods to
823 adapt its behaviour:
824 classmethod _adjust_kwargs(cls, **kwargs)
826 The _adjust_kwargs() extension point allows for late
827 fields tuning.
828 It is called once keyword arguments have been resolved
830 and post-generation items removed, but before the
831 inline_args extraction phase.
832 class UserFactory(factory.Factory):
834 @classmethod
836 def _adjust_kwargs(cls, **kwargs):
837 # Ensure ``lastname`` is upper-case.
838 kwargs['lastname'] = kwargs['lastname'].upper()
839 return kwargs
840 classmethod _setup_next_sequence(cls)
842 This method will compute the first value to use for the
843 sequence counter of this factory.
844 It is called when the first instance of the factory (or
846 one of its subclasses) is created.
847 Subclasses may fetch the next free ID from the database,
849 for instance.
850 classmethod _build(cls, model_class, *args, **kwargs)
852 This class method is called whenever a new instance needs
853 to be built. It receives the model class (provided to
854 model), and the positional and keyword arguments to use
855 for the class once all has been computed.
856 Subclasses may override this for custom APIs.
858 classmethod _create(cls, model_class, *args, **kwargs)
860 The _create() method is called whenever an instance needs
861 to be created. It receives the same arguments as
862 _build().
863 Subclasses may override this for specific persistence
865 backends:
866 class BaseBackendFactory(factory.Factory):
868 class Meta:
869 abstract = True # Optional
870 def _create(cls, model_class, *args, **kwargs):
872 obj = model_class(*args, **kwargs)
873 obj.save()
874 return obj
875 classmethod _after_postgeneration(cls, obj, create,
877 results=None)
878 Parameters
880 · obj (object) – The object just generated
882 · create (bool) – Whether the object was ‘built’
884 or ‘created’
885 · results (dict) – Map of post-generation declara‐
887 tion name to call result
888 The _after_postgeneration() is called once post-genera‐
890 tion declarations have been handled.
891 Its arguments allow to handle specifically some post-gen‐
893 eration return values, for instance.
894 Advanced functions:
896 classmethod reset_sequence(cls, value=None, force=False)
898 Parameters
900 · value (int) – The value to reset the sequence to
902 · force (bool) – Whether to force-reset the
904 sequence
905 Allows to reset the sequence counter for a Factory. The
907 new value can be passed in as the value argument:
908 >>> SomeFactory.reset_sequence(4)
910 >>> SomeFactory._next_sequence
911 4
912 Since subclasses of a non-abstract Factory share the same
914 sequence counter, special care needs to be taken when
915 resetting the counter of such a subclass.
916 By default, reset_sequence() will raise a ValueError when
918 called on a subclassed Factory subclass. This can be
919 avoided by passing in the force=True flag:
920 >>> InheritedFactory.reset_sequence()
922 Traceback (most recent call last):
923 File "factory_boy/tests/test_base.py", line 179, in test_reset_sequence_subclass_parent
924 SubTestObjectFactory.reset_sequence()
925 File "factory_boy/factory/base.py", line 250, in reset_sequence
926 "Cannot reset the sequence of a factory subclass. "
927 ValueError: Cannot reset the sequence of a factory subclass. Please call reset_sequence() on the root factory, or call reset_sequence(forward=True).
928 >>> InheritedFactory.reset_sequence(force=True)
930 >>>
931 This is equivalent to calling reset_sequence() on the
933 base factory in the chain.
934 Parameters
936 New in version 2.7.0.
937 Some models have many fields that can be summarized by a few parame‐
940 ters; for instance, a train with many cars — each complete with serial
941 number, manufacturer, …; or an order that can be pend‐
942 ing/shipped/received, with a few fields to describe each step.
943 When building instances of such models, a couple of parameters can be
945 enough to determine all other fields; this is handled by the Params
946 section of a Factory declaration.
947 Simple parameters
949 Some factories only need little data:
950 class ConferenceFactory(factory.Factory):
952 class Meta:
953 model = Conference
954 class Params:
956 duration = 'short' # Or 'long'
957 start_date = factory.fuzzy.FuzzyDate()
959 end_date = factory.LazyAttribute(
960 lambda o: o.start_date + datetime.timedelta(days=2 if o.duration == 'short' else 7)
961 )
962 sprints_start = factory.LazyAttribute(
963 lambda o: o.end_date - datetime.timedelta(days=0 if o.duration == 'short' else 1)
964 )
965 >>> Conference(duration='short')
967 <Conference: DUTH 2015 (2015-11-05 - 2015-11-08, sprints 2015-11-08)>
968 >>> Conference(duration='long')
969 <Conference: DjangoConEU 2016 (2016-03-30 - 2016-04-03, sprints 2016-04-02)>
970 Any simple parameter provided to the Factory.Params section is avail‐
972 able to the whole factory, but not passed to the final class (similar
973 to the exclude behavior).
974 Traits
976 class factory.Trait(**kwargs)
977 New in version 2.7.0.
978 A trait’s parameters are the fields it should alter when
981 enabled.
982 For more complex situations, it is helpful to override a few fields at
984 once:
985 class OrderFactory(factory.Factory):
987 class Meta:
988 model = Order
989 state = 'pending'
991 shipped_on = None
992 shipped_by = None
993 class Params:
995 shipped = factory.Trait(
996 state='shipped',
997 shipped_on=datetime.date.today(),
998 shipped_by=factory.SubFactory(EmployeeFactory),
999 )
1000 Such a Trait is activated or disabled by a single boolean field:
1002 >>> OrderFactory()
1004 <Order: pending>
1005 Order(state='pending')
1006 >>> OrderFactory(shipped=True)
1007 <Order: shipped by John Doe on 2016-04-02>
1008 A Trait can be enabled/disabled by a Factory subclass:
1010 class ShippedOrderFactory(OrderFactory):
1012 shipped = True
1013 Values set in a Trait can be overridden by call-time values:
1015 >>> OrderFactory(shipped=True, shipped_on=last_year)
1017 <Order: shipped by John Doe on 2015-04-20>
1018 Traits can be chained:
1020 class OrderFactory(factory.Factory):
1022 class Meta:
1023 model = Order
1024 # Can be pending/shipping/received
1026 state = 'pending'
1027 shipped_on = None
1028 shipped_by = None
1029 received_on = None
1030 received_by = None
1031 class Params:
1033 shipped = factory.Trait(
1034 state='shipped',
1035 shipped_on=datetime.date.today,
1036 shipped_by=factory.SubFactory(EmployeeFactory),
1037 )
1038 received = factory.Trait(
1039 shipped=True,
1040 state='received',
1041 shipped_on=datetime.date.today - datetime.timedelta(days=4),
1042 received_on=datetime.date.today,
1043 received_by=factory.SubFactory(CustomerFactory),
1044 )
1045 >>> OrderFactory(received=True)
1047 <Order: shipped by John Doe on 2016-03-20, received by Joan Smith on 2016-04-02>
1048 A Trait might be overridden in Factory subclasses:
1050 class LocalOrderFactory(OrderFactory):
1052 class Params:
1054 received = factory.Trait(
1055 shipped=True,
1056 state='received',
1057 shipped_on=datetime.date.today - datetime.timedelta(days=1),
1058 received_on=datetime.date.today,
1059 received_by=factory.SubFactory(CustomerFactory),
1060 )
1061 >>> LocalOrderFactory(received=True)
1063 <Order: shipped by John Doe on 2016-04-01, received by Joan Smith on 2016-04-02>
1064 NOTE:
1066 When overriding a Trait, the whole declaration MUST be replaced.
1067 Strategies
1069 factory_boy supports two main strategies for generating instances, plus
1070 stubs.
1071 factory.BUILD_STRATEGY
1073 The ‘build’ strategy is used when an instance should be created,
1074 but not persisted to any datastore.
1075 It is usually a simple call to the __init__() method of the
1077 model class.
1078 factory.CREATE_STRATEGY
1080 The ‘create’ strategy builds and saves an instance into its
1081 appropriate datastore.
1082 This is the default strategy of factory_boy; it would typically
1084 instantiate an object, then save it:
1085 >>> obj = self._associated_class(*args, **kwargs)
1087 >>> obj.save()
1088 >>> return obj
1089 WARNING:
1091 For backward compatibility reasons, the default behaviour of
1092 factory_boy is to call MyClass.objects.create(*args,
1093 **kwargs) when using the create strategy.
1094 That policy will be used if the associated class has an
1096 objects attribute and the _create() classmethod of the
1097 Factory wasn’t overridden.
1098 factory.use_strategy(strategy)
1100 Decorator
1101 Change the default strategy of the decorated Factory to the cho‐
1103 sen strategy:
1104 @use_strategy(factory.BUILD_STRATEGY)
1106 class UserBuildingFactory(UserFactory):
1107 pass
1108 factory.STUB_STRATEGY
1110 The ‘stub’ strategy is an exception in the factory_boy world: it
1111 doesn’t return an instance of the model class, and actually
1112 doesn’t require one to be present.
1113 Instead, it returns an instance of StubObject whose attributes
1115 have been set according to the declarations.
1116 class factory.StubObject(object)
1118 A plain, stupid object. No method, no helpers, simply a bunch of
1119 attributes.
1120 It is typically instantiated, then has its attributes set:
1122 >>> obj = StubObject()
1124 >>> obj.x = 1
1125 >>> obj.y = 2
1126 class factory.StubFactory(Factory)
1128 An abstract Factory, with a default strategy set to
1129 STUB_STRATEGY.
1130 factory.debug(logger='factory', stream=None)
1132 Parameters
1134 · logger (str) – The name of the logger to enable debug
1136 for
1137 · stream (file) – The stream to send debug output to,
1139 defaults to sys.stderr
1140 Context manager to help debugging factory_boy behavior. It will
1142 temporarily put the target logger (e.g 'factory') in debug mode,
1143 sending all output to :obj`~sys.stderr`; upon leaving the con‐
1144 text, the logging levels are reset.
1145 A typical use case is to understand what happens during a single
1147 factory call:
1148 with factory.debug():
1150 obj = TestModel2Factory()
1151 This will yield messages similar to those (artificial indenta‐
1153 tion):
1154 BaseFactory: Preparing tests.test_using.TestModel2Factory(extra={})
1156 LazyStub: Computing values for tests.test_using.TestModel2Factory(two=<OrderedDeclarationWrapper for <factory.declarations.SubFactory object at 0x1e15610>>)
1157 SubFactory: Instantiating tests.test_using.TestModelFactory(__containers=(<LazyStub for tests.test_using.TestModel2Factory>,), one=4), create=True
1158 BaseFactory: Preparing tests.test_using.TestModelFactory(extra={'__containers': (<LazyStub for tests.test_using.TestModel2Factory>,), 'one': 4})
1159 LazyStub: Computing values for tests.test_using.TestModelFactory(one=4)
1160 LazyStub: Computed values, got tests.test_using.TestModelFactory(one=4)
1161 BaseFactory: Generating tests.test_using.TestModelFactory(one=4)
1162 LazyStub: Computed values, got tests.test_using.TestModel2Factory(two=<tests.test_using.TestModel object at 0x1e15410>)
1163 BaseFactory: Generating tests.test_using.TestModel2Factory(two=<tests.test_using.TestModel object at 0x1e15410>)
1164 Declarations
1166 Faker
1167 class factory.Faker(provider, locale=None, **kwargs)
1168 In order to easily define realistic-looking factories, use the
1169 Faker attribute declaration.
1170 This is a wrapper around faker; its argument is the name of a
1172 faker provider:
1173 class UserFactory(factory.Factory):
1175 class Meta:
1176 model = User
1177 name = factory.Faker('name')
1179 >>> user = UserFactory()
1181 >>> user.name
1182 'Lucy Cechtelar'
1183 locale If a custom locale is required for one specific field,
1185 use the locale parameter:
1186 class UserFactory(factory.Factory):
1188 class Meta:
1189 model = User
1190 name = factory.Faker('name', locale='fr_FR')
1192 >>> user = UserFactory()
1194 >>> user.name
1195 'Jean Valjean'
1196 classmethod override_default_locale(cls, locale)
1198 If the locale needs to be overridden for a whole test,
1199 use override_default_locale():
1200 >>> with factory.Faker.override_default_locale('de_DE'):
1202 ... UserFactory()
1203 <User: Johannes Brahms>
1204 classmethod add_provider(cls, locale=None)
1206 Some projects may need to fake fields beyond those pro‐
1207 vided by faker; in such cases, use
1208 factory.Faker.add_provider() to declare additional
1209 providers for those fields:
1210 factory.Faker.add_provider(SmileyProvider)
1212 class FaceFactory(factory.Factory):
1214 class Meta:
1215 model = Face
1216 smiley = factory.Faker('smiley')
1218 LazyFunction
1220 class factory.LazyFunction(method_to_call)
1221 The LazyFunction is the simplest case where the value of an attribute
1223 does not depend on the object being built.
1224 It takes as argument a method to call (function, lambda…); that method
1226 should not take any argument, though keyword arguments are safe but
1227 unused, and return a value.
1228 class LogFactory(factory.Factory):
1230 class Meta:
1231 model = models.Log
1232 timestamp = factory.LazyFunction(datetime.now)
1234 >>> LogFactory()
1236 <Log: log at 2016-02-12 17:02:34>
1237 >>> # The LazyFunction can be overriden
1239 >>> LogFactory(timestamp=now - timedelta(days=1))
1240 <Log: log at 2016-02-11 17:02:34>
1241 LazyFunction is also useful for assigning copies of mutable objects
1243 (like lists) to an object’s property. Example:
1244 DEFAULT_TEAM = ['Player1', 'Player2']
1246 class TeamFactory(factory.Factory):
1248 class Meta:
1249 model = models.Team
1250 teammates = factory.LazyFunction(lambda: list(DEFAULT_TEAM))
1252 Decorator
1254 The class LazyFunction does not provide a decorator.
1255 For complex cases, use LazyAttribute.lazy_attribute() directly.
1257 LazyAttribute
1259 class factory.LazyAttribute(method_to_call)
1260 The LazyAttribute is a simple yet extremely powerful building brick for
1262 extending a Factory.
1263 It takes as argument a method to call (usually a lambda); that method
1265 should accept the object being built as sole argument, and return a
1266 value.
1267 class UserFactory(factory.Factory):
1269 class Meta:
1270 model = User
1271 username = 'john'
1273 email = factory.LazyAttribute(lambda o: '%s@example.com' % o.username)
1274 >>> u = UserFactory()
1276 >>> u.email
1277 'john@example.com'
1278 >>> u = UserFactory(username='leo')
1280 >>> u.email
1281 'leo@example.com'
1282 The object passed to LazyAttribute is not an instance of the target
1284 class, but instead a Resolver: a temporary container that computes the
1285 value of all declared fields.
1286 Decorator
1288 factory.lazy_attribute()
1289 If a simple lambda isn’t enough, you may use the lazy_attribute() deco‐
1291 rator instead.
1292 This decorates an instance method that should take a single argument,
1294 self; the name of the method will be used as the name of the attribute
1295 to fill with the return value of the method:
1296 class UserFactory(factory.Factory)
1298 class Meta:
1299 model = User
1300 name = u"Jean"
1302 @factory.lazy_attribute
1304 def email(self):
1305 # Convert to plain ascii text
1306 clean_name = (unicodedata.normalize('NFKD', self.name)
1307 .encode('ascii', 'ignore')
1308 .decode('utf8'))
1309 return u'%s@example.com' % clean_name
1310 >>> joel = UserFactory(name=u"Joël")
1312 >>> joel.email
1313 u'joel@example.com'
1314 Sequence
1316 class factory.Sequence(lambda, type=int)
1317 If a field should be unique, and thus different for all built
1319 instances, use a Sequence.
1320 This declaration takes a single argument, a function accepting a single
1322 parameter - the current sequence counter - and returning the related
1323 value.
1324 NOTE:
1326 An extra kwarg argument, type, may be provided. This feature was
1327 deprecated in 1.3.0 and will be removed in 2.0.0.
1328 class UserFactory(factory.Factory)
1330 class Meta:
1331 model = User
1332 phone = factory.Sequence(lambda n: '123-555-%04d' % n)
1334 >>> UserFactory().phone
1336 '123-555-0001'
1337 >>> UserFactory().phone
1338 '123-555-0002'
1339 Decorator
1341 factory.sequence()
1342 As with lazy_attribute(), a decorator is available for complex situa‐
1344 tions.
1345 sequence() decorates an instance method, whose self method will actu‐
1347 ally be the sequence counter - this might be confusing:
1348 class UserFactory(factory.Factory)
1350 class Meta:
1351 model = User
1352 @factory.sequence
1354 def phone(n):
1355 a = n // 10000
1356 b = n % 10000
1357 return '%03d-555-%04d' % (a, b)
1358 >>> UserFactory().phone
1360 '000-555-9999'
1361 >>> UserFactory().phone
1362 '001-555-0000'
1363 Sharing
1365 The sequence counter is shared across all Sequence attributes of the
1366 Factory:
1367 class UserFactory(factory.Factory):
1369 class Meta:
1370 model = User
1371 phone = factory.Sequence(lambda n: '%04d' % n)
1373 office = factory.Sequence(lambda n: 'A23-B%03d' % n)
1374 >>> u = UserFactory()
1376 >>> u.phone, u.office
1377 '0041', 'A23-B041'
1378 >>> u2 = UserFactory()
1379 >>> u2.phone, u2.office
1380 '0042', 'A23-B042'
1381 Inheritance
1383 When a Factory inherits from another Factory and the model of the sub‐
1384 class inherits from the model of the parent, the sequence counter is
1385 shared across the Factory classes:
1386 class UserFactory(factory.Factory):
1388 class Meta:
1389 model = User
1390 phone = factory.Sequence(lambda n: '123-555-%04d' % n)
1392 class EmployeeFactory(UserFactory):
1395 office_phone = factory.Sequence(lambda n: '%04d' % n)
1396 >>> u = UserFactory()
1398 >>> u.phone
1399 '123-555-0001'
1400 >>> e = EmployeeFactory()
1402 >>> e.phone, e.office_phone
1403 '123-555-0002', '0002'
1404 >>> u2 = UserFactory()
1406 >>> u2.phone
1407 '123-555-0003'
1408 Forcing a sequence counter
1410 If a specific value of the sequence counter is required for one
1411 instance, the __sequence keyword argument should be passed to the fac‐
1412 tory method.
1413 This will force the sequence counter during the call, without altering
1415 the class-level value.
1416 class UserFactory(factory.Factory):
1418 class Meta:
1419 model = User
1420 uid = factory.Sequence(int)
1422 >>> UserFactory()
1424 <User: 0>
1425 >>> UserFactory()
1426 <User: 1>
1427 >>> UserFactory(__sequence=42)
1428 <User: 42>
1429 WARNING:
1431 The impact of setting __sequence=n on a _batch call is undefined.
1432 Each generated instance may share a same counter, or use incremental
1433 values starting from the forced value.
1434 LazyAttributeSequence
1436 class factory.LazyAttributeSequence(method_to_call)
1437 The LazyAttributeSequence declaration merges features of Sequence and
1439 LazyAttribute.
1440 It takes a single argument, a function whose two parameters are, in
1442 order:
1443 · The object being built
1445 · The sequence counter
1447 class UserFactory(factory.Factory):
1449 class Meta:
1450 model = User
1451 login = 'john'
1453 email = factory.LazyAttributeSequence(lambda o, n: '%s@s%d.example.com' % (o.login, n))
1454 >>> UserFactory().email
1456 'john@s1.example.com'
1457 >>> UserFactory(login='jack').email
1458 'jack@s2.example.com'
1459 Decorator
1461 factory.lazy_attribute_sequence(method_to_call)
1462 As for lazy_attribute() and sequence(), the lazy_attribute_sequence()
1464 handles more complex cases:
1465 class UserFactory(factory.Factory):
1467 class Meta:
1468 model = User
1469 login = 'john'
1471 @lazy_attribute_sequence
1473 def email(self, n):
1474 bucket = n % 10
1475 return '%s@s%d.example.com' % (self.login, bucket)
1476 SubFactory
1478 class factory.SubFactory(factory, **kwargs)
1479 This attribute declaration calls another Factory subclass, selecting
1481 the same build strategy and collecting extra kwargs in the process.
1482 The SubFactory attribute should be called with:
1484 · A Factory subclass as first argument, or the fully qualified import
1486 path to that Factory (see Circular imports)
1487 · An optional set of keyword arguments that should be passed when call‐
1489 ing that factory
1490 NOTE:
1492 When passing an actual Factory for the factory argument, make sure
1493 to pass the class and not instance (i.e no () after the class):
1494 class FooFactory(factory.Factory):
1496 class Meta:
1497 model = Foo
1498 bar = factory.SubFactory(BarFactory) # Not BarFactory()
1500 Definition
1502 # A standard factory
1503 class UserFactory(factory.Factory):
1504 class Meta:
1505 model = User
1506 # Various fields
1508 first_name = 'John'
1509 last_name = factory.Sequence(lambda n: 'D%se' % ('o' * n)) # De, Doe, Dooe, Doooe, ...
1510 email = factory.LazyAttribute(lambda o: '%s.%s@example.org' % (o.first_name.lower(), o.last_name.lower()))
1511 # A factory for an object with a 'User' field
1513 class CompanyFactory(factory.Factory):
1514 class Meta:
1515 model = Company
1516 name = factory.Sequence(lambda n: 'FactoryBoyz' + 'z' * n)
1518 # Let's use our UserFactory to create that user, and override its first name.
1520 owner = factory.SubFactory(UserFactory, first_name='Jack')
1521 Calling
1523 The wrapping factory will call of the inner factory:
1524 >>> c = CompanyFactory()
1526 >>> c
1527 <Company: FactoryBoyz>
1528 # Notice that the first_name was overridden
1530 >>> c.owner
1531 <User: Jack De>
1532 >>> c.owner.email
1533 jack.de@example.org
1534 Fields of the SubFactory may be overridden from the external factory:
1536 >>> c = CompanyFactory(owner__first_name='Henry')
1538 >>> c.owner
1539 <User: Henry Doe>
1540 # Notice that the updated first_name was propagated to the email LazyAttribute.
1542 >>> c.owner.email
1543 henry.doe@example.org
1544 # It is also possible to override other fields of the SubFactory
1546 >>> c = CompanyFactory(owner__last_name='Jones')
1547 >>> c.owner
1548 <User: Henry Jones>
1549 >>> c.owner.email
1550 henry.jones@example.org
1551 Strategies
1553 The strategy chosen for the external factory will be propagated to all
1554 subfactories:
1555 >>> c = CompanyFactory()
1557 >>> c.pk # Saved to the database
1558 3
1559 >>> c.owner.pk # Saved to the database
1560 8
1561 >>> c = CompanyFactory.build()
1563 >>> c.pk # Not saved
1564 None
1565 >>> c.owner.pk # Not saved either
1566 None
1567 Circular imports
1569 Some factories may rely on each other in a circular manner. This issue
1570 can be handled by passing the absolute import path to the target
1571 Factory to the SubFactory.
1572 New in version 1.3.0.
1574 class UserFactory(factory.Factory):
1577 class Meta:
1578 model = User
1579 username = 'john'
1581 main_group = factory.SubFactory('users.factories.GroupFactory')
1582 class GroupFactory(factory.Factory):
1584 class Meta:
1585 model = Group
1586 name = "MyGroup"
1588 owner = factory.SubFactory(UserFactory)
1589 Obviously, such circular relationships require careful handling of
1591 loops:
1592 >>> owner = UserFactory(main_group=None)
1594 >>> UserFactory(main_group__owner=owner)
1595 <john (group: MyGroup)>
1596 SelfAttribute
1598 class factory.SelfAttribute(dotted_path_to_attribute)
1599 Some fields should reference another field of the object being con‐
1601 structed, or an attribute thereof.
1602 This is performed by the SelfAttribute declaration. That declaration
1604 takes a single argument, a dot-delimited path to the attribute to
1605 fetch:
1606 class UserFactory(factory.Factory):
1608 class Meta:
1609 model = User
1610 birthdate = factory.Sequence(lambda n: datetime.date(2000, 1, 1) + datetime.timedelta(days=n))
1612 birthmonth = factory.SelfAttribute('birthdate.month')
1613 >>> u = UserFactory()
1615 >>> u.birthdate
1616 date(2000, 3, 15)
1617 >>> u.birthmonth
1618 3
1619 Parents
1621 When used in conjunction with SubFactory, the SelfAttribute gains an
1622 “upward” semantic through the double-dot notation, as used in Python
1623 imports.
1624 factory.SelfAttribute('..country.language') means “Select the language
1626 of the country of the Factory calling me”.
1627 class UserFactory(factory.Factory):
1629 class Meta:
1630 model = User
1631 language = 'en'
1633 class CompanyFactory(factory.Factory):
1636 class Meta:
1637 model = Company
1638 country = factory.SubFactory(CountryFactory)
1640 owner = factory.SubFactory(UserFactory, language=factory.SelfAttribute('..country.language'))
1641 >>> company = CompanyFactory()
1643 >>> company.country.language
1644 'fr'
1645 >>> company.owner.language
1646 'fr'
1647 Obviously, this “follow parents” ability also handles overriding some
1649 attributes on call:
1650 >>> company = CompanyFactory(country=china)
1652 >>> company.owner.language
1653 'cn'
1654 This feature is also available to LazyAttribute and
1656 LazyAttributeSequence, through the factory_parent attribute of the
1657 passed-in object:
1658 class CompanyFactory(factory.Factory):
1660 class Meta:
1661 model = Company
1662 country = factory.SubFactory(CountryFactory)
1663 owner = factory.SubFactory(UserFactory,
1664 language=factory.LazyAttribute(lambda user: user.factory_parent.country.language),
1665 )
1666 Iterator
1668 class factory.Iterator(iterable, cycle=True, getter=None)
1669 The Iterator declaration takes successive values from the given
1670 iterable. When it is exhausted, it starts again from zero
1671 (unless cycle=False).
1672 cycle The cycle argument is only useful for advanced cases,
1674 where the provided iterable has no end (as wishing to
1675 cycle it means storing values in memory…).
1676 New in version 1.3.0: The cycle argument is available as
1678 of v1.3.0; previous versions had a behaviour equivalent
1679 to cycle=False.
1680 getter A custom function called on each value returned by the
1683 iterable. See the Getter section for details.
1684 New in version 1.3.0.
1686 reset()
1689 Reset the internal iterator used by the attribute, so
1690 that the next value will be the first value generated by
1691 the iterator.
1692 May be called several times.
1694 Each call to the factory will receive the next value from the iterable:
1696 class UserFactory(factory.Factory)
1698 lang = factory.Iterator(['en', 'fr', 'es', 'it', 'de'])
1699 >>> UserFactory().lang
1701 'en'
1702 >>> UserFactory().lang
1703 'fr'
1704 When a value is passed in for the argument, the iterator will not be
1706 advanced:
1707 >>> UserFactory().lang
1709 'en'
1710 >>> UserFactory(lang='cn').lang
1711 'cn'
1712 >>> UserFactory().lang
1713 'fr'
1714 Getter
1716 Some situations may reuse an existing iterable, using only some compo‐
1717 nent. This is handled by the getter attribute: this is a function that
1718 accepts as sole parameter a value from the iterable, and returns an
1719 adequate value.
1720 class UserFactory(factory.Factory):
1722 class Meta:
1723 model = User
1724 # CATEGORY_CHOICES is a list of (key, title) tuples
1726 category = factory.Iterator(User.CATEGORY_CHOICES, getter=lambda c: c[0])
1727 Decorator
1729 factory.iterator(func)
1730 When generating items of the iterator gets too complex for a simple
1732 list comprehension, use the iterator() decorator:
1733 WARNING:
1735 The decorated function takes no argument, notably no self parameter.
1736 class UserFactory(factory.Factory):
1738 class Meta:
1739 model = User
1740 @factory.iterator
1742 def name():
1743 with open('test/data/names.dat', 'r') as f:
1744 for line in f:
1745 yield line
1746 WARNING:
1748 Values from the underlying iterator are kept in memory; once the
1749 initial iterator has been emptied, saved values are used instead of
1750 executing the function instead.
1751 Use factory.Iterator(my_func, cycle=False) to disable value recy‐
1753 cling.
1754 Resetting
1756 In order to start back at the first value in an Iterator, simply call
1757 the reset() method of that attribute (accessing it from the bare
1758 Factory subclass):
1759 >>> UserFactory().lang
1761 'en'
1762 >>> UserFactory().lang
1763 'fr'
1764 >>> UserFactory.lang.reset()
1765 >>> UserFactory().lang
1766 'en'
1767 Dict and List
1769 When a factory expects lists or dicts as arguments, such values can be
1770 generated through the whole range of factory_boy declarations, with the
1771 Dict and List attributes:
1772 class factory.Dict(params[, dict_factory=factory.DictFactory])
1774 The Dict class is used for dict-like attributes. It receives as
1775 non-keyword argument a dictionary of fields to define, whose
1776 value may be any factory-enabled declarations:
1777 class UserFactory(factory.Factory):
1779 class Meta:
1780 model = User
1781 is_superuser = False
1783 roles = factory.Dict({
1784 'role1': True,
1785 'role2': False,
1786 'role3': factory.Iterator([True, False]),
1787 'admin': factory.SelfAttribute('..is_superuser'),
1788 })
1789 NOTE:
1791 Declarations used as a Dict values are evaluated within that
1792 Dict’s context; this means that you must use the ..foo syntax
1793 to access fields defined at the factory level.
1794 On the other hand, the Sequence counter is aligned on the
1796 containing factory’s one.
1797 The Dict behaviour can be tuned through the following parame‐
1799 ters:
1800 dict_factory
1802 The actual factory to use for generating the dict can be
1803 set as a keyword argument, if an exotic dictionary-like
1804 object (SortedDict, …) is required.
1805 class factory.List(items[, list_factory=factory.ListFactory])
1807 The List can be used for list-like attributes.
1808 Internally, the fields are converted into a index=value dict,
1810 which makes it possible to override some values at use time:
1811 class UserFactory(factory.Factory):
1813 class Meta:
1814 model = User
1815 flags = factory.List([
1817 'user',
1818 'active',
1819 'admin',
1820 ])
1821 >>> u = UserFactory(flags__2='superadmin')
1823 >>> u.flags
1824 ['user', 'active', 'superadmin']
1825 The List behaviour can be tuned through the following parame‐
1827 ters:
1828 list_factory
1830 The actual factory to use for generating the list can be
1831 set as a keyword argument, if another type (tuple, set,
1832 …) is required.
1833 Maybe
1835 class factory.Maybe(decider, yes_declaration, no_declaration)
1836 Sometimes, the way to build a given field depends on the value of
1838 another, for instance of a parameter.
1839 In those cases, use the Maybe declaration: it takes the name of a
1841 “decider” boolean field, and two declarations; depending on the value
1842 of the field whose name is held in the ‘decider’ parameter, it will
1843 apply the effects of one or the other declaration:
1844 class UserFactory(factory.Factory):
1846 class Meta:
1847 model = User
1848 is_active = True
1850 deactivation_date = factory.Maybe(
1851 'is_active',
1852 yes_declaration=None,
1853 no_declaration=factory.fuzzy.FuzzyDateTime(timezone.now() - datetime.timedelta(days=10)),
1854 )
1855 >>> u = UserFactory(is_active=True)
1857 >>> u.deactivation_date
1858 None
1859 >>> u = UserFactory(is_active=False)
1860 >>> u.deactivation_date
1861 datetime.datetime(2017, 4, 1, 23, 21, 23, tzinfo=UTC)
1862 NOTE:
1864 If the condition for the decider is complex, use a LazyAttribute
1865 defined in the Params section of your factory to handle the computa‐
1866 tion.
1867 Post-generation hooks
1869 Some objects expect additional method calls or complex processing for
1870 proper definition. For instance, a User may need to have a related
1871 Profile, where the Profile is built from the User object.
1872 To support this pattern, factory_boy provides the following tools:
1874 · PostGenerationMethodCall: allows you to hook a particular
1876 attribute to a function call
1877 · PostGeneration: this class allows calling a given function
1879 with the generated object as argument
1880 · post_generation(): decorator performing the same functions as
1882 PostGeneration
1883 · RelatedFactory: this builds or creates a given factory after
1885 building/creating the first Factory.
1886 Post-generation hooks are called in the same order they are declared in
1888 the factory class, so that functions can rely on the side effects
1889 applied by the previous post-generation hook.
1890 Extracting parameters
1892 All post-building hooks share a common base for picking parameters from
1893 the set of attributes passed to the Factory.
1894 For instance, a PostGeneration hook is declared as post:
1896 class SomeFactory(factory.Factory):
1898 class Meta:
1899 model = SomeObject
1900 @post_generation
1902 def post(obj, create, extracted, **kwargs):
1903 obj.set_origin(create)
1904 When calling the factory, some arguments will be extracted for this
1906 method:
1907 · If a post argument is passed, it will be passed as the extracted
1909 field
1910 · Any argument starting with post__XYZ will be extracted, its post__
1912 prefix removed, and added to the kwargs passed to the post-generation
1913 hook.
1914 Extracted arguments won’t be passed to the model class.
1916 Thus, in the following call:
1918 >>> SomeFactory(
1920 post=1,
1921 post_x=2,
1922 post__y=3,
1923 post__z__t=42,
1924 )
1925 The post hook will receive 1 as extracted and {'y': 3, 'z__t': 42} as
1927 keyword arguments; {'post_x': 2} will be passed to SomeFac‐
1928 tory._meta.model.
1929 RelatedFactory
1931 class factory.RelatedFactory(factory, factory_related_name='',
1932 **kwargs)
1933 A RelatedFactory behaves mostly like a SubFactory, with the main
1934 difference that the related Factory will be generated after the
1935 base Factory.
1936 factory
1938 As for SubFactory, the factory argument can be:
1939 · A Factory subclass
1941 · Or the fully qualified path to a Factory subclass (see
1943 Circular imports for details)
1944 name The generated object (where the RelatedFactory attribute
1946 will set) may be passed to the related factory if the
1947 factory_related_name parameter is set.
1948 It will be passed as a keyword argument, using the name
1950 value as keyword:
1951 NOTE:
1953 When passing an actual Factory for the factory argument, make sure
1954 to pass the class and not instance (i.e no () after the class):
1955 class FooFactory(factory.Factory):
1957 class Meta:
1958 model = Foo
1959 bar = factory.RelatedFactory(BarFactory) # Not BarFactory()
1961 class CityFactory(factory.Factory):
1963 class Meta:
1964 model = City
1965 capital_of = None
1967 name = "Toronto"
1968 class CountryFactory(factory.Factory):
1970 class Meta:
1971 model = Country
1972 lang = 'fr'
1974 capital_city = factory.RelatedFactory(CityFactory, 'capital_of', name="Paris")
1975 >>> france = CountryFactory()
1977 >>> City.objects.get(capital_of=france)
1978 <City: Paris>
1979 Extra kwargs may be passed to the related factory, through the usual
1981 ATTR__SUBATTR syntax:
1982 >>> england = CountryFactory(lang='en', capital_city__name="London")
1984 >>> City.objects.get(capital_of=england)
1985 <City: London>
1986 If a value is passed for the RelatedFactory attribute, this disables
1988 RelatedFactory generation:
1989 >>> france = CountryFactory()
1991 >>> paris = City.objects.get()
1992 >>> paris
1993 <City: Paris>
1994 >>> reunion = CountryFactory(capital_city=paris)
1995 >>> City.objects.count() # No new capital_city generated
1996 1
1997 >>> guyane = CountryFactory(capital_city=paris, capital_city__name='Kourou')
1998 >>> City.objects.count() # No new capital_city generated, ``name`` ignored.
1999 1
2000 NOTE:
2002 The target of the RelatedFactory is evaluated after the initial fac‐
2003 tory has been instantiated. However, the build context is passed
2004 down to that factory; this means that calls to factory.SelfAttribute
2005 can go back to the calling factorry’s context:
2006 class CountryFactory(factory.Factory):
2008 class Meta:
2009 model = Country
2010 lang = 'fr'
2012 capital_city = factory.RelatedFactory(CityFactory, 'capital_of',
2013 # Would also work with SelfAttribute('capital_of.lang')
2014 main_lang=factory.SelfAttribute('..lang'),
2015 )
2016 PostGeneration
2018 class factory.PostGeneration(callable)
2019 The PostGeneration declaration performs actions once the model object
2021 has been generated.
2022 Its sole argument is a callable, that will be called once the base
2024 object has
2025 been generated.
2026 Once the base object has been generated, the provided callable will be
2028 called as callable(obj, create, extracted, **kwargs), where:
2029 · obj is the base object previously generated
2031 · create is a boolean indicating which strategy was used
2033 · extracted is None unless a value was passed in for the PostGeneration
2035 declaration at Factory declaration time
2036 · kwargs are any extra parameters passed as attr__key=value when call‐
2038 ing the Factory:
2039 class UserFactory(factory.Factory):
2041 class Meta:
2042 model = User
2043 login = 'john'
2045 make_mbox = factory.PostGeneration(
2046 lambda obj, create, extracted, **kwargs: os.makedirs(obj.login))
2047 Decorator
2049 factory.post_generation()
2050 A decorator is also provided, decorating a single method accepting the
2052 same obj, created, extracted and keyword arguments as PostGeneration.
2053 class UserFactory(factory.Factory):
2055 class Meta:
2056 model = User
2057 login = 'john'
2059 @factory.post_generation
2061 def mbox(self, create, extracted, **kwargs):
2062 if not create:
2063 return
2064 path = extracted or os.path.join('/tmp/mbox/', self.login)
2065 os.path.makedirs(path)
2066 return path
2067 >>> UserFactory.build() # Nothing was created
2069 >>> UserFactory.create() # Creates dir /tmp/mbox/john
2070 >>> UserFactory.create(login='jack') # Creates dir /tmp/mbox/jack
2071 >>> UserFactory.create(mbox='/tmp/alt') # Creates dir /tmp/alt
2072 PostGenerationMethodCall
2074 class factory.PostGenerationMethodCall(method_name, *arg, **kwargs)
2075 The PostGenerationMethodCall declaration will call a method on
2076 the generated object just after instantiation. This declaration
2077 class provides a friendly means of generating attributes of a
2078 factory instance during initialization. The declaration is cre‐
2079 ated using the following arguments:
2080 method_name
2082 The name of the method to call on the model object
2083 arg The default, optional, positional argument to pass to the
2085 method given in method_name
2086 kwargs The default set of keyword arguments to pass to the
2088 method given in method_name
2089 Once the factory instance has been generated, the method specified in
2091 method_name will be called on the generated object with any arguments
2092 specified in the PostGenerationMethodCall declaration, by default.
2093 For example, to set a default password on a generated User instance
2095 during instantiation, we could make a declaration for a password
2096 attribute like below:
2097 class UserFactory(factory.Factory):
2099 class Meta:
2100 model = User
2101 username = 'user'
2103 password = factory.PostGenerationMethodCall('set_password',
2104 'defaultpassword')
2105 When we instantiate a user from the UserFactory, the factory will cre‐
2107 ate a password attribute by calling User.set_password('defaultpass‐
2108 word'). Thus, by default, our users will have a password set to
2109 'defaultpassword'.
2110 >>> u = UserFactory() # Calls user.set_password('defaultpassword')
2112 >>> u.check_password('defaultpassword')
2113 True
2114 If the PostGenerationMethodCall declaration contained no arguments or
2116 one argument, an overriding value can be passed directly to the method
2117 through a keyword argument matching the attribute name. For example we
2118 can override the default password specified in the declaration above by
2119 simply passing in the desired password as a keyword argument to the
2120 factory during instantiation.
2121 >>> other_u = UserFactory(password='different') # Calls user.set_password('different')
2123 >>> other_u.check_password('defaultpassword')
2124 False
2125 >>> other_u.check_password('different')
2126 True
2127 NOTE:
2129 For Django models, unless the object method called by
2130 PostGenerationMethodCall saves the object back to the database, we
2131 will have to explicitly remember to save the object back if we per‐
2132 formed a create().
2133 >>> u = UserFactory.create() # u.password has not been saved back to the database
2135 >>> u.save() # we must remember to do it ourselves
2136 We can avoid this by subclassing from DjangoModelFactory, instead,
2138 e.g.,
2139 class UserFactory(factory.django.DjangoModelFactory):
2141 class Meta:
2142 model = User
2143 username = 'user'
2145 password = factory.PostGenerationMethodCall('set_password',
2146 'defaultpassword')
2147 WARNING:
2149 In order to keep a consistent and simple API, a
2150 PostGenerationMethodCall allows at most one positional argument; all
2151 other parameters should be passed as keyword arguments.
2152 Keywords extracted from the factory arguments are merged into the
2154 defaults present in the PostGenerationMethodCall declaration.
2155 >>> UserFactory(password__disabled=True) # Calls user.set_password('', 'sha1', disabled=True)
2157 Module-level functions
2159 Beyond the Factory class and the various Declarations classes and meth‐
2160 ods, factory_boy exposes a few module-level functions, mostly useful
2161 for lightweight factory generation.
2162 Lightweight factory declaration
2164 factory.make_factory(klass, **kwargs)
2165 The make_factory() function takes a class, declarations as key‐
2166 word arguments, and generates a new Factory for that class
2167 accordingly:
2168 UserFactory = make_factory(User,
2170 login='john',
2171 email=factory.LazyAttribute(lambda u: '%s@example.com' % u.login),
2172 )
2173 # This is equivalent to:
2175 class UserFactory(factory.Factory):
2177 class Meta:
2178 model = User
2179 login = 'john'
2181 email = factory.LazyAttribute(lambda u: '%s@example.com' % u.login)
2182 An alternate base class to Factory can be specified in the FAC‐
2184 TORY_CLASS argument:
2185 UserFactory = make_factory(models.User,
2187 login='john',
2188 email=factory.LazyAttribute(lambda u: '%s@example.com' % u.login),
2189 FACTORY_CLASS=factory.django.DjangoModelFactory,
2190 )
2191 # This is equivalent to:
2193 class UserFactory(factory.django.DjangoModelFactory):
2195 class Meta:
2196 model = models.User
2197 login = 'john'
2199 email = factory.LazyAttribute(lambda u: '%s@example.com' % u.login)
2200 New in version 2.0.0: The FACTORY_CLASS kwarg was added in
2202 2.0.0.
2203 Instance building
2206 The factory module provides a bunch of shortcuts for creating a factory
2207 and extracting instances from them:
2208 factory.build(klass, FACTORY_CLASS=None, **kwargs)
2210 factory.build_batch(klass, size, FACTORY_CLASS=None, **kwargs)
2212 Create a factory for klass using declarations passed in kwargs;
2213 return an instance built from that factory, or a list of size
2214 instances (for build_batch()).
2215 Parameters
2217 · klass (class) – Class of the instance to build
2219 · size (int) – Number of instances to build
2221 · kwargs – Declarations to use for the generated factory
2223 · FACTORY_CLASS – Alternate base class (instead of
2225 Factory)
2226 factory.create(klass, FACTORY_CLASS=None, **kwargs)
2228 factory.create_batch(klass, size, FACTORY_CLASS=None, **kwargs)
2230 Create a factory for klass using declarations passed in kwargs;
2231 return an instance created from that factory, or a list of size
2232 instances (for create_batch()).
2233 Parameters
2235 · klass (class) – Class of the instance to create
2237 · size (int) – Number of instances to create
2239 · kwargs – Declarations to use for the generated factory
2241 · FACTORY_CLASS – Alternate base class (instead of
2243 Factory)
2244 factory.stub(klass, FACTORY_CLASS=None, **kwargs)
2246 factory.stub_batch(klass, size, FACTORY_CLASS=None, **kwargs)
2248 Create a factory for klass using declarations passed in kwargs;
2249 return an instance stubbed from that factory, or a list of size
2250 instances (for stub_batch()).
2251 Parameters
2253 · klass (class) – Class of the instance to stub
2255 · size (int) – Number of instances to stub
2257 · kwargs – Declarations to use for the generated factory
2259 · FACTORY_CLASS – Alternate base class (instead of
2261 Factory)
2262 factory.generate(klass, strategy, FACTORY_CLASS=None, **kwargs)
2264 factory.generate_batch(klass, strategy, size, FACTORY_CLASS=None,
2266 **kwargs)
2267 Create a factory for klass using declarations passed in kwargs;
2268 return an instance generated from that factory with the strategy
2269 strategy, or a list of size instances (for generate_batch()).
2270 Parameters
2272 · klass (class) – Class of the instance to generate
2274 · strategy (str) – The strategy to use
2276 · size (int) – Number of instances to generate
2278 · kwargs – Declarations to use for the generated factory
2280 · FACTORY_CLASS – Alternate base class (instead of
2282 Factory)
2283 factory.simple_generate(klass, create, FACTORY_CLASS=None, **kwargs)
2285 factory.simple_generate_batch(klass, create, size, FACTORY_CLASS=None,
2287 **kwargs)
2288 Create a factory for klass using declarations passed in kwargs;
2289 return an instance generated from that factory according to the
2290 create flag, or a list of size instances (for
2291 simple_generate_batch()).
2292 Parameters
2294 · klass (class) – Class of the instance to generate
2296 · create (bool) – Whether to build (False) or create
2298 (True) instances
2299 · size (int) – Number of instances to generate
2301 · kwargs – Declarations to use for the generated factory
2303 · FACTORY_CLASS – Alternate base class (instead of
2305 Factory)
2306 Using factory_boy with ORMs
2308 factory_boy provides custom Factory subclasses for various ORMs, adding
2309 dedicated features.
2310 Django
2312 The first versions of factory_boy were designed specifically for
2313 Django, but the library has now evolved to be framework-independent.
2314 Most features should thus feel quite familiar to Django users.
2316 The DjangoModelFactory subclass
2318 All factories for a Django Model should use the DjangoModelFactory base
2319 class.
2320 class factory.django.DjangoModelFactory(factory.Factory)
2322 Dedicated class for Django Model factories.
2323 This class provides the following features:
2325 · The model attribute also supports the 'app.Model' syntax
2327 · create() uses Model.objects.create()
2329 · When using RelatedFactory or PostGeneration attributes, the
2331 base object will be saved once all post-generation hooks have
2332 run.
2333 NOTE:
2335 With Django versions 1.8.0 to 1.8.3, it was no longer possible to
2336 call .build() on a factory if this factory used a SubFactory point‐
2337 ing to another model: Django refused to set a ForeignKey to an
2338 unsaved Model instance.
2339 See https://code.djangoproject.com/ticket/10811 and
2341 https://code.djangoproject.com/ticket/25160 for details.
2342 class factory.django.DjangoOptions(factory.base.FactoryOptions)
2344 The class Meta on a DjangoModelFactory supports extra parame‐
2345 ters:
2346 database
2348 New in version 2.5.0.
2349 All queries to the related model will be routed to the
2352 given database. It defaults to 'default'.
2353 django_get_or_create
2355 New in version 2.4.0.
2356 Fields whose name are passed in this list will be used to
2359 perform a Model.objects.get_or_create() instead of the
2360 usual Model.objects.create():
2361 class UserFactory(factory.django.DjangoModelFactory):
2363 class Meta:
2364 model = 'myapp.User' # Equivalent to ``model = myapp.models.User``
2365 django_get_or_create = ('username',)
2366 username = 'john'
2368 >>> User.objects.all()
2370 []
2371 >>> UserFactory() # Creates a new user
2372 <User: john>
2373 >>> User.objects.all()
2374 [<User: john>]
2375 >>> UserFactory() # Fetches the existing user
2377 <User: john>
2378 >>> User.objects.all() # No new user!
2379 [<User: john>]
2380 >>> UserFactory(username='jack') # Creates another user
2382 <User: jack>
2383 >>> User.objects.all()
2384 [<User: john>, <User: jack>]
2385 Extra fields
2387 class factory.django.FileField
2388 Custom declarations for django.db.models.FileField
2389 __init__(self, from_path='', from_file='', data=b'', file‐
2391 name='example.dat')
2392 Parameters
2394 · from_path (str) – Use data from the file located
2396 at from_path, and keep its filename
2397 · from_file (file) – Use the contents of the pro‐
2399 vided file object; use its filename if avail‐
2400 able, unless filename is also provided.
2401 · from_func (func) – Use function that returns a
2403 file object
2404 · data (bytes) – Use the provided bytes as file
2406 contents
2407 · filename (str) – The filename for the FileField
2409 NOTE:
2411 If the value None was passed for the FileField field, this will dis‐
2412 able field generation:
2413 class MyFactory(factory.django.DjangoModelFactory):
2415 class Meta:
2416 model = models.MyModel
2417 the_file = factory.django.FileField(filename='the_file.dat')
2419 >>> MyFactory(the_file__data=b'uhuh').the_file.read()
2421 b'uhuh'
2422 >>> MyFactory(the_file=None).the_file
2423 None
2424 class factory.django.ImageField
2426 Custom declarations for django.db.models.ImageField
2427 __init__(self, from_path='', from_file='', filename='exam‐
2429 ple.jpg', width=100, height=100, color='green', format='JPEG')
2430 Parameters
2432 · from_path (str) – Use data from the file located
2434 at from_path, and keep its filename
2435 · from_file (file) – Use the contents of the pro‐
2437 vided file object; use its filename if available
2438 · from_func (func) – Use function that returns a
2440 file object
2441 · filename (str) – The filename for the ImageField
2443 · width (int) – The width of the generated image
2445 (default: 100)
2446 · height (int) – The height of the generated image
2448 (default: 100)
2449 · color (str) – The color of the generated image
2451 (default: 'green')
2452 · format (str) – The image format (as supported by
2454 PIL) (default: 'JPEG')
2455 NOTE:
2457 If the value None was passed for the FileField field, this will dis‐
2458 able field generation:
2459 NOTE:
2461 Just as Django’s django.db.models.ImageField requires the Python
2462 Imaging Library, this ImageField requires it too.
2463 class MyFactory(factory.django.DjangoModelFactory):
2465 class Meta:
2466 model = models.MyModel
2467 the_image = factory.django.ImageField(color='blue')
2469 >>> MyFactory(the_image__width=42).the_image.width
2471 42
2472 >>> MyFactory(the_image=None).the_image
2473 None
2474 Disabling signals
2476 Signals are often used to plug some custom code into external compo‐
2477 nents code; for instance to create Profile objects on-the-fly when a
2478 new User object is saved.
2479 This may interfere with finely tuned factories, which would create both
2481 using RelatedFactory.
2482 To work around this problem, use the mute_signals() decorator/context
2484 manager:
2485 factory.django.mute_signals(signal1, ...)
2487 Disable the list of selected signals when calling the factory,
2488 and reactivate them upon leaving.
2489 # foo/factories.py
2491 import factory
2493 import factory.django
2494 from . import models
2496 from . import signals
2497 @factory.django.mute_signals(signals.pre_save, signals.post_save)
2499 class FooFactory(factory.django.DjangoModelFactory):
2500 class Meta:
2501 model = models.Foo
2502 # ...
2504 def make_chain():
2506 with factory.django.mute_signals(signals.pre_save, signals.post_save):
2507 # pre_save/post_save won't be called here.
2508 return SomeFactory(), SomeOtherFactory()
2509 Mogo
2511 factory_boy supports Mogo-style models, through the MogoFactory class.
2512 Mogo is a wrapper around the pymongo library for MongoDB.
2514 class factory.mogo.MogoFactory(factory.Factory)
2516 Dedicated class for Mogo models.
2517 This class provides the following features:
2519 · build() calls a model’s new() method
2521 · create() builds an instance through new() then saves it.
2523 MongoEngine
2525 factory_boy supports MongoEngine-style models, through the
2526 MongoEngineFactory class.
2527 mongoengine is a wrapper around the pymongo library for MongoDB.
2529 class factory.mongoengine.MongoEngineFactory(factory.Factory)
2531 Dedicated class for MongoEngine models.
2532 This class provides the following features:
2534 · build() calls a model’s __init__ method
2536 · create() builds an instance through __init__ then saves it.
2538 NOTE:
2540 If the associated class <factory.FactoryOptions.model is a
2541 mongoengine.EmbeddedDocument, the create() function won’t
2542 “save” it, since this wouldn’t make sense.
2543 This feature makes it possible to use SubFactory to create
2545 embedded document.
2546 A minimalist example:
2548 import mongoengine
2550 class Address(mongoengine.EmbeddedDocument):
2552 street = mongoengine.StringField()
2553 class Person(mongoengine.Document):
2555 name = mongoengine.StringField()
2556 address = mongoengine.EmbeddedDocumentField(Address)
2557 import factory
2559 class AddressFactory(factory.mongoengine.MongoEngineFactory):
2561 class Meta:
2562 model = Address
2563 street = factory.Sequence(lambda n: 'street%d' % n)
2565 class PersonFactory(factory.mongoengine.MongoEngineFactory):
2567 class Meta:
2568 model = Person
2569 name = factory.Sequence(lambda n: 'name%d' % n)
2571 address = factory.SubFactory(AddressFactory)
2572 SQLAlchemy
2574 Factoy_boy also supports SQLAlchemy models through the
2575 SQLAlchemyModelFactory class.
2576 To work, this class needs an SQLAlchemy session object affected to the
2578 Meta.sqlalchemy_session attribute.
2579 class factory.alchemy.SQLAlchemyModelFactory(factory.Factory)
2581 Dedicated class for SQLAlchemy models.
2582 This class provides the following features:
2584 · create() uses sqlalchemy.orm.session.Session.add()
2586 class factory.alchemy.SQLAlchemyOptions(factory.base.FactoryOptions)
2588 In addition to the usual parameters available in class Meta, a
2589 SQLAlchemyModelFactory also supports the following settings:
2590 sqlalchemy_session
2592 SQLAlchemy session to use to communicate with the data‐
2593 base when creating an object through this
2594 SQLAlchemyModelFactory.
2595 sqlalchemy_session_persistence
2597 Control the action taken by sqlalchemy session at the end
2598 of a create call.
2599 Valid values are:
2601 · None: do nothing
2603 · 'flush': perform a session flush()
2605 · 'commit': perform a session commit()
2607 The default value is None.
2609 If force_flush is set to True, it overrides this option.
2611 force_flush
2613 Force a session flush() at the end of _create().
2614 NOTE:
2616 This option is deprecated. Use sqlalchemy_session_per‐
2617 sistence instead.
2618 A (very) simple example:
2620 from sqlalchemy import Column, Integer, Unicode, create_engine
2622 from sqlalchemy.ext.declarative import declarative_base
2623 from sqlalchemy.orm import scoped_session, sessionmaker
2624 engine = create_engine('sqlite://')
2626 session = scoped_session(sessionmaker(bind=engine))
2627 Base = declarative_base()
2628 class User(Base):
2631 """ A SQLAlchemy simple model class who represents a user """
2632 __tablename__ = 'UserTable'
2633 id = Column(Integer(), primary_key=True)
2635 name = Column(Unicode(20))
2636 Base.metadata.create_all(engine)
2638 import factory
2640 class UserFactory(factory.alchemy.SQLAlchemyModelFactory):
2642 class Meta:
2643 model = User
2644 sqlalchemy_session = session # the SQLAlchemy session object
2645 id = factory.Sequence(lambda n: n)
2647 name = factory.Sequence(lambda n: u'User %d' % n)
2648 >>> session.query(User).all()
2650 []
2651 >>> UserFactory()
2652 <User: User 1>
2653 >>> session.query(User).all()
2654 [<User: User 1>]
2655 Managing sessions
2657 Since SQLAlchemy is a general purpose library, there is no “global”
2658 session management system.
2659 The most common pattern when working with unit tests and factory_boy is
2661 to use SQLAlchemy’s sqlalchemy.orm.scoping.scoped_session:
2662 · The test runner configures some project-wide scoped_session
2664 · Each SQLAlchemyModelFactory subclass uses this scoped_session as its
2666 sqlalchemy_session
2667 · The tearDown() method of tests calls Session.remove to reset the ses‐
2669 sion.
2670 NOTE:
2672 See the excellent SQLAlchemy guide on scoped_session for details of
2673 scoped_session’s usage.
2674 The basic idea is that declarative parts of the code (including fac‐
2676 tories) need a simple way to access the “current session”, but that
2677 session will only be created and configured at a later point.
2678 The scoped_session handles this, by virtue of only creating the ses‐
2680 sion when a query is sent to the database.
2681 Here is an example layout:
2683 · A global (test-only?) file holds the scoped_session:
2685 # myprojet/test/common.py
2687 from sqlalchemy import orm
2689 Session = orm.scoped_session(orm.sessionmaker())
2690 · All factory access it:
2692 # myproject/factories.py
2694 import factory
2696 import factory.alchemy
2697 from . import models
2699 from .test import common
2700 class UserFactory(factory.alchemy.SQLAlchemyModelFactory):
2702 class Meta:
2703 model = models.User
2704 # Use the not-so-global scoped_session
2706 # Warning: DO NOT USE common.Session()!
2707 sqlalchemy_session = common.Session
2708 name = factory.Sequence(lambda n: "User %d" % n)
2710 · The test runner configures the scoped_session when it starts:
2712 # myproject/test/runtests.py
2714 import sqlalchemy
2716 from . import common
2718 def runtests():
2720 engine = sqlalchemy.create_engine('sqlite://')
2721 # It's a scoped_session, and now is the time to configure it.
2723 common.Session.configure(bind=engine)
2724 run_the_tests
2726 · test cases use this scoped_session, and clear it after each test (for
2728 isolation):
2729 # myproject/test/test_stuff.py
2731 import unittest
2733 from . import common
2735 class MyTest(unittest.TestCase):
2737 def setUp(self):
2739 # Prepare a new, clean session
2740 self.session = common.Session()
2741 def test_something(self):
2743 u = factories.UserFactory()
2744 self.assertEqual([u], self.session.query(User).all())
2745 def tearDown(self):
2747 # Rollback the session => no changes to the database
2748 self.session.rollback()
2749 # Remove it, so that the next test gets a new Session()
2750 common.Session.remove()
2751 Common recipes
2753 NOTE:
2754 Most recipes below take on Django model examples, but can also be
2755 used on their own.
2756 Dependent objects (ForeignKey)
2758 When one attribute is actually a complex field (e.g a ForeignKey to
2759 another Model), use the SubFactory declaration:
2760 # models.py
2762 class User(models.Model):
2763 first_name = models.CharField()
2764 group = models.ForeignKey(Group)
2765 # factories.py
2768 import factory
2769 from . import models
2770 class UserFactory(factory.django.DjangoModelFactory):
2772 class Meta:
2773 model = models.User
2774 first_name = factory.Sequence(lambda n: "Agent %03d" % n)
2776 group = factory.SubFactory(GroupFactory)
2777 Choosing from a populated table
2779 If the target of the ForeignKey should be chosen from a pre-populated
2780 table (e.g django.contrib.contenttypes.models.ContentType), simply use
2781 a factory.Iterator on the chosen queryset:
2782 import factory, factory.django
2784 from . import models
2785 class UserFactory(factory.django.DjangoModelFactory):
2787 class Meta:
2788 model = models.User
2789 language = factory.Iterator(models.Language.objects.all())
2791 Here, models.Language.objects.all() won’t be evaluated until the first
2793 call to UserFactory; thus avoiding DB queries at import time.
2794 Reverse dependencies (reverse ForeignKey)
2796 When a related object should be created upon object creation (e.g a
2797 reverse ForeignKey from another Model), use a RelatedFactory declara‐
2798 tion:
2799 # models.py
2801 class User(models.Model):
2802 pass
2803 class UserLog(models.Model):
2805 user = models.ForeignKey(User)
2806 action = models.CharField()
2807 # factories.py
2810 class UserFactory(factory.django.DjangoModelFactory):
2811 class Meta:
2812 model = models.User
2813 log = factory.RelatedFactory(UserLogFactory, 'user', action=models.UserLog.ACTION_CREATE)
2815 When a UserFactory is instantiated, factory_boy will call UserLogFac‐
2817 tory(user=that_user, action=...) just before returning the created
2818 User.
2819 Example: Django’s Profile
2821 Django (<1.5) provided a mechanism to attach a Profile to a User
2822 instance, using a OneToOneField from the Profile to the User.
2823 A typical way to create those profiles was to hook a post-save signal
2825 to the User model.
2826 Prior to version 2.9, the solution to this was to override the _gener‐
2828 ate() method on the factory.
2829 Since version 2.9, the mute_signals() decorator should be used:
2831 @factory.django.mute_signals(post_save)
2833 class ProfileFactory(factory.django.DjangoModelFactory):
2834 class Meta:
2835 model = my_models.Profile
2836 title = 'Dr'
2838 # We pass in profile=None to prevent UserFactory from creating another profile
2839 # (this disables the RelatedFactory)
2840 user = factory.SubFactory('app.factories.UserFactory', profile=None)
2841 @factory.django.mute_signals(post_save)
2843 class UserFactory(factory.django.DjangoModelFactory):
2844 class Meta:
2845 model = auth_models.User
2846 username = factory.Sequence(lambda n: "user_%d" % n)
2848 # We pass in 'user' to link the generated Profile to our just-generated User
2850 # This will call ProfileFactory(user=our_new_user), thus skipping the SubFactory.
2851 profile = factory.RelatedFactory(ProfileFactory, 'user')
2852 >>> u = UserFactory(profile__title=u"Lord")
2854 >>> u.get_profile().title
2855 u"Lord"
2856 Such behaviour can be extended to other situations where a signal
2858 interferes with factory_boy related factories.
2859 Any factories that call these classes with SubFactory will also need to
2861 be decorated in the same manner.
2862 NOTE:
2864 When any RelatedFactory or post_generation attribute is defined on
2865 the DjangoModelFactory subclass, a second save() is performed after
2866 the call to _create().
2867 Code working with signals should thus use the mute_signals() decora‐
2869 tor
2870 Simple Many-to-many relationship
2872 Building the adequate link between two models depends heavily on the
2873 use case; factory_boy doesn’t provide a “all in one tools” as for Sub‐
2874 Factory or RelatedFactory, users will have to craft their own depending
2875 on the model.
2876 The base building block for this feature is the post_generation hook:
2878 # models.py
2880 class Group(models.Model):
2881 name = models.CharField()
2882 class User(models.Model):
2884 name = models.CharField()
2885 groups = models.ManyToManyField(Group)
2886 # factories.py
2889 class GroupFactory(factory.django.DjangoModelFactory):
2890 class Meta:
2891 model = models.Group
2892 name = factory.Sequence(lambda n: "Group #%s" % n)
2894 class UserFactory(factory.django.DjangoModelFactory):
2896 class Meta:
2897 model = models.User
2898 name = "John Doe"
2900 @factory.post_generation
2902 def groups(self, create, extracted, **kwargs):
2903 if not create:
2904 # Simple build, do nothing.
2905 return
2906 if extracted:
2908 # A list of groups were passed in, use them
2909 for group in extracted:
2910 self.groups.add(group)
2911 When calling UserFactory() or UserFactory.build(), no group binding
2913 will be created.
2914 But when UserFactory.create(groups=(group1, group2, group3)) is called,
2916 the groups declaration will add passed in groups to the set of groups
2917 for the user.
2918 Many-to-many relation with a ‘through’
2920 If only one link is required, this can be simply performed with a
2921 RelatedFactory. If more links are needed, simply add more RelatedFac‐
2922 tory declarations:
2923 # models.py
2925 class User(models.Model):
2926 name = models.CharField()
2927 class Group(models.Model):
2929 name = models.CharField()
2930 members = models.ManyToManyField(User, through='GroupLevel')
2931 class GroupLevel(models.Model):
2933 user = models.ForeignKey(User)
2934 group = models.ForeignKey(Group)
2935 rank = models.IntegerField()
2936 # factories.py
2939 class UserFactory(factory.django.DjangoModelFactory):
2940 class Meta:
2941 model = models.User
2942 name = "John Doe"
2944 class GroupFactory(factory.django.DjangoModelFactory):
2946 class Meta:
2947 model = models.Group
2948 name = "Admins"
2950 class GroupLevelFactory(factory.django.DjangoModelFactory):
2952 class Meta:
2953 model = models.GroupLevel
2954 user = factory.SubFactory(UserFactory)
2956 group = factory.SubFactory(GroupFactory)
2957 rank = 1
2958 class UserWithGroupFactory(UserFactory):
2960 membership = factory.RelatedFactory(GroupLevelFactory, 'user')
2961 class UserWith2GroupsFactory(UserFactory):
2963 membership1 = factory.RelatedFactory(GroupLevelFactory, 'user', group__name='Group1')
2964 membership2 = factory.RelatedFactory(GroupLevelFactory, 'user', group__name='Group2')
2965 Whenever the UserWithGroupFactory is called, it will, as a post-genera‐
2967 tion hook, call the GroupLevelFactory, passing the generated user as a
2968 user field:
2969 1. UserWithGroupFactory() generates a User instance, obj
2971 2. It calls GroupLevelFactory(user=obj)
2973 3. It returns obj
2975 When using the UserWith2GroupsFactory, that behavior becomes:
2977 1. UserWith2GroupsFactory() generates a User instance, obj
2979 2. It calls GroupLevelFactory(user=obj, group__name='Group1')
2981 3. It calls GroupLevelFactory(user=obj, group__name='Group2')
2983 4. It returns obj
2985 Copying fields to a SubFactory
2987 When a field of a related class should match one of the container:
2988 # models.py
2990 class Country(models.Model):
2991 name = models.CharField()
2992 lang = models.CharField()
2993 class User(models.Model):
2995 name = models.CharField()
2996 lang = models.CharField()
2997 country = models.ForeignKey(Country)
2998 class Company(models.Model):
3000 name = models.CharField()
3001 owner = models.ForeignKey(User)
3002 country = models.ForeignKey(Country)
3003 Here, we want:
3005 · The User to have the lang of its country (factory.SelfAt‐
3007 tribute('country.lang'))
3008 · The Company owner to live in the country of the company (fac‐
3010 tory.SelfAttribute('..country'))
3011 # factories.py
3013 class CountryFactory(factory.django.DjangoModelFactory):
3014 class Meta:
3015 model = models.Country
3016 name = factory.Iterator(["France", "Italy", "Spain"])
3018 lang = factory.Iterator(['fr', 'it', 'es'])
3019 class UserFactory(factory.django.DjangoModelFactory):
3021 class Meta:
3022 model = models.User
3023 name = "John"
3025 lang = factory.SelfAttribute('country.lang')
3026 country = factory.SubFactory(CountryFactory)
3027 class CompanyFactory(factory.django.DjangoModelFactory):
3029 class Meta:
3030 model = models.Company
3031 name = "ACME, Inc."
3033 country = factory.SubFactory(CountryFactory)
3034 owner = factory.SubFactory(UserFactory, country=factory.SelfAttribute('..country'))
3035 If the value of a field on the child factory is indirectly derived from
3037 a field on the parent factory, you will need to use LazyAttribute and
3038 poke the “factory_parent” attribute.
3039 This time, we want the company owner to live in a country neighboring
3041 the country of the company:
3042 class CompanyFactory(factory.django.DjangoModelFactory):
3044 class Meta:
3045 model = models.Company
3046 name = "ACME, Inc."
3048 country = factory.SubFactory(CountryFactory)
3049 owner = factory.SubFactory(UserFactory,
3050 country=factory.LazyAttribute(lambda o: get_random_neighbor(o.factory_parent.country)))
3051 Custom manager methods
3053 Sometimes you need a factory to call a specific manager method other
3054 then the default Model.objects.create() method:
3055 class UserFactory(factory.DjangoModelFactory):
3057 class Meta:
3058 model = UserenaSignup
3059 username = "l7d8s"
3061 email = "my_name@example.com"
3062 password = "my_password"
3063 @classmethod
3065 def _create(cls, model_class, *args, **kwargs):
3066 """Override the default ``_create`` with our custom call."""
3067 manager = cls._get_manager(model_class)
3068 # The default would use ``manager.create(*args, **kwargs)``
3069 return manager.create_user(*args, **kwargs)
3070 Forcing the sequence counter
3072 A common pattern with factory_boy is to use a factory.Sequence declara‐
3073 tion to provide varying values to attributes declared as unique.
3074 However, it is sometimes useful to force a given value to the counter,
3076 for instance to ensure that tests are properly reproductible.
3077 factory_boy provides a few hooks for this:
3079 Forcing the value on a per-call basis
3081 In order to force the counter for a specific Factory instantia‐
3082 tion, just pass the value in the __sequence=42 parameter:
3083 class AccountFactory(factory.Factory):
3085 class Meta:
3086 model = Account
3087 uid = factory.Sequence(lambda n: n)
3088 name = "Test"
3089 >>> obj1 = AccountFactory(name="John Doe", __sequence=10)
3091 >>> obj1.uid # Taken from the __sequence counter
3092 10
3093 >>> obj2 = AccountFactory(name="Jane Doe")
3094 >>> obj2.uid # The base sequence counter hasn't changed
3095 1
3096 Resetting the counter globally
3098 If all calls for a factory must start from a deterministic num‐
3099 ber, use factory.Factory.reset_sequence(); this will reset the
3100 counter to its initial value (as defined by factory.Fac‐
3101 tory._setup_next_sequence()).
3102 >>> AccountFactory().uid
3104 1
3105 >>> AccountFactory().uid
3106 2
3107 >>> AccountFactory.reset_sequence()
3108 >>> AccountFactory().uid # Reset to the initial value
3109 1
3110 >>> AccountFactory().uid
3111 2
3112 It is also possible to reset the counter to a specific value:
3114 >>> AccountFactory.reset_sequence(10)
3116 >>> AccountFactory().uid
3117 10
3118 >>> AccountFactory().uid
3119 11
3120 This recipe is most useful in a TestCase’s setUp() method.
3122 Forcing the initial value for all projects
3124 The sequence counter of a Factory can also be set automatically
3125 upon the first call through the _setup_next_sequence() method;
3126 this helps when the objects’s attributes mustn’t conflict with
3127 pre-existing data.
3128 A typical example is to ensure that running a Python script
3130 twice will create non-conflicting objects, by setting up the
3131 counter to “max used value plus one”:
3132 class AccountFactory(factory.django.DjangoModelFactory):
3134 class Meta:
3135 model = models.Account
3136 @classmethod
3138 def _setup_next_sequence(cls):
3139 try:
3140 return models.Accounts.objects.latest('uid').uid + 1
3141 except models.Account.DoesNotExist:
3142 return 1
3143 >>> Account.objects.create(uid=42, name="Blah")
3145 >>> AccountFactory.create() # Sets up the account number based on the latest uid
3146 <Account uid=43, name=Test>
3147 Converting a factory’s output to a dict
3149 In order to inject some data to, say, a REST API, it can be useful to
3150 fetch the factory’s data as a dict.
3151 Internally, a factory will:
3153 1. Merge declarations and overrides from all sources (class definition,
3155 call parameters, …)
3156 2. Resolve them into a dict
3158 3. Pass that dict as keyword arguments to the model’s build / create
3160 function
3161 In order to get a dict, we’ll just have to swap the model; the easiest
3163 way is to use factory.build():
3164 class UserFactory(factory.django.DjangoModelFactory):
3166 class Meta:
3167 model = models.User
3168 first_name = factory.Sequence(lambda n: "Agent %03d" % n)
3170 username = factory.Faker('username')
3171 >>> factory.build(dict, FACTORY_CLASS=UserFactory)
3173 {'first_name': "Agent 001", 'username': 'john_doe'}
3174 Django models with GenericForeignKeys
3176 For model which uses GenericForeignKey
3177 from __future__ import unicode_literals
3179 from django.db import models
3181 from django.contrib.contenttypes.models import ContentType
3182 from django.contrib.contenttypes.fields import GenericForeignKey
3183 class TaggedItem(models.Model):
3186 """Example GenericForeinKey model from django docs"""
3187 tag = models.SlugField()
3188 content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE)
3189 object_id = models.PositiveIntegerField()
3190 content_object = GenericForeignKey('content_type', 'object_id')
3191 def __str__(self): # __unicode__ on Python 2
3193 return self.tag
3194 We can create factories like this:
3198 import factory
3200 from django.contrib.auth.models import User, Group
3201 from django.contrib.contenttypes.models import ContentType
3202 from .models import TaggedItem
3204 class UserFactory(factory.DjangoModelFactory):
3207 first_name = 'Adam'
3208 class Meta:
3210 model = User
3211 class GroupFactory(factory.DjangoModelFactory):
3214 name = 'group'
3215 class Meta:
3217 model = Group
3218 class TaggedItemFactory(factory.DjangoModelFactory):
3221 object_id = factory.SelfAttribute('content_object.id')
3222 content_type = factory.LazyAttribute(
3223 lambda o: ContentType.objects.get_for_model(o.content_object))
3224 class Meta:
3226 exclude = ['content_object']
3227 abstract = True
3228 class TaggedUserFactory(TaggedItemFactory):
3231 content_object = factory.SubFactory(UserFactory)
3232 class Meta:
3234 model = TaggedItem
3235 class TaggedGroupFactory(TaggedItemFactory):
3238 content_object = factory.SubFactory(GroupFactory)
3239 class Meta:
3241 model = TaggedItem
3242 Fuzzy attributes
3245 NOTE:
3246 Now that FactoryBoy includes the factory.Faker class, most of these
3247 built-in fuzzers are deprecated in favor of their Faker equivalents.
3248 Further discussion here:
3249 https://github.com/FactoryBoy/factory_boy/issues/271/
3250 Some tests may be interested in testing with fuzzy, random values.
3252 This is handled by the factory.fuzzy module, which provides a few ran‐
3254 dom declarations.
3255 NOTE:
3257 Use import factory.fuzzy to load this module.
3258 FuzzyAttribute
3260 class factory.fuzzy.FuzzyAttribute
3261 The FuzzyAttribute uses an arbitrary callable as fuzzer. It is
3262 expected that successive calls of that function return various
3263 values.
3264 fuzzer The callable that generates random values
3266 FuzzyText
3268 class factory.fuzzy.FuzzyText(length=12, chars=string.ascii_letters,
3269 prefix='')
3270 The FuzzyText fuzzer yields random strings beginning with the
3271 given prefix, followed by length charactes chosen from the chars
3272 character set, and ending with the given suffix.
3273 length int, the length of the random part
3275 prefix text, an optional prefix to prepend to the random part
3277 suffix text, an optional suffix to append to the random part
3279 chars
3281 char iterable, the chars to choose from; defaults to the
3283 list of ascii
3284 letters and numbers.
3285 FuzzyChoice
3287 class factory.fuzzy.FuzzyChoice(choices)
3288 The FuzzyChoice fuzzer yields random choices from the given
3289 iterable.
3290 NOTE:
3292 The passed in choices will be converted into a list upon
3293 first use, not at declaration time.
3294 This allows passing in, for instance, a Django queryset that
3296 will only hit the database during the database, not at import
3297 time.
3298 choices
3300 The list of choices to select randomly
3301 FuzzyInteger
3303 class factory.fuzzy.FuzzyInteger(low[, high[, step]])
3304 The FuzzyInteger fuzzer generates random integers within a given
3305 inclusive range.
3306 The low bound may be omitted, in which case it defaults to 0:
3308 >>> fi = FuzzyInteger(0, 42)
3310 >>> fi.low, fi.high
3311 0, 42
3312 >>> fi = FuzzyInteger(42)
3314 >>> fi.low, fi.high
3315 0, 42
3316 low int, the inclusive lower bound of generated integers
3318 high int, the inclusive higher bound of generated integers
3320 step int, the step between values in the range; for instance,
3322 a FuzzyInteger(0, 42, step=3) might only yield values
3323 from [0, 3, 6, 9, 12, 15, 18, 21, 24, 27, 30, 33, 36, 39,
3324 42].
3325 FuzzyDecimal
3327 class factory.fuzzy.FuzzyDecimal(low[, high[, precision=2]])
3328 The FuzzyDecimal fuzzer generates random decimals within a given
3329 inclusive range.
3330 The low bound may be omitted, in which case it defaults to 0:
3332 >>> FuzzyDecimal(0.5, 42.7)
3334 >>> fi.low, fi.high
3335 0.5, 42.7
3336 >>> fi = FuzzyDecimal(42.7)
3338 >>> fi.low, fi.high
3339 0.0, 42.7
3340 >>> fi = FuzzyDecimal(0.5, 42.7, 3)
3342 >>> fi.low, fi.high, fi.precision
3343 0.5, 42.7, 3
3344 low decimal, the inclusive lower bound of generated decimals
3346 high decimal, the inclusive higher bound of generated decimals
3348 precision
3350 int, the number of digits to generate after the dot. The default
3352 is 2 digits.
3353 FuzzyFloat
3355 class factory.fuzzy.FuzzyFloat(low[, high])
3356 The FuzzyFloat fuzzer provides random float objects within a
3357 given inclusive range.
3358 >>> FuzzyFloat(0.5, 42.7)
3360 >>> fi.low, fi.high
3361 0.5, 42.7
3362 >>> fi = FuzzyFloat(42.7)
3364 >>> fi.low, fi.high
3365 0.0, 42.7
3366 low decimal, the inclusive lower bound of generated floats
3368 high decimal, the inclusive higher bound of generated floats
3370 FuzzyDate
3372 class factory.fuzzy.FuzzyDate(start_date[, end_date])
3373 The FuzzyDate fuzzer generates random dates within a given
3374 inclusive range.
3375 The end_date bound may be omitted, in which case it defaults to
3377 the current date:
3378 >>> fd = FuzzyDate(datetime.date(2008, 1, 1))
3380 >>> fd.start_date, fd.end_date
3381 datetime.date(2008, 1, 1), datetime.date(2013, 4, 16)
3382 start_date
3384 datetime.date, the inclusive lower bound of generated
3385 dates
3386 end_date
3388 datetime.date, the inclusive higher bound of generated
3389 dates
3390 FuzzyDateTime
3392 class factory.fuzzy.FuzzyDateTime(start_dt[, end_dt], force_year=None,
3393 force_month=None, force_day=None, force_hour=None, force_minute=None,
3394 force_second=None, force_microsecond=None)
3395 The FuzzyDateTime fuzzer generates random timezone-aware date‐
3396 time within a given inclusive range.
3397 The end_dt bound may be omitted, in which case it defaults to
3399 datetime.datetime.now() localized into the UTC timezone.
3400 >>> fdt = FuzzyDateTime(datetime.datetime(2008, 1, 1, tzinfo=UTC))
3402 >>> fdt.start_dt, fdt.end_dt
3403 datetime.datetime(2008, 1, 1, tzinfo=UTC), datetime.datetime(2013, 4, 21, 19, 13, 32, 458487, tzinfo=UTC)
3404 The force_XXX keyword arguments force the related value of gen‐
3406 erated datetimes:
3407 >>> fdt = FuzzyDateTime(datetime.datetime(2008, 1, 1, tzinfo=UTC), datetime.datetime(2009, 1, 1, tzinfo=UTC),
3409 ... force_day=3, force_second=42)
3410 >>> fdt.evaluate(2, None, False) # Actual code used by ``SomeFactory.build()``
3411 datetime.datetime(2008, 5, 3, 12, 13, 42, 124848, tzinfo=UTC)
3412 start_dt
3414 datetime.datetime, the inclusive lower bound of generated
3415 datetimes
3416 end_dt datetime.datetime, the inclusive upper bound of generated
3418 datetimes
3419 force_year
3421 int or None; if set, forces the year of generated date‐
3422 time.
3423 force_month
3425 int or None; if set, forces the month of generated date‐
3426 time.
3427 force_day
3429 int or None; if set, forces the day of generated date‐
3430 time.
3431 force_hour
3433 int or None; if set, forces the hour of generated date‐
3434 time.
3435 force_minute
3437 int or None; if set, forces the minute of generated date‐
3438 time.
3439 force_second
3441 int or None; if set, forces the second of generated date‐
3442 time.
3443 force_microsecond
3445 int or None; if set, forces the microsecond of generated
3446 datetime.
3447 FuzzyNaiveDateTime
3449 class factory.fuzzy.FuzzyNaiveDateTime(start_dt[, end_dt],
3450 force_year=None, force_month=None, force_day=None, force_hour=None,
3451 force_minute=None, force_second=None, force_microsecond=None)
3452 The FuzzyNaiveDateTime fuzzer generates random naive datetime
3453 within a given inclusive range.
3454 The end_dt bound may be omitted, in which case it defaults to
3456 datetime.datetime.now():
3457 >>> fdt = FuzzyNaiveDateTime(datetime.datetime(2008, 1, 1))
3459 >>> fdt.start_dt, fdt.end_dt
3460 datetime.datetime(2008, 1, 1), datetime.datetime(2013, 4, 21, 19, 13, 32, 458487)
3461 The force_XXX keyword arguments force the related value of gen‐
3463 erated datetimes:
3464 >>> fdt = FuzzyNaiveDateTime(datetime.datetime(2008, 1, 1), datetime.datetime(2009, 1, 1),
3466 ... force_day=3, force_second=42)
3467 >>> fdt.evaluate(2, None, False) # Actual code used by ``SomeFactory.build()``
3468 datetime.datetime(2008, 5, 3, 12, 13, 42, 124848)
3469 start_dt
3471 datetime.datetime, the inclusive lower bound of generated
3472 datetimes
3473 end_dt datetime.datetime, the inclusive upper bound of generated
3475 datetimes
3476 force_year
3478 int or None; if set, forces the year of generated date‐
3479 time.
3480 force_month
3482 int or None; if set, forces the month of generated date‐
3483 time.
3484 force_day
3486 int or None; if set, forces the day of generated date‐
3487 time.
3488 force_hour
3490 int or None; if set, forces the hour of generated date‐
3491 time.
3492 force_minute
3494 int or None; if set, forces the minute of generated date‐
3495 time.
3496 force_second
3498 int or None; if set, forces the second of generated date‐
3499 time.
3500 force_microsecond
3502 int or None; if set, forces the microsecond of generated
3503 datetime.
3504 Custom fuzzy fields
3506 Alternate fuzzy fields may be defined. They should inherit from the
3507 BaseFuzzyAttribute class, and override its fuzz() method.
3508 class factory.fuzzy.BaseFuzzyAttribute
3510 Base class for all fuzzy attributes.
3511 fuzz(self)
3513 The method responsible for generating random values.
3514 Must be overridden in subclasses.
3515 Managing randomness
3517 Using random in factories allows to “fuzz” a program efficiently. How‐
3518 ever, it’s sometimes required to reproduce a failing test.
3519 factory.fuzzy uses a separate instance of random.Random, and provides a
3521 few helpers for this:
3522 factory.fuzzy.get_random_state()
3524 Call get_random_state() to retrieve the random generator’s cur‐
3525 rent state.
3526 factory.fuzzy.set_random_state(state)
3528 Use set_random_state() to set a custom state into the random
3529 generator (fetched from get_random_state() in a previous run,
3530 for instance)
3531 factory.fuzzy.reseed_random(seed)
3533 The reseed_random() function allows to load a chosen seed into
3534 the random generator.
3535 Custom BaseFuzzyAttribute subclasses SHOULD use factory.fuzzy._random
3537 as a randomness source; this ensures that data they generate can be
3538 regenerated using the simple state from get_random_state().
3539 Examples
3541 Here are some real-world examples of using FactoryBoy.
3542 Objects
3544 First, let’s define a couple of objects:
3545 class Account(object):
3547 def __init__(self, username, email):
3548 self.username = username
3549 self.email = email
3550 def __str__(self):
3552 return '%s (%s)' % (self.username, self.email)
3553 class Profile(object):
3556 GENDER_MALE = 'm'
3558 GENDER_FEMALE = 'f'
3559 GENDER_UNKNOWN = 'u' # If the user refused to give it
3560 def __init__(self, account, gender, firstname, lastname, planet='Earth'):
3562 self.account = account
3563 self.gender = gender
3564 self.firstname = firstname
3565 self.lastname = lastname
3566 self.planet = planet
3567 def __unicode__(self):
3569 return u'%s %s (%s)' % (
3570 unicode(self.firstname),
3571 unicode(self.lastname),
3572 unicode(self.account.accountname),
3573 )
3574 Factories
3576 And now, we’ll define the related factories:
3577 import datetime
3579 import factory
3580 import random
3581 from . import objects
3583 class AccountFactory(factory.Factory):
3586 class Meta:
3587 model = objects.Account
3588 username = factory.Sequence(lambda n: 'john%s' % n)
3590 email = factory.LazyAttribute(lambda o: '%s@example.org' % o.username)
3591 date_joined = factory.LazyFunction(datetime.datetime.now)
3592 class ProfileFactory(factory.Factory):
3595 class Meta:
3596 model = objects.Profile
3597 account = factory.SubFactory(AccountFactory)
3599 gender = factory.Iterator([objects.Profile.GENDER_MALE, objects.Profile.GENDER_FEMALE])
3600 firstname = u'John'
3601 lastname = u'Doe'
3602 We have now defined basic factories for our Account and Profile
3604 classes.
3605 If we commonly use a specific variant of our objects, we can refine a
3607 factory accordingly:
3608 class FemaleProfileFactory(ProfileFactory):
3610 gender = objects.Profile.GENDER_FEMALE
3611 firstname = u'Jane'
3612 user__username = factory.Sequence(lambda n: 'jane%s' % n)
3613 Using the factories
3615 We can now use our factories, for tests:
3616 import unittest
3618 from . import business_logic
3620 from . import factories
3621 from . import objects
3622 class MyTestCase(unittest.TestCase):
3625 def test_send_mail(self):
3627 account = factories.AccountFactory()
3628 email = business_logic.prepare_email(account, subject='Foo', text='Bar')
3629 self.assertEqual(email.to, account.email)
3631 def test_get_profile_stats(self):
3633 profiles = []
3634 profiles.extend(factories.ProfileFactory.create_batch(4))
3636 profiles.extend(factories.FemaleProfileFactory.create_batch(2))
3637 profiles.extend(factories.ProfileFactory.create_batch(2, planet="Tatooine"))
3638 stats = business_logic.profile_stats(profiles)
3640 self.assertEqual({'Earth': 6, 'Mars': 2}, stats.planets)
3641 self.assertLess(stats.genders[objects.Profile.GENDER_FEMALE], 2)
3642 Or for fixtures:
3644 from . import factories
3646 def make_objects():
3648 factories.ProfileFactory.create_batch(size=50)
3649 # Let's create a few, known objects.
3651 factories.ProfileFactory(
3652 gender=objects.Profile.GENDER_MALE,
3653 firstname='Luke',
3654 lastname='Skywalker',
3655 planet='Tatooine',
3656 )
3657 factories.ProfileFactory(
3659 gender=objects.Profile.GENDER_FEMALE,
3660 firstname='Leia',
3661 lastname='Organa',
3662 planet='Alderaan',
3663 )
3664 Internals
3666 Behind the scenes: steps performed when parsing a factory declaration,
3667 and when calling it.
3668 This section will be based on the following factory declaration:
3670 class UserFactory(factory.Factory):
3672 class Meta:
3673 model = User
3674 class Params:
3676 # Allow us to quickly enable staff/superuser flags
3677 superuser = factory.Trait(
3678 is_superuser=True,
3679 is_staff=True,
3680 )
3681 # Meta parameter handling all 'enabled'-related fields
3682 enabled = True
3683 # Classic fields
3685 username = factory.Faker('user_name')
3686 full_name = factory.Faker('name')
3687 creation_date = factory.fuzzy.FuzzyDateTime(
3688 datetime.datetime(2000, 1, 1, tzinfo=UTC),
3689 datetime.datetime(2015, 12, 31, 20, tzinfo=UTC)
3690 )
3691 # Conditional flags
3693 is_active = factory.SelfAttribute('enabled')
3694 deactivation_date = factory.Maybe(
3695 'enabled',
3696 None,
3697 factory.fuzzy.FuzzyDateTime(
3698 # factory.SelfAttribute('creation_date'),
3699 datetime.datetime.now().replace(tzinfo=UTC) - datetime.timedelta(days=10),
3700 datetime.datetime.now().replace(tzinfo=UTC) - datetime.timedelta(days=1),
3701 ),
3702 )
3703 # Related logs
3705 creation_log = factory.RelatedFactory(
3706 UserLogFactory, 'user',
3707 action='create', timestamp=factory.SelfAttribute('user.creation_date'),
3708 )
3709 Parsing, Step 1: Metaclass and type declaration
3712 1. Python parses the declaration and calls (thanks to the metaclass
3713 declaration):
3714 factory.base.BaseFactory.__new__(
3716 'UserFactory',
3717 (factory.Factory,),
3718 attributes,
3719 )
3720 2. That metaclass removes Meta and Params from the class attributes,
3722 then generate the actual factory class (according to standard Python
3723 rules)
3724 3. It initializes a FactoryOptions object, and links it to the class
3726 Parsing, Step 2: adapting the class definition
3728 1. The FactoryOptions reads the options from the class Meta declaration
3729 2. It finds a few specific pointer (loading the model class, finding
3731 the reference factory for the sequence counter, etc.)
3732 3. It copies declarations and parameters from parent classes
3734 4. It scans current class attributes (from vars()) to detect pre/post
3736 declarations
3737 5. Declarations are split among pre-declarations and post-declarations
3739 (a raw value shadowing a post-declaration is seen as a post-declara‐
3740 tion)
3741 NOTE:
3743 A declaration for foo__bar will be converted into parameter bar for
3744 declaration foo.
3745 Instantiating, Step 1: Converging entrypoints
3747 First, decide the strategy:
3748 · If the entrypoint is specific to a strategy (build(), create_batch(),
3750 …), use it
3751 · If it is generic (generate(), Factory.__call__()), use the strategy
3753 defined at the class Meta level
3754 Then, we’ll pass the strategy and passed-in overrides to the _gener‐
3756 ate() method.
3757 NOTE:
3759 According to the project roadmap, a future version will use a _gen‐
3760 erate_batch`() at its core instead.
3761 A factory’s _generate() function actually delegates to a StepBuilder()
3763 object. This object will carry the overall “build an object” context
3764 (strategy, depth, and possibly other).
3765 Instantiating, Step 2: Preparing values
3767 1. The StepBuilder merges overrides with the class-level declarations
3768 2. The sequence counter for this instance is initialized
3770 3. A Resolver is set up with all those declarations, and parses them in
3772 order; it will call each value’s evaluate() method, including extra
3773 parameters.
3774 4. If needed, the Resolver might recurse (through the StepBuilder, e.g
3776 when encountering a SubFactory.
3777 Instantiating, Step 3: Building the object
3779 1. The StepBuilder fetches the attributes computed by the Resolver.
3780 2. It applies renaming/adjustment rules
3782 3. It passes them to the FactoryOptions.instantiate() method, which
3784 forwards to the proper methods.
3785 4. Post-declaration are applied (in declaration order)
3787 NOTE:
3789 This document discusses implementation details; there is no guaran‐
3790 tee that the described methods names and signatures will be kept as
3791 is.
3792 ChangeLog
3794 2.11.1 (2018-05-05)
3795 Bugfix:
3796 · Fix passing deep context to a SubFactory (Foo(x__y__z=fac‐
3798 tory.Faker('name'))
3799 2.11.0 (2018-05-05)
3801 Bugfix:
3802 · Fix FuzzyFloat to return a 15 decimal digits precision float by
3804 default
3805 · issue #451: Restore FileField to a ParameteredAttribute, relying
3807 on composition to parse the provided parameters.
3808 · issue #389: Fix random state management with faker.
3810 · issue #466: Restore mixing Trait and post_generation().
3812 2.10.0 (2018-01-28)
3814 Bugfix:
3815 · issue #443: Don’t crash when calling factory.Iterator.reset() on a
3817 brand new iterator.
3818 New:
3820 · issue #397: Allow a factory.Maybe to contain a PostGenerationDec‐
3822 laration. This also applies to factory.Trait, since they use a
3823 factory.Maybe declaration internally.
3824 2.9.2 (2017-08-03)
3826 Bugfix:
3827 · Fix declaration corruption bug when a factory defined
3829 foo__bar__baz=1 and a caller provided a foo__bar=x parameter at
3830 call time: this got merged into the factory’s base declarations.
3831 2.9.1 (2017-08-02)
3833 Bugfix:
3834 · Fix packaging issues (see
3836 https://github.com/zestsoftware/zest.releaser/issues/212)
3837 · Don’t crash when debugging PostGenerationDeclaration
3839 2.9.0 (2017-07-30)
3841 This version brings massive changes to the core engine, thus reducing
3842 the number of corner cases and weird behaviourrs.
3843 New:
3845 · issue #275: factory.fuzzy and factory.faker now use the same ran‐
3847 dom seed.
3848 · Add factory.Maybe, which chooses among two possible declarations
3850 based on another field’s value (powers the Trait feature).
3851 · PostGenerationMethodCall only allows to pass one positional argu‐
3853 ment; use keyword arguments for extra parameters.
3854 Deprecation:
3856 · factory.fuzzy.get_random_state is deprecated, factory.ran‐
3858 dom.get_random_state should be used instead.
3859 · factory.fuzzy.set_random_state is deprecated, factory.ran‐
3861 dom.set_random_state should be used instead.
3862 · factory.fuzzy.reseed_random is deprecated, factory.ran‐
3864 dom.reseed_random should be used instead.
3865 2.8.1 (2016-12-17)
3867 Bugfix:
3868 · Fix packaging issues.
3870 2.8.0 (2016-12-17)
3872 New:
3873 · issue #240: Call post-generation declarations in the order they
3875 were declared, thanks to Oleg Pidsadnyi.
3876 · issue #309: Provide new options for SQLAlchemy session persistence
3878 Bugfix:
3880 · issue #334: Adjust for the package change in faker
3882 2.7.0 (2016-04-19)
3884 New:
3885 · issue #267: Add factory.LazyFunction to remove unneeded lambda
3887 parameters, thanks to Hervé Cauwelier.
3888 · issue #251: Add parameterized factories and traits
3890 · issue #256, issue #292: Improve error messages in corner cases
3892 Removed:
3894 · issue #278: Formally drop support for Python2.6
3896 WARNING:
3898 Version 2.7.0 moves all error classes to factory.errors. This breaks
3899 existing import statements for any error classes except those
3900 importing FactoryError directly from the factory module.
3901 2.6.1 (2016-02-10)
3903 New:
3904 · issue #262: Allow optional forced flush on SQLAlchemy, courtesy of
3906 Minjung.
3907 2.6.0 (2015-10-20)
3909 New:
3910 · Add factory.FactoryOptions.rename to help handle conflicting names
3912 (issue #206)
3913 · Add support for random-yet-realistic values through fake-factory,
3915 through the factory.Faker class.
3916 · factory.Iterator no longer begins iteration of its argument at
3918 import time, thus allowing to pass in a lazy iterator such as a
3919 Django queryset (i.e factory.Iterator(mod‐
3920 els.MyThingy.objects.all())).
3921 · Simplify imports for ORM layers, now available through a simple
3923 factory import, at factory.alchemy.SQLAlchemyModelFactory / fac‐
3924 tory.django.DjangoModelFactory / factory.mongoengine.MongoEngine‐
3925 Factory.
3926 Bugfix:
3928 · issue #201: Properly handle custom Django managers when dealing
3930 with abstract Django models.
3931 · issue #212: Fix factory.django.mute_signals() to handle Django’s
3933 signal caching
3934 · issue #228: Don’t load django.apps.apps.get_model() until required
3936 · issue #219: Stop using mogo.model.Model.new(), deprecated 4 years
3938 ago.
3939 2.5.2 (2015-04-21)
3941 Bugfix:
3942 · Add support for Django 1.7/1.8
3944 · Add support for mongoengine>=0.9.0 / pymongo>=2.1
3946 2.5.1 (2015-03-27)
3948 Bugfix:
3949 · Respect custom managers in DjangoModelFactory (see issue #192)
3951 · Allow passing declarations (e.g Sequence) as parameters to File‐
3953 Field and ImageField.
3954 2.5.0 (2015-03-26)
3956 New:
3957 · Add support for getting/setting factory.fuzzy’s random state (see
3959 issue #175, issue #185).
3960 · Support lazy evaluation of iterables in factory.fuzzy.FuzzyChoice
3962 (see issue #184).
3963 · Support non-default databases at the factory level (see issue
3965 #171)
3966 · Make factory.django.FileField and factory.django.ImageField
3968 non-post_generation, i.e normal fields also available in save()
3969 (see issue #141).
3970 Bugfix:
3972 · Avoid issues when using factory.django.mute_signals() on a base
3974 factory class (see issue #183).
3975 · Fix limitations of factory.StubFactory, that can now use fac‐
3977 tory.SubFactory and co (see issue #131).
3978 Deprecation:
3980 · Remove deprecated features from 2.4.0 (2014-06-21)
3982 · Remove the auto-magical sequence setup (based on the latest pri‐
3984 mary key value in the database) for Django and SQLAlchemy; this
3985 relates to issues issue #170, issue #153, issue #111, issue #103,
3986 issue #92, issue #78. See
3987 https://github.com/FactoryBoy/factory_boy/commit/13d310f for tech‐
3988 nical details.
3989 WARNING:
3991 Version 2.5.0 removes the ‘auto-magical sequence setup’ bug-and-fea‐
3992 ture. This could trigger some bugs when tests expected a non-zero
3993 sequence reference.
3994 Upgrading
3996 WARNING:
3997 Version 2.5.0 removes features that were marked as deprecated in
3998 v2.4.0.
3999 All FACTORY_*-style attributes are now declared in a class Meta: sec‐
4001 tion:
4002 # Old-style, deprecated
4004 class MyFactory(factory.Factory):
4005 FACTORY_FOR = models.MyModel
4006 FACTORY_HIDDEN_ARGS = ['a', 'b', 'c']
4007 # New-style
4009 class MyFactory(factory.Factory):
4010 class Meta:
4011 model = models.MyModel
4012 exclude = ['a', 'b', 'c']
4013 A simple shell command to upgrade the code would be:
4015 # sed -i: inplace update
4017 # grep -l: only file names, not matching lines
4018 sed -i 's/FACTORY_FOR =/class Meta:\n model =/' $(grep -l FACTORY_FOR $(find . -name '*.py'))
4019 This takes care of all FACTORY_FOR occurrences; the files containing
4021 other attributes to rename can be found with grep -R FACTORY .
4022 2.4.1 (2014-06-23)
4024 Bugfix:
4025 · Fix overriding deeply inherited attributes (set in one factory,
4027 overridden in a subclass, used in a sub-sub-class).
4028 2.4.0 (2014-06-21)
4030 New:
4031 · Add support for factory.fuzzy.FuzzyInteger.step, thanks to
4033 ilya-pirogov (issue #120)
4034 · Add mute_signals() decorator to temporarily disable some signals,
4036 thanks to ilya-pirogov (issue #122)
4037 · Add FuzzyFloat (issue #124)
4039 · Declare target model and other non-declaration fields in a class
4041 Meta section.
4042 Deprecation:
4044 · Use of FACTORY_FOR and other FACTORY class-level attributes is
4046 deprecated and will be removed in 2.5. Those attributes should
4047 now declared within the class Meta attribute:
4048 For factory.Factory:
4050 · Rename FACTORY_FOR to model
4052 · Rename ABSTRACT_FACTORY to abstract
4054 · Rename FACTORY_STRATEGY to strategy
4056 · Rename FACTORY_ARG_PARAMETERS to inline_args
4058 · Rename FACTORY_HIDDEN_ARGS to exclude
4060 For factory.django.DjangoModelFactory:
4062 · Rename FACTORY_DJANGO_GET_OR_CREATE to django_get_or_create
4064 For factory.alchemy.SQLAlchemyModelFactory:
4066 · Rename FACTORY_SESSION to sqlalchemy_session
4068 2.3.1 (2014-01-22)
4070 Bugfix:
4071 · Fix badly written assert containing state-changing code, spotted
4073 by chsigi (issue #126)
4074 · Don’t crash when handling objects whose __repr__ is non-pure-ascii
4076 bytes on Py2, discovered by mbertheau (issue #123) and strycore (‐
4077 issue #127)
4078 2.3.0 (2013-12-25)
4080 New:
4081 · Add FuzzyText, thanks to jdufresne (issue #97)
4083 · Add FuzzyDecimal, thanks to thedrow (issue #94)
4085 · Add support for EmbeddedDocument, thanks to imiric (issue #100)
4087 2.2.1 (2013-09-24)
4089 Bugfix:
4090 · Fixed sequence counter for DjangoModelFactory when a factory
4092 inherits from another factory relating to an abstract model.
4093 2.2.0 (2013-09-24)
4095 Bugfix:
4096 · Removed duplicated SQLAlchemyModelFactory lurking in factory (‐
4098 issue #83)
4099 · Properly handle sequences within object inheritance chains. If
4101 FactoryA inherits from FactoryB, and their associated classes
4102 share the same link, sequence counters will be shared (issue #93)
4103 · Properly handle nested SubFactory overrides
4105 New:
4107 · The DjangoModelFactory now supports the FACTORY_FOR =
4109 'myapp.MyModel' syntax, making it easier to shove all factories in
4110 a single module (issue #66).
4111 · Add factory.debug() helper for easier backtrace analysis
4113 · Adding factory support for mongoengine with MongoEngineFactory.
4115 2.1.2 (2013-08-14)
4117 New:
4118 · The ABSTRACT_FACTORY keyword is now optional, and automatically
4120 set to True if neither the Factory subclass nor its parent declare
4121 the FACTORY_FOR attribute (issue #74)
4122 2.1.1 (2013-07-02)
4124 Bugfix:
4125 · Properly retrieve the color keyword argument passed to ImageField
4127 2.1.0 (2013-06-26)
4129 New:
4130 · Add FuzzyDate thanks to saulshanabrook
4132 · Add FuzzyDateTime and FuzzyNaiveDateTime.
4134 · Add a factory_parent attribute to the Resolver passed to LazyAt‐
4136 tribute, in order to access fields defined in wrapping factories.
4137 · Move DjangoModelFactory and MogoFactory to their own modules (fac‐
4139 tory.django and factory.mogo)
4140 · Add the reset_sequence() classmethod to Factory to ease resetting
4142 the sequence counter for a given factory.
4143 · Add debug messages to factory logger.
4145 · Add a reset() method to Iterator (issue #63)
4147 · Add support for the SQLAlchemy ORM through SQLAlchemyModelFactory
4149 (issue #64, thanks to Romain Commandé)
4150 · Add factory.django.FileField and factory.django.ImageField hooks
4152 for related Django model fields (issue #52)
4153 Bugfix
4155 · Properly handle non-integer pks in DjangoModelFactory (issue #57).
4157 · Disable RelatedFactory generation when a specific value was passed
4159 (issue #62, thanks to Gabe Koscky)
4160 Deprecation:
4162 · Rename RelatedFactory’s name argument to factory_related_name (See
4164 issue #58)
4165 2.0.2 (2013-04-16)
4167 New:
4168 · When FACTORY_DJANGO_GET_OR_CREATE is empty, use Model.objects.cre‐
4170 ate() instead of Model.objects.get_or_create.
4171 2.0.1 (2013-04-16)
4173 New:
4174 · Don’t push defaults to get_or_create when FAC‐
4176 TORY_DJANGO_GET_OR_CREATE is not set.
4177 2.0.0 (2013-04-15)
4179 New:
4180 · Allow overriding the base factory class for make_factory() and
4182 friends.
4183 · Add support for Python3 (Thanks to kmike and nkryptic)
4185 · The default type for Sequence is now int
4187 · Fields listed in FACTORY_HIDDEN_ARGS won’t be passed to the asso‐
4189 ciated class’ constructor
4190 · Add support for get_or_create in DjangoModelFactory, through FAC‐
4192 TORY_DJANGO_GET_OR_CREATE.
4193 · Add support for fuzzy attribute definitions.
4195 · The Sequence counter can be overridden when calling a generating
4197 function
4198 · Add Dict and List declarations (Closes issue #18).
4200 Removed:
4202 · Remove associated class discovery
4204 · Remove InfiniteIterator and infinite_iterator()
4206 · Remove CircularSubFactory
4208 · Remove extract_prefix kwarg to post-generation hooks.
4210 · Stop defaulting to Django’s Foo.objects.create() when “creating”
4212 instances
4213 · Remove STRATEGY_*
4215 · Remove set_building_function() / set_creation_function()
4217 1.3.0 (2013-03-11)
4219 WARNING:
4220 This version deprecates many magic or unexplicit features that will
4221 be removed in v2.0.0.
4222 Please read the Upgrading section, then run your tests with python
4224 -W default to see all remaining warnings.
4225 New
4227 ·
4228 Global:
4230 · Rewrite the whole documentation
4232 · Provide a dedicated MogoFactory subclass of Factory
4234 ·
4236 The Factory class:
4238 · Better creation/building customization hooks at factory.Fac‐
4240 tory._build() and factory.Factory.create()
4241 · Add support for passing non-kwarg parameters to a Factory
4243 wrapped class through FACTORY_ARG_PARAMETERS.
4244 · Keep the FACTORY_FOR attribute in Factory classes
4246 ·
4248 Declarations:
4250 · Allow SubFactory to solve circular dependencies between fac‐
4252 tories
4253 · Enhance SelfAttribute to handle “container” attribute fetch‐
4255 ing
4256 · Add a getter to Iterator declarations
4258 · A Iterator may be prevented from cycling by setting its
4260 cycle argument to False
4261 · Allow overriding default arguments in a PostGeneration‐
4263 MethodCall when generating an instance of the factory
4264 · An object created by a DjangoModelFactory will be saved
4266 again after PostGeneration hooks execution
4267 Pending deprecation
4269 The following features have been deprecated and will be removed in an
4270 upcoming release.
4271 ·
4273 Declarations:
4275 · InfiniteIterator is deprecated in favor of Iterator
4277 · CircularSubFactory is deprecated in favor of SubFactory
4279 · The extract_prefix argument to post_generation() is now dep‐
4281 recated
4282 ·
4284 Factory:
4286 · Usage of set_creation_function() and set_building_function()
4288 are now deprecated
4289 · Implicit associated class discovery is no longer supported,
4291 you must set the FACTORY_FOR attribute on all Factory sub‐
4292 classes
4293 Upgrading
4295 This version deprecates a few magic or undocumented features. All
4296 warnings will turn into errors starting from v2.0.0.
4297 In order to upgrade client code, apply the following rules:
4299 · Add a FACTORY_FOR attribute pointing to the target class to each Fac‐
4301 tory, instead of relying on automagic associated class discovery
4302 · When using factory_boy for Django models, have each factory inherit
4304 from DjangoModelFactory
4305 · Replace factory.CircularSubFactory('some.module', 'Symbol') with fac‐
4307 tory.SubFactory('some.module.Symbol')
4308 · Replace factory.InfiniteIterator(iterable) with factory.Itera‐
4310 tor(iterable)
4311 · Replace @factory.post_generation() with @factory.post_generation
4313 · Replace factory.set_building_function(SomeFactory, building_function)
4315 with an override of the _build() method of SomeFactory
4316 · Replace factory.set_creation_function(SomeFactory, creation_function)
4318 with an override of the _create() method of SomeFactory
4319 1.2.0 (2012-09-08)
4321 New:
4322 · Add CircularSubFactory to solve circular dependencies between fac‐
4324 tories
4325 1.1.5 (2012-07-09)
4327 Bugfix:
4328 · Fix PostGenerationDeclaration and derived classes.
4330 1.1.4 (2012-06-19)
4332 New:
4333 · Add use_strategy() decorator to override a Factory’s default
4335 strategy
4336 · Improve test running (tox, python2.6/2.7)
4338 · Introduce PostGeneration and RelatedFactory
4340 1.1.3 (2012-03-09)
4342 Bugfix:
4343 · Fix packaging rules
4345 1.1.2 (2012-02-25)
4347 New:
4348 · Add Iterator and InfiniteIterator for Factory attribute declara‐
4350 tions.
4351 · Provide generate() and simple_generate(), that allow specifying
4353 the instantiation strategy directly. Also provides gener‐
4354 ate_batch() and simple_generate_batch().
4355 1.1.1 (2012-02-24)
4357 New:
4358 · Add build_batch(), create_batch() and stub_batch(), to instantiate
4360 factories in batch
4361 1.1.0 (2012-02-24)
4363 New:
4364 · Improve the SelfAttribute syntax to fetch sub-attributes using the
4366 foo.bar syntax;
4367 · Add ContainerAttribute to fetch attributes from the container of a
4369 SubFactory.
4370 · Provide the make_factory() helper: MyClassFactory = make_fac‐
4372 tory(MyClass, x=3, y=4)
4373 · Add build(), create(), stub() helpers
4375 Bugfix:
4377 · Allow classmethod/staticmethod on factories
4379 Deprecation:
4381 · Auto-discovery of FACTORY_FOR based on class name is now depre‐
4383 cated
4384 1.0.4 (2011-12-21)
4386 New:
4387 · Improve the algorithm for populating a Factory attributes dict
4389 · Add python setup.py test command to run the test suite
4391 · Allow custom build functions
4393 · Introduce MOGO_BUILD build function
4395 · Add support for inheriting from multiple Factory
4397 · Base Factory classes can now be declared abstract.
4399 · Provide DjangoModelFactory, whose Sequence counter starts at the
4401 next free database id
4402 · Introduce SelfAttribute, a shortcut for factory.LazyAt‐
4404 tribute(lambda o: o.foo.bar.baz.
4405 Bugfix:
4407 · Handle nested SubFactory
4409 · Share sequence counter between parent and subclasses
4411 · Fix SubFactory / Sequence interferences
4413 1.0.2 (2011-05-16)
4415 New:
4416 · Introduce SubFactory
4418 1.0.1 (2011-05-13)
4420 New:
4421 · Allow Factory inheritance
4423 · Improve handling of custom build/create functions
4425 Bugfix:
4427 · Fix concurrency between LazyAttribute and Sequence
4429 1.0.0 (2010-08-22)
4431 New:
4432 · First version of factory_boy
4434 Credits
4436 · Initial version by Mark Sandstrom (2010)
4437 · Developed by Raphaël Barrois since 2011
4439 Credits
4441 Maintainers
4442 The factory_boy project is operated and maintained by:
4443 · Jeff Widman <jeff@jeffwidman.com> (https://github.com/jeffwidman)
4445 · Raphaël Barrois <raphael.barrois+fboy@polytechnique.org> (‐
4447 https://github.com/rbarrois)
4448 Contributors
4450 The project was initially created by Mark Sandstrom <‐
4451 mark@deliciouslynerdy.com>.
4452 The project has received contributions from (in alphabetical order):
4454 · Adam Chainz <adam@adamj.eu>
4456 · Alejandro <tovarich@gmail.com>
4458 · Alexey Kotlyarov <a@koterpillar.com>
4460 · Amit Shah <amit@amwam.me>
4462 · Anas Zahim <zanass0@gmail.com> (https://github.com/kamotos)
4464 · Andrey Voronov <voronov84@gmail.com>
4466 · Branko Majic <branko@majic.rs>
4468 · Carl Meyer <carl@oddbird.net>
4470 · Chris Lasher <chris.lasher@gmail.com>
4472 · Chris Seto <chriskseto@gmail.com>
4474 · Christoph Sieghart <sigi@0x2a.at>
4476 · David Baumgold <david@davidbaumgold.com>
4478 · Demur Nodia <demur.nodia@gmail.com> (https://github.com/demonno)
4480 · Eduard Iskandarov <edikexp@gmail.com>
4482 · Flavio Curella <flavio.curella@gmail.com>
4484 · George Hickman <george@ghickman.co.uk>
4486 · Hervé Cauwelier <herve.cauwelier@polyconseil.fr>
4488 · Ilya Baryshev <baryshev@gmail.com>
4490 · Ilya Pirogov <ilja.pirogov@gmail.com>
4492 · Ionuț Arțăriși <ionut@artarisi.eu>
4494 · Issa Jubril <issa.jubril@andela.com>
4496 · Ivan Miric <imiric@gmail.com>
4498 · Janusz Skonieczny <wooyek@users.noreply.github.com>
4500 · Jeff Widman <jeff@jeffwidman.com> (https://github.com/jeffwidman)
4502 · Jon Dufresne <jon.dufresne@gmail.com>
4504 · Jonathan Tushman <jtushman@pipewave.com>
4506 · Joshua Carp <jm.carp@gmail.com>
4508 · Leonardo Lazzaro <llazzaro@dc.uba.ar>
4510 · Luke GB <github@lukegb.com>
4512 · Marc Abramowitz <marc@marc-abramowitz.com>
4514 · Mark Sandstrom <mark@deliciouslynerdy.com>
4516 · Martin Bächtold <martin+factoryboy@baechtold.me> (‐
4518 https://github.com/mbaechtold)
4519 · Michael Joseph <michaeljoseph+github@gmail.com>
4521 · Mikhail Korobov <kmike84@gmail.com>
4523 · Oleg Pidsadnyi <oleg.pidsadnyi@gmail.com>
4525 · Omer <omer@stokeet.com>
4527 · Pauly Fenwar <fenney@gmail.com>
4529 · Peter Marsh <pete@skimlinks.com>
4531 · Puneeth Chaganti <punchagan@muse-amuse.in>
4533 · QuantumGhost <obelisk.reg+github@gmail.com>
4535 · Raphaël Barrois <raphael.barrois+fboy@polytechnique.org> (‐
4537 https://github.com/rbarrois)
4538 · Rich Rauenzahn <rich@vmware.com>
4540 · Richard Moch <richard@mbp.polyconseil.fr>
4542 · Rob Zyskowski <zyskowski.rob@gmail.com>
4544 · Robrecht De Rouck <Robrecht.De.Rouck@gmail.com>
4546 · Samuel Paccoud <samuel@sampaccoud.com>
4548 · Saul Shanabrook <s.shanabrook@gmail.com>
4550 · Sean Löfgren <SeanBE@users.noreply.github.com>
4552 · Tom <tom@tomleo.com>
4554 · alex-netquity <alex@netquity.com>
4556 · anentropic <ego@anentropic.com>
4558 · minimumserious <commande.romain@gmail.com>
4560 · mluszczyk <mluszczyk@users.noreply.github.com>
4562 · nkryptic <nkryptic@gmail.com>
4564 · obiwanus <ivan@ivanovs.info>
4566 · tsouvarev <tsouvarev@mail.ru>
4568 · yamaneko <yamaneko1212@gmail.com>
4570 Contributor license agreement
4572 NOTE:
4573 This agreement is required to allow redistribution of submitted con‐
4574 tributions. See http://oss-watch.ac.uk/resources/cla for an expla‐
4575 nation.
4576 Any contributor proposing updates to the code or documentation of this
4578 project MUST add its name to the list in the Contributors section,
4579 thereby “signing” the following contributor license agreement:
4580 They accept and agree to the following terms for their present end
4582 future contributions submitted to the factory_boy project:
4583 · They represent that they are legally entitled to grant this license,
4585 and that their contributions are their original creation
4586 · They grant the factory_boy project a perpetual, worldwide, non-exclu‐
4588 sive, no-charge, royalty-free, irrevocable copyright license to
4589 reproduce, prepare derivative works of, publicly display, sublicense
4590 and distribute their contributions and such derivative works.
4591 · They are not expected to provide support for their contributions,
4593 except to the extent they desire to provide support.
4594 NOTE:
4596 The above agreement is inspired by the Apache Contributor License
4597 Agreement.
4598 Ideas
4600 This is a list of future features that may be incorporated into fac‐
4601 tory_boy:
4602 · When a Factory is built or created, pass the calling context through‐
4604 out the calling chain instead of custom solutions everywhere
4605 · Define a proper set of rules for the support of third-party ORMs
4607 · Properly evaluate nested declarations (e.g factory.fuzzy.Fuzzy‐
4609 Date(start_date=factory.SelfAttribute('since')))
4610 · genindex
4612 · modindex
4614 · search
4616
4618 Raphaël Barrois, Mark Sandstrom
4619
4621 2011-2015, Raphaël Barrois, Mark Sandstrom
46222.11 Feb 02, 2019 FACTORYBOY(1)