summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/recipes.rst94
1 files changed, 94 insertions, 0 deletions
diff --git a/docs/recipes.rst b/docs/recipes.rst
index 72dacef..70eca46 100644
--- a/docs/recipes.rst
+++ b/docs/recipes.rst
@@ -327,3 +327,97 @@ default :meth:`Model.objects.create() <django.db.models.query.QuerySet.create>`
manager = cls._get_manager(model_class)
# The default would use ``manager.create(*args, **kwargs)``
return manager.create_user(*args, **kwargs)
+
+
+Forcing the sequence counter
+----------------------------
+
+A common pattern with factory_boy is to use a :class:`factory.Sequence` declaration
+to provide varying values to attributes declared as unique.
+
+However, it is sometimes useful to force a given value to the counter, for instance
+to ensure that tests are properly reproductible.
+
+factory_boy provides a few hooks for this:
+
+
+Forcing the value on a per-call basis
+ In order to force the counter for a specific :class:`~factory.Factory` instantiation,
+ just pass the value in the ``__sequence=42`` parameter:
+
+ .. code-block:: python
+
+ class AccountFactory(factory.Factory):
+ class Meta:
+ model = Account
+ uid = factory.Sequence(lambda n: n)
+ name = "Test"
+
+ .. code-block:: pycon
+
+ >>> obj1 = AccountFactory(name="John Doe", __sequence=10)
+ >>> obj1.uid # Taken from the __sequence counter
+ 10
+ >>> obj2 = AccountFactory(name="Jane Doe")
+ >>> obj2.uid # The base sequence counter hasn't changed
+ 1
+
+
+Resetting the counter globally
+ If all calls for a factory must start from a deterministic number,
+ use :meth:`factory.Factory.reset_sequence`; this will reset the counter
+ to its initial value (as defined by :meth:`factory.Factory._setup_next_sequence`).
+
+ .. code-block:: pycon
+
+ >>> AccountFactory().uid
+ 1
+ >>> AccountFactory().uid
+ 2
+ >>> AccountFactory.reset_sequence()
+ >>> AccountFactory().uid # Reset to the initial value
+ 1
+ >>> AccountFactory().uid
+ 2
+
+ It is also possible to reset the counter to a specific value:
+
+ .. code-block:: pycon
+
+ >>> AccountFactory.reset_sequence(10)
+ >>> AccountFactory().uid
+ 10
+ >>> AccountFactory().uid
+ 11
+
+ This recipe is most useful in a :class:`~unittest.TestCase`'s
+ :meth:`~unittest.TestCase.setUp` method.
+
+
+Forcing the initial value for all projects
+ The sequence counter of a :class:`~factory.Factory` can also be set
+ automatically upon the first call through the
+ :meth:`~factory.Factory._setup_next_sequence` method; this helps when the
+ objects's attributes mustn't conflict with pre-existing data.
+
+ A typical example is to ensure that running a Python script twice will create
+ non-conflicting objects, by setting up the counter to "max used value plus one":
+
+ .. code-block:: python
+
+ class AccountFactory(factory.django.DjangoModelFactory):
+ class Meta:
+ model = models.Account
+
+ @classmethod
+ def _setup_next_sequence(cls):
+ try:
+ return models.Accounts.objects.latest('uid').uid + 1
+ except models.Account.DoesNotExist:
+ return 1
+
+ .. code-block:: pycon
+
+ >>> Account.objects.create(uid=42, name="Blah")
+ >>> AccountFactory.create() # Sets up the account number based on the latest uid
+ <Account uid=43, name=Test>