Fuzzy attributes

Note

Now that FactoryBoy includes the factory.Faker class, most of these built-in fuzzers are deprecated in favor of their Faker equivalents. Further discussion here: https://github.com/FactoryBoy/factory_boy/issues/271/

Some tests may be interested in testing with fuzzy, random values.

This is handled by the factory.fuzzy module, which provides a few random declarations.

Note

Use import factory.fuzzy to load this module.

FuzzyAttribute

class factory.fuzzy.FuzzyAttribute

The FuzzyAttribute uses an arbitrary callable as fuzzer. It is expected that successive calls of that function return various values.

fuzzer

The callable that generates random values

FuzzyText

class factory.fuzzy.FuzzyText(length=12, chars=string.ascii_letters, prefix='')

The FuzzyText fuzzer yields random strings beginning with the given prefix, followed by length charactes chosen from the chars character set, and ending with the given suffix.

length

int, the length of the random part

prefix

text, an optional prefix to prepend to the random part

suffix

text, an optional suffix to append to the random part

chars

char iterable, the chars to choose from; defaults to the list of ascii

letters and numbers.

FuzzyChoice

class factory.fuzzy.FuzzyChoice(choices)

The FuzzyChoice fuzzer yields random choices from the given iterable.

Note

The passed in choices will be converted into a list upon first use, not at declaration time.

This allows passing in, for instance, a Django queryset that will only hit the database during the database, not at import time.

choices

The list of choices to select randomly

FuzzyInteger

class factory.fuzzy.FuzzyInteger(low[, high[, step]])

The FuzzyInteger fuzzer generates random integers within a given inclusive range.

The low bound may be omitted, in which case it defaults to 0:

>>> fi = FuzzyInteger(0, 42)
>>> fi.low, fi.high
0, 42

>>> fi = FuzzyInteger(42)
>>> fi.low, fi.high
0, 42

low

int, the inclusive lower bound of generated integers

high

int, the inclusive higher bound of generated integers

step

int, the step between values in the range; for instance, a FuzzyInteger(0, 42, step=3) might only yield values from [0, 3, 6, 9, 12, 15, 18, 21, 24, 27, 30, 33, 36, 39, 42].

FuzzyDecimal

class factory.fuzzy.FuzzyDecimal(low[, high[, precision=2]])

The FuzzyDecimal fuzzer generates random decimals within a given inclusive range.

The low bound may be omitted, in which case it defaults to 0:

>>> FuzzyDecimal(0.5, 42.7)
>>> fi.low, fi.high
0.5, 42.7

>>> fi = FuzzyDecimal(42.7)
>>> fi.low, fi.high
0.0, 42.7

>>> fi = FuzzyDecimal(0.5, 42.7, 3)
>>> fi.low, fi.high, fi.precision
0.5, 42.7, 3

low

decimal, the inclusive lower bound of generated decimals

high

decimal, the inclusive higher bound of generated decimals

precision

int, the number of digits to generate after the dot. The default is 2 digits.

FuzzyFloat

class factory.fuzzy.FuzzyFloat(low[, high])

The FuzzyFloat fuzzer provides random float objects within a given inclusive range.

>>> FuzzyFloat(0.5, 42.7)
>>> fi.low, fi.high
0.5, 42.7

>>> fi = FuzzyFloat(42.7)
>>> fi.low, fi.high
0.0, 42.7

low

decimal, the inclusive lower bound of generated floats

high

decimal, the inclusive higher bound of generated floats

FuzzyDate

class factory.fuzzy.FuzzyDate(start_date[, end_date])

The FuzzyDate fuzzer generates random dates within a given inclusive range.

The end_date bound may be omitted, in which case it defaults to the current date:

>>> fd = FuzzyDate(datetime.date(2008, 1, 1))
>>> fd.start_date, fd.end_date
datetime.date(2008, 1, 1), datetime.date(2013, 4, 16)

start_date

datetime.date, the inclusive lower bound of generated dates

end_date

datetime.date, the inclusive higher bound of generated dates

FuzzyDateTime

class factory.fuzzy.FuzzyDateTime(start_dt, [end_dt, ]force_year=None, force_month=None, force_day=None, force_hour=None, force_minute=None, force_second=None, force_microsecond=None)

The FuzzyDateTime fuzzer generates random timezone-aware datetime within a given inclusive range.

The end_dt bound may be omitted, in which case it defaults to datetime.datetime.now() localized into the UTC timezone.

>>> fdt = FuzzyDateTime(datetime.datetime(2008, 1, 1, tzinfo=UTC))
>>> fdt.start_dt, fdt.end_dt
datetime.datetime(2008, 1, 1, tzinfo=UTC), datetime.datetime(2013, 4, 21, 19, 13, 32, 458487, tzinfo=UTC)

The force_XXX keyword arguments force the related value of generated datetimes:

>>> fdt = FuzzyDateTime(datetime.datetime(2008, 1, 1, tzinfo=UTC), datetime.datetime(2009, 1, 1, tzinfo=UTC),
...     force_day=3, force_second=42)
>>> fdt.evaluate(2, None, False)  # Actual code used by ``SomeFactory.build()``
datetime.datetime(2008, 5, 3, 12, 13, 42, 124848, tzinfo=UTC)

start_dt

datetime.datetime, the inclusive lower bound of generated datetimes

end_dt

datetime.datetime, the inclusive upper bound of generated datetimes

force_year

int or None; if set, forces the year of generated datetime.

force_month

int or None; if set, forces the month of generated datetime.

force_day

int or None; if set, forces the day of generated datetime.

force_hour

int or None; if set, forces the hour of generated datetime.

force_minute

int or None; if set, forces the minute of generated datetime.

force_second

int or None; if set, forces the second of generated datetime.

force_microsecond

int or None; if set, forces the microsecond of generated datetime.

FuzzyNaiveDateTime

class factory.fuzzy.FuzzyNaiveDateTime(start_dt, [end_dt, ]force_year=None, force_month=None, force_day=None, force_hour=None, force_minute=None, force_second=None, force_microsecond=None)

The FuzzyNaiveDateTime fuzzer generates random naive datetime within a given inclusive range.

The end_dt bound may be omitted, in which case it defaults to datetime.datetime.now():

>>> fdt = FuzzyNaiveDateTime(datetime.datetime(2008, 1, 1))
>>> fdt.start_dt, fdt.end_dt
datetime.datetime(2008, 1, 1), datetime.datetime(2013, 4, 21, 19, 13, 32, 458487)

The force_XXX keyword arguments force the related value of generated datetimes:

>>> fdt = FuzzyNaiveDateTime(datetime.datetime(2008, 1, 1), datetime.datetime(2009, 1, 1),
...     force_day=3, force_second=42)
>>> fdt.evaluate(2, None, False)  # Actual code used by ``SomeFactory.build()``
datetime.datetime(2008, 5, 3, 12, 13, 42, 124848)

start_dt

datetime.datetime, the inclusive lower bound of generated datetimes

end_dt

datetime.datetime, the inclusive upper bound of generated datetimes

force_year

int or None; if set, forces the year of generated datetime.

force_month

int or None; if set, forces the month of generated datetime.

force_day

int or None; if set, forces the day of generated datetime.

force_hour

int or None; if set, forces the hour of generated datetime.

force_minute

int or None; if set, forces the minute of generated datetime.

force_second

int or None; if set, forces the second of generated datetime.

force_microsecond

int or None; if set, forces the microsecond of generated datetime.

Custom fuzzy fields

Alternate fuzzy fields may be defined. They should inherit from the BaseFuzzyAttribute class, and override its fuzz() method.

class factory.fuzzy.BaseFuzzyAttribute

Base class for all fuzzy attributes.

fuzz(self)

The method responsible for generating random values. Must be overridden in subclasses.

Managing randomness

Using random in factories allows to “fuzz” a program efficiently. However, it’s sometimes required to reproduce a failing test.

factory.fuzzy uses a separate instance of random.Random, and provides a few helpers for this:

factory.fuzzy.get_random_state()

Call get_random_state() to retrieve the random generator’s current state.

factory.fuzzy.set_random_state(state)

Use set_random_state() to set a custom state into the random generator (fetched from get_random_state() in a previous run, for instance)

factory.fuzzy.reseed_random(seed)

The reseed_random() function allows to load a chosen seed into the random generator.

Custom BaseFuzzyAttribute subclasses SHOULD use factory.fuzzy._random as a randomness source; this ensures that data they generate can be regenerated using the simple state from get_random_state().