diff options
| -rw-r--r-- | docs/examples.rst | 136 | ||||
| -rw-r--r-- | docs/index.rst | 7 |
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 ================== |