faker

Documentation

Overview

Package faker generates plausible values for factories and tests.

Why this is written here rather than taken from a library

One property decides it: a failing test has to be reproducible from the seed it printed. Every Faker this package hands out is driven by an explicitly seeded generator, so faker.New(42) yields the same sequence on every run, on every machine, forever. The package-level functions of math/rand and math/rand/v2 do not have that property -- they are seeded from the runtime -- and a library that reaches for them cannot be made to have it from outside.

The second reason is smaller and still real: the core of this collection carries one third-party dependency, and a name generator is not the one worth making it two.

What it is not

It is not a locale library and it will not become one. The word lists are small and English, chosen so that a generated row reads like a row rather than like a hash. A project that needs Portuguese street names writes its own Faker and passes it in -- which is what the interface is for.

Index

• type Faker
  • func New(seed int64) Faker

Types

type Faker

type Faker interface {
	// FirstName returns a given name.
	FirstName() string
	// LastName returns a family name.
	LastName() string
	// Name returns a full name.
	Name() string
	// UserName returns a handle: lowercase, no spaces.
	UserName() string
	// Email returns an address at a domain reserved for documentation, so a
	// seeded database cannot mail a stranger.
	Email() string
	// Word returns one word.
	Word() string
	// Sentence returns n words, capitalised, ending in a full stop.
	Sentence(words int) string
	// Paragraph returns n sentences.
	Paragraph(sentences int) string
	// Int returns a number in [min, max].
	Int(min, max int) int
	// Float returns a number in [min, max] rounded to decimals places.
	Float(min, max float64, decimals int) float64
	// Bool returns true half the time.
	Bool() bool
	// UUID returns a version 4 identifier.
	//
	// It is drawn from this Faker's generator, not from crypto/rand, because
	// reproducibility is the point here. It is fake data and must never be used
	// where an unguessable identifier is needed.
	UUID() string
	// Time returns an instant in [from, to], truncated to the second.
	Time(from, to time.Time) time.Time
	// Pick returns one of the options.
	Pick(options ...string) string
	// Unique returns a Faker that does not repeat a value it has already
	// answered for the same method.
	Unique() Faker
}

Faker is what a factory definition asks of a source of plausible values.

It is an interface so that a project can substitute its own, and it is small so that substituting one is an afternoon rather than a project. Anything not here is written in the definition, where the reader can see it.

func New

func New(seed int64) Faker

New returns a Faker seeded with seed.

The same seed yields the same sequence. That is the whole contract, and it is what makes a factory failure reproducible: the seed goes in the test output, and the run that reproduces it takes the seed back.