Built-in Generators

Here are the list of built-in generators that Fox provides. They are either generators of a particular data type or provide computation on top of other generators.

Data Generators

There are many data generators provided for generating data. Most of these generators shrink to zero:

  • Numerically zero (or as close as possible)
  • Empty collection (or at least shrunk items)
Function Generates Description
FOXInteger NSNumber * Generates random integers
FOXPositiveInteger NSNumber * Generates random zero or positive integers
FOXNegativeInteger NSNumber * Generates random zero or negative integers
FOXStrictPositiveInteger NSNumber * Generates random positive integers (non-zero)
FOXStrictNegativeInteger NSNumber * Generates random negative integers (non-zero)
FOXChoose NSNumber * Generates random integers between the given range (inclusive)
FOXFloat NSNumber * Generates random floats. WARNING: currently does not stably shrink to 0.
FOXDouble NSNumber * Generates random doubles. WARNING: currently does not stably shrink to 0.
FOXDecimalNumber NSNumber * Generates random decimal numbers. WARNING: currently does not stably shrink to 0.
FOXReturn id Always returns the given value. Does not shrink
FOXTuple NSArray * Generates random fixed-sized arrays of generated values. Values generated are in the same order as the generators provided.
FOXTupleOfGenerators NSArray * Generates random fixed-sized arrays of generated values. Values generated are in the same order as the generators provided.
FOXArray NSArray * Generates random variable-sized arrays of generated values.
FOXArrayOfSize NSArray * Generates random fixed-sized arrays of generated values. Values generated are in the same order as the generators provided.
FOXArrayOfSizeRange NSArray * Generates random variable-sized arrays of generated values. Array size is within the given range (inclusive).
FOXDictionary NSDictionary * Generates random dictionries of generated values. Keys are known values ahead of time. Specified in @{<key>: <generator>} form.
FOXSet NSSet * Generates random sets of a given generated values.
FOXCharacter NSString * Generates random 1-length sized character string. May be an unprintable character.
FOXAlphabetCharacter NSString * Generates random 1-length sized character string. Only generates alphabetical letters.
FOXNumericCharacter NSString * Generates random 1-length sized character string. Only generates digits.
FOXAlphanumericCharacter NSString * Generates random 1-length sized character string. Only generates alphanumeric.
FOXAsciiCharacter NSString * Generates random 1-length sized character string. Only generates ascii characters.
FOXString NSString * Generates random variable length strings. May be an unprintable string.
FOXStringOfLength NSString * Generates random fixed length strings. May be an unprintable string.
FOXStringOfLengthRange NSString * Generates random length strings within the given range (inclusive). May be an unprintable string.
FOXAsciiString NSString * Generates random variable length strings. Only generates ascii characters.
FOXAsciiStringOfLength NSString * Generates random fixed length strings. Only generates ascii characters.
FOXAsciiStringOfLengthRange NSString * Generates random variable length strings within the given range (inclusive). Only generates ascii characters.
FOXAlphabeticalString NSString * Generates random variable length strings. Only generates alphabetical characters.
FOXAlphabeticalStringOfLength NSString * Generates random fixed length strings. Only generates alphabetical characters.
FOXAlphabeticalStringOfLengthRange NSString * Generates random variable length strings within the given range (inclusive). Only generates alphabetical characters.
FOXAlphanumericalString NSString * Generates random variable length strings. Only generates alphabetical characters.
FOXAlphanumericalStringOfLength NSString * Generates random fixed length strings. Only generates alphanumeric characters.
FOXAlphanumericalStringOfLengthRange NSString * Generates random variable length strings within the given range (inclusive). Only generates alphanumeric characters.
FOXNumericalString NSString * Generates random variable length strings. Only generates numeric characters.
FOXNumericalStringOfLength NSString * Generates random fixed length strings. Only generates numeric characters.
FOXNumericalStringOfLengthRange NSString * Generates random variable length strings within the given range (inclusive). Only generates numeric characters.
FOXSimpleType id Generates random simple types. A simple type does not compose with other types. May not be printable.
FOXPrintableSimpleType id Generates random simple types. A simple type does not compose with other types. Ensured to be printable.
FOXCompositeType id Generates random composite types. A composite type composes with the given generator.
FOXAnyObject id Generates random simple or composite types.
FOXAnyPrintableObject id Generates random printable simple or composite types.

Computation Generators

Also, you can compose some computation work on top of data generators. The resulting generator adopts the same shrinking properties as the original generator.

Function Description
FOXMap Applies a block to each generated value.
FOXBind Applies a block to the lazy tree that the original generator creates. See Building Generators section for more information.
FOXResize Overrides the given generator’s size parameter with the specified size. Prevents shrinking.
FOXOptional Creates a new generator that has a 25% chance of returning nil instead of the provided generated value.
FOXFrequency Dispatches to one of many generators by probability. Takes an array of tuples (2-sized array) - @[@[@probability_uint, generator]]. Shrinking follows whatever generator is returned.
FOXSized Encloses the given block to create generator that is dependent on the size hint generators receive when generating values.
FOXSuchThat Returns each generated value iff it satisfies the given block. If the filter excludes more than 10 values in a row, the resulting generator assumes it has reached maximum shrinking.
FOXSuchThatWithMaxTries Returns each generated value iff it satisfies the given block. If the filter excludes more than the given max tries in a row, the resulting generator assumes it has reached maximum shrinking.
FOXOneOf Returns generated values by randomly picking from an array of generators. Shrinking is dependent on the generator chosen.
FOXForAll Asserts using the block and a generator and produces test assertion results (FOXPropertyResult). Shrinking tests against smaller values of the given generator.
FOXForSome Like FOXForAll, but allows the assertion block to “skip” potentially invalid test cases.
FOXCommands Generates arrays of FOXCommands that satisfies a given state machine.
FOXExecuteCommands Generates arrays of FOXExecutedCommands that satisfies a given state machine and executed against a subject. Can be passed to FOXExecutedSuccessfully to verify if the subject conforms to the state machine.

Warning

Using FOXSuchThat and FOXSuchThatWithMaxTries are “filter” generators and can lead to significant waste in test generation by Fox. While it gives you the most flexibility the kind of generated data, it is the most computationally expensive. Use other generators when possible.

Debugging Functions

Fox comes with a handful of functions that can help you diagnose generator problems.

Function Description
FOXSample Samples 10 values that generator produces.
FOXSampleWithCount Samples a number of values that a generator produces.
FOXSampleShrinking Samples 10 steps of shrinking from a value that a generator produces.
FOXSampleShrinkingWithCount Samples a number of steps of shrinking from a value that a generator produces.