The highest tagged major version is
Documentation
¶
Overview ¶
Package fake provides generic test data generation utilities for creating fake instances of any type.
Every builder here generates from the same options: numbers start at 1 rather than 0, and recursion is bounded to DefaultRecursionDepth. The bound is a property of the package rather than of the entry point, so which of BuildFake, MustBuildFake and BuildFakeForTest a caller reaches for does not change what a fake costs to build. The ToDepth builders take another bound for callers who want the nested graph populated.
Index ¶
- Constants
- func BuildFake[X any]() (*X, error)
- func BuildFakeForTest[X any](t *testing.T) *X
- func BuildFakeForTestToDepth[X any](t *testing.T, depth uint) (x *X)
- func BuildFakeForType[X any](opts ...options.OptionFunc) (x *X)
- func BuildFakeID() string
- func BuildFakeNumber() float64
- func BuildFakePage[T any](build func() *T) *filtering.QueryFilteredResult[T]
- func BuildFakePageOfSize[T any](size int, build func() *T) *filtering.QueryFilteredResult[T]
- func BuildFakePassword() string
- func BuildFakeRecord[X any](opts ...options.OptionFunc) *X
- func BuildFakeString() string
- func BuildFakeTime() time.Time
- func BuildFakeToDepth[X any](depth uint) (x *X, err error)
- func MustBuildFake[X any]() X
- func MustBuildFakeToDepth[X any](depth uint) X
Constants ¶
const DefaultPageSize = 3
DefaultPageSize is how many elements BuildFakePage puts in a page.
Three, because the properties a list test is usually after — that the elements are distinct, that they arrive in order, that a count matches — need more than one and are no better shown by a hundred.
const DefaultRecursionDepth uint = 0
DefaultRecursionDepth is the recursion bound every builder in this package applies unless the caller names another one.
faker bounds recursion per type rather than per level: it counts how many times each type already appears on the path down to the value it is filling, and writes a zero instead of recursing once that count exceeds the bound. At 0 a type that reaches itself — directly, or around a cycle through other types — is filled once, and the field that would repeat it is left zero.
That is one below faker's own default of 1, and the difference is not one level. Every extra level is multiplied by the slices on the way down to it: a struct holding a slice of itself yields on the order of twenty values at 0 and seventy at 1, and it is the faked type's shape rather than anything the caller wrote that decides the multiplier. Callers who want the nested graph populated ask for it by depth, through the ToDepth builders.
Variables ¶
This section is empty.
Functions ¶
func BuildFake ¶
BuildFake builds a fake instance of the given type. Recursion is bounded to DefaultRecursionDepth; the caller who wants a deeper graph reaches for BuildFakeToDepth.
func BuildFakeForTest ¶
BuildFakeForTest builds a fake instance of the given type for a test, failing the test on error. Recursion is bounded to DefaultRecursionDepth; the caller who wants a deeper graph reaches for BuildFakeForTestToDepth.
func BuildFakeForTestToDepth ¶
BuildFakeForTestToDepth builds a fake instance of the given type for a test with recursion bounded to depth, failing the test on error.
func BuildFakeForType ¶
func BuildFakeForType[X any](opts ...options.OptionFunc) (x *X)
BuildFakeForType builds a fake instance of the given type with the caller's faker options applied over this package's, panicking on error.
The builders above decide everything for the caller, which is the right trade for a value handed straight to an assertion and the wrong one for a type whose shape faker cannot infer. The two that come up are a field typed any, which faker refuses to fill and reports as an error for the whole value, and a slice of a struct that holds slices, whose length faker picks at random up to a hundred at every level and so multiplies: a graph three collections deep costs seconds to build and is discarded by the caller that only wanted the root. Both are answered by an option — an option this package would otherwise have to grow a named parameter for, once per knob.
So this is the escape hatch, and it is deliberately the whole of faker's rather than a curated few: a caller reaching past the defaults knows something about its own types that this package does not, and enumerating what it may know in advance is a guess that would need revisiting every time it turned out wrong.
It panics rather than returning an error for the same reason MustBuildFake does: the failures are structural facts about the type, so a fake that cannot be built cannot be built on any run, and a test is the place that is discovered.
func BuildFakeID ¶
func BuildFakeID() string
BuildFakeID builds a fake identifier of the kind this platform issues.
A random string is not one: identifiers are what rows join on, so a fake carrying twenty-five random letters where an identifier goes is a row that joins to nothing, and the test that fails is several layers away from the fake that caused it.
func BuildFakeNumber ¶
func BuildFakeNumber() float64
BuildFakeNumber builds a whole number from the range generated numeric fields draw from.
Whole for the reason BuildFakeRecord rounds the floats it generates: the columns these values round-trip through mostly keep two decimal places, and one that keeps fewer than the value does returns something the caller did not save.
func BuildFakePage ¶
func BuildFakePage[T any](build func() *T) *filtering.QueryFilteredResult[T]
BuildFakePage builds a page of fakes from the builder for one of them.
A service that lists something has a test that needs a page of it, so every domain that lists anything grows one of these per type, and they are all the same function with the element type changed. What varies is the builder to call, which is what this takes.
func BuildFakePageOfSize ¶
func BuildFakePageOfSize[T any](size int, build func() *T) *filtering.QueryFilteredResult[T]
BuildFakePageOfSize builds a page of the given size from the builder for one element, for the test whose subject is the size.
The counts describe the page rather than a store behind it: a page of n elements reports n filtered and n total, which is what a caller reading the response would conclude. A test about a page that is a window onto something larger sets the counts it means.
They are marked known, because a fake page is one that was answered. A test whose subject is the other case — a store that had no row to read its counts off — wants filtering.NewQueryFilteredResultWithoutCounts rather than this.
func BuildFakePassword ¶
func BuildFakePassword() string
BuildFakePassword builds a fake password.
Long, because the rule a password is usually checked against is a minimum length, and a fake that fails it turns every test that registers a user into a test of validation.
func BuildFakeRecord ¶
func BuildFakeRecord[X any](opts ...options.OptionFunc) *X
BuildFakeRecord builds a fake X shaped like something this platform stores.
The builders above hand back what faker produced, which for a type that is written to a database and read back is not quite a usable value: an identifier field gets random letters, a timestamp gets sub-second precision in local time, and every pointer and slice gets filled, which is the opposite of what an optional field and a child collection mean to the store. A caller then either fixes all of that by hand, which is the composite literal they were trying to stop writing, or writes tests that fail for reasons that have nothing to do with the code under test.
So the value is generated and then walked, and what comes back is:
- a field named like an identifier holds a real identifier
- a time.Time is truncated to the second and in UTC
- a pointer, slice, map or interface is nil
- a float is a whole number
- everything else is what faker produced
What that leaves for the caller is the fields whose values the type constrains — a status from a closed set, a URL that has to resolve, a minimum that has to be below its maximum — which are the fields worth reading in a builder anyway.
The caller's options are applied over the two this needs, so an option named here can still be overridden; see BuildFakeForType for why order settles that. It panics for the reason MustBuildFake does.
func BuildFakeString ¶
func BuildFakeString() string
BuildFakeString builds a fake string for a field that holds prose — a name, a description, a note.
A sentence rather than a single word, because these values are read in failure messages, and six words drawn from a list are far likelier to be distinguishable than two fakes that both say "quo".
func BuildFakeTime ¶
BuildFakeTime builds a fake time, truncated to the second and in UTC.
It draws from the same library every other builder here does. A second faker was pulled in for this one function, and two generators mean two seeds and two notions of what a random value is — which is a surprising amount of machinery for "an arbitrary timestamp".
Truncated because these values round-trip through columns that do not all keep sub-second precision, and a fake that survives a save but not a reload fails an equality assertion for a reason that has nothing to do with the code under test.
func BuildFakeToDepth ¶
BuildFakeToDepth builds a fake instance of the given type with recursion bounded to depth.
func MustBuildFake ¶
func MustBuildFake[X any]() X
MustBuildFake builds a fake instance of the given type, panicking on error. Recursion is bounded to DefaultRecursionDepth; the caller who wants a deeper graph reaches for MustBuildFakeToDepth.
func MustBuildFakeToDepth ¶
MustBuildFakeToDepth builds a fake instance of the given type with recursion bounded to depth, panicking on error.
Types ¶
This section is empty.
Source Files