summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorRaphaël Barrois <raphael.barrois@polytechnique.org>2012-01-08 21:14:33 +0100
committerRaphaël Barrois <raphael.barrois@polytechnique.org>2012-01-08 21:14:33 +0100
commitb81f0282acbb8ee03d56b5ea8957e439efc5bf27 (patch)
tree08f56e82609a99001ad6af2d2d3d3915c1189116 /docs
parentbcc1ad6fdce458ae3b24270789ab60ddd2425c4a (diff)
downloadfactory-boy-b81f0282acbb8ee03d56b5ea8957e439efc5bf27.tar
factory-boy-b81f0282acbb8ee03d56b5ea8957e439efc5bf27.tar.gz
Add examples to the doc.
Signed-off-by: Raphaël Barrois <raphael.barrois@polytechnique.org>
Diffstat (limited to 'docs')
-rw-r--r--docs/examples.rst136
-rw-r--r--docs/index.rst7
2 files changed, 139 insertions, 4 deletions
diff --git a/docs/examples.rst b/docs/examples.rst
new file mode 100644
index 0000000..cac6bc6
--- /dev/null
+++ b/docs/examples.rst
@@ -0,0 +1,136 @@
+Examples
+========
+
+Here are some real-world examples of using FactoryBoy.
+
+
+Objects
+-------
+
+First, let's define a couple of objects::
+
+ class Account(object):
+ def __init__(self, username, email):
+ self.username = username
+ self.email = email
+
+ def __str__(self):
+ return '%s (%s)' % (self.username, self.email)
+
+
+ class Profile(object):
+
+ GENDER_MALE = 'm'
+ GENDER_FEMALE = 'f'
+ GENDER_UNKNOWN = 'u' # If the user refused to give it
+
+ def __init__(self, account, gender, firstname, lastname, planet='Earth'):
+ self.account = account
+ self.gender = gender
+ self.firstname = firstname
+ self.lastname = lastname
+ self.planet = planet
+
+ def __unicode__(self):
+ return u'%s %s (%s)' % (
+ unicode(self.firstname),
+ unicode(self.lastname),
+ unicode(self.account.accountname),
+ )
+
+Factories
+---------
+
+And now, we'll define the related factories::
+
+ import factory
+ import random
+
+ from . import objects
+
+
+ class AccountFactory(factory.Factory):
+ FACTORY_FOR = objects.Account
+
+ username = factory.Sequence(lambda n: 'john%s' % n)
+ email = factory.LazyAttribute(lambda o: '%s@example.org' % o.username)
+
+
+ class ProfileFactory(factory.Factory):
+ FACTORY_FOR = objects.Profile
+
+ account = factory.SubFactory(AccountFactory)
+ gender = random.choice([objects.Profile.GENDER_MALE, objects.Profile.GENDER_FEMALE])
+ firstname = u'John'
+ lastname = u'Doe'
+
+
+
+We have now defined basic factories for our :py:class:`~Account` and :py:class:`~Profile` classes.
+
+If we commonly use a specific variant of our objects, we can refine a factory accordingly::
+
+ class FemaleProfileFactory(ProfileFactory):
+ gender = objects.Profile.GENDER_FEMALE
+ firstname = u'Jane'
+ user__username = factory.Sequence(lambda n: 'jane%s' % n)
+
+
+
+Using the factories
+-------------------
+
+We can now use our factories, for tests::
+
+ import unittest
+
+ from . import business_logic
+ from . import factories
+ from . import objects
+
+
+ class MyTestCase(unittest.TestCase):
+
+ def test_send_mail(self):
+ account = factories.AccountFactory()
+ email = business_logic.prepare_email(account, subject='Foo', text='Bar')
+
+ self.assertEqual(email.to, account.email)
+
+ def test_get_profile_stats(self):
+ profiles = []
+
+ for _ in xrange(4):
+ profiles.append(factories.ProfileFactory())
+ for _ in xrange(2):
+ profiles.append(factories.FemaleProfileFactory())
+ for _ in xrange(2):
+ profiles.append(factories.ProfileFactory(planet='Tatooine'))
+
+ stats = business_logic.profile_stats(profiles)
+ self.assertEqual({'Earth': 6, 'Mars': 2}, stats.planets)
+ self.assertLess(stats.genders[objects.Profile.GENDER_FEMALE], 2)
+
+
+Or for fixtures::
+
+ from . import factories
+
+ def make_objects():
+ for _ in xrange(50):
+ factories.ProfileFactory()
+
+ # Let's create a few, known objects.
+ factories.ProfileFactory(
+ gender=objects.Profile.GENDER_MALE,
+ firstname='Luke',
+ lastname='Skywalker',
+ planet='Tatooine',
+ )
+
+ factories.ProfileFactory(
+ gender=objects.Profile.GENDER_FEMALE,
+ firstname='Leia',
+ lastname='Organa',
+ planet='Alderaan',
+ )
diff --git a/docs/index.rst b/docs/index.rst
index 17d81c1..2e0f4a3 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -54,12 +54,11 @@ Once defined, a factory can be instantiated through different methods::
Contents:
-:doc:`SubFactory <subfactory>`
-
.. toctree::
- :maxdepth: 2
+ :maxdepth: 2
- subfactory
+ examples
+ subfactory
Indices and tables
==================