fake-rs: plausible fake data for Rust tests, in fourteen locales

What the crate actually generates

fake is a Rust library and a command line tool for producing fake data, and the scope is wide enough that the README lists it rather than describing it. There are name generators that produce first names, last names, titles and full names with a title, address generators covering city prefixes and suffixes, street names, secondary address types, zip codes, post codes, building numbers, time zones, state names and abbreviations, and geographic values including latitude, longitude and geohash. There are text generators, with words, sentences, paragraphs, lists, block quotes, links, code fragments and lorem style output, and commercial ones, with product names, adjectives, materials, departments, prices, promotion codes, descriptions and barcodes. Around that sit identifiers and technical values, IP and MAC addresses, user agents, ISBN and ISIN numbers, IBAN codes, currency details, semantic versions, colour notations in several models, file system paths and mime types, and dates and times. It is closer to a data catalogue than to a random string generator.

Adding the crate and choosing features

The dependency goes into a Cargo manifest like any other, and the derive feature is the one most projects want:

[dependencies]
fake = { version = "5", features = ["derive"] }

The rest of the feature flags are opt-in integrations with other crates, and the list is long enough to be worth reading before you add them, because each one pulls a dependency into your build. There are flags for chrono and chrono-tz, for http, ulid, ferroid, uuid, bigdecimal, rust_decimal, random_color, geo, semver, serde_json, time, zerocopy, glam, url, indexmap and either. Two flags deserve special attention. always-true-rng exposes a generator whose random source always returns true, and maybe-non-empty-collections uses it to generate collections that are guaranteed to have at least one element. That is a useful trick for testing code paths that assume a non-empty list, and it is also the kind of option that produces a green test suite and a broken production assumption if it leaks out of the test code.

The derive macro and the Faker

The API has two halves. The derive half lets a plain struct be filled in, and the README example shows the shape of it, with a field level attribute that overrides the generator for one field:

use fake::{Dummy, Fake, Faker};

#[derive(Debug, Dummy)]
pub struct Foo {
    #[dummy(faker = "1000..2000")]
    order_id: usize,
    customer: String,
    paid: bool,
}

fn main() {
    let f: Foo = Faker.fake();
    println!("{:?}", f);
}

Beyond the struct form, the Faker can produce a value of any type that implements the trait, including a tuple of primitives, and a range can be used as the source, so a string of a given length or a number inside a numeric range can be generated directly. There is also a macro for nested collections, which builds a vector of vectors with a chosen shape, and that is the piece that keeps a fixture from looking like a flat list of the same row.

Reproducible output with a seeded generator

A fake data library is only useful in tests if it can be made to produce the same output twice, and fake handles that by accepting the random source as a parameter. The README shows a standard random number generator constructed from a fixed seed array and then used to produce a value five times, each call passing the generator into a method on the Faker. The practical effect is that a test can assert on exact values, or a developer can regenerate the fixture that caused a failure last month. The alternative, letting the global generator pick the seed, gives you variety between runs at the cost of reproducibility. The choice is per call site rather than global, which is the right design, because most fixtures do not need to be deterministic while a handful of regression tests do.

Locale data is the part most libraries skip

The crate supports fourteen locales, and the codes are the ones you would expect from the data set names, English, French, Arabic, Traditional Chinese, Simplified Chinese, Japanese, Brazilian and European Portuguese, German, Italian, Welsh, Dutch and Persian. In the library the locale is an argument, so a name generator is called with the locale it should draw from, and the example shows the same generator producing an English name and then a Traditional Chinese one. The convenience path is a separate module per locale, where a words generator takes a length range and returns a vector of strings without the locale in the call. This matters more than it sounds. A test fixture for a European product that contains Chinese names will pass the parser and fail a human reviewer, and a form that validates a name against a country specific rule set will behave differently once the locale matches the market the product serves.

The command line tool exposes the same generators

The binary is installed from the repository with a feature flag, which is how a project keeps a command line tool out of a library dependency:

cargo install --features=cli --git https://github.com/cksac/fake-rs.git

Once installed, the fake command exposes a subcommand per generator, and the help output in the README is the complete list, from CityPrefix and CountryName through Word, Sentence and Paragraph, through PhoneNumber, Ip, UserAgent, CreditCardNumber, Isbn, Semver, CurrencyCode, Bic, HexColor, RgbColor, Time and DateTime, to the commerce family with product names, prices, promotion codes and barcodes. Two options shape the output, a repeat count and a locale, and the locale option is what makes a quick non-English fixture possible:

fake -r5 -lzh_cn Name

Individual generators also take their own arguments, and the example shows the password generator with a minimum length, which is the kind of detail that decides whether the tool is useful for filling a password field in a fixture.

The workspace and the two crates inside it

The repository is a Cargo workspace with two members, the fake library itself and dummy_derive, the procedural macro crate that implements the derive. Splitting the macro into its own crate is the standard arrangement, because a derive macro has to be compiled as a separate proc macro and the two then have separate dependency trees, which keeps a user who does not want the derive from paying for it. The workspace uses the second resolver and declares a release profile with long thin optimisation and a single codegen unit, so the published binary benefits from better inlining than the default release settings would give. The documentation is published to the standard Rust documentation site, and the project keeps a separate documentation directory for material that does not belong in the generated API pages. The tree also carries both an Apache licence file and an MIT licence file, the usual dual licence arrangement in the Rust ecosystem, even though the project's licence field names the Apache terms.

Where fake data is the wrong tool

The limitation is not a bug, it is the nature of the thing. The output is structurally valid and internally consistent, which is exactly what a parser needs, and it is patterned in ways a person notices, which is exactly what a real dataset does not do. A name generator will produce a name from a list, a phone number will respect a national format without corresponding to a subscriber, and an address will have a street that does not exist. So the tool is right for a test fixture, a development seed and a documentation sample, and wrong for a demo that has to survive a technical reader, a load test that needs realistic distributions, or a privacy exercise where the data has to look real. The always-true-rng option adds a second trap, since a generator that always succeeds will hide a code path that fails on empty input, and that failure will then appear in production rather than in the test run.

Editorial conclusion

The fake crate fits a Rust project that needs test fixtures, seed data for a development database or sample records for documentation, and it fits a team that wants the same fixture in several languages, since the locale data is the point of the crate rather than an afterthought. It does not fit a case where the data has to be plausible to a person rather than to a parser, since the output is patterned and will not survive contact with a careful reviewer. Before adopting it, check which feature flags you enable, because each one pulls in a dependency, and read the documentation for the always-true-rng option before using it anywhere outside a test.

Frequently asked questions

Official sources

1. cksac/fake-rs on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases