Hex.pm Version Hex.pm Downloads Elixir CI

NeoFaker is a fake data generator for Elixir tests and development environments.

Requirements

  • Erlang: 28.0 or newer
  • Elixir: 1.18.4-otp-28 or newer

Installation

Add NeoFaker to your mix.exs dependencies:

def deps do
  [
    {:neo_faker, "~> 0.15.0", only: [:dev, :test]}
  ]
end

Then fetch the dependency:

mix deps.get

Configuration

Set the default locale in config/config.exs:

config :neo_faker, locale: :default

If the requested locale isn't available, NeoFaker falls back to :default (generic English US data). See supported locales for the full list.

NeoFaker.Locale.set/1 changes the locale for the calling process only. It never touches config :neo_faker, locale: ..., so other processes, including concurrent async: true tests, keep using their own locale. Use it for a quick script or a single test. Use config for a locale that should apply to the whole application.

Phoenix Projects

For Phoenix apps, set the locale in config/dev.exs or config/test.exs instead. In test/test_helper.exs, add:

ExUnit.start()
NeoFaker.start()

If you use NeoFaker inside a test/support/factory.ex module to build fake Ecto.Schema structs for your tests, see Ecto Test Factories. It covers wiring NeoFaker into the factory pattern from Ecto's own guide, and how to keep factory-generated values unique where your schema requires it.

Usage

Every function lives under a domain module such as NeoFaker.Person, NeoFaker.Internet, or NeoFaker.Date. There's no single catch-all module:

iex> NeoFaker.Person.full_name()
"Abigail Bethany Crawford"

iex> NeoFaker.Internet.email()
"josé@example.com"

iex> NeoFaker.App.description()
"Fake data generator for Elixir tests and development environments."

iex> NeoFaker.App.description(locale: :id_id)
"Penghasil data palsu untuk pengujian dan lingkungan pengembangan Elixir."

Most functions accept a keyword list of options to control the output shape. Check each function's own documentation for the options it supports:

iex> NeoFaker.Person.age(18, 65)
42

iex> NeoFaker.Color.hex(format: :eight_digit)
"#613583FF"

Reproducible output

NeoFaker draws values via Enum.random/1 and :rand.uniform/1, both backed by :rand, which Erlang/OTP seeds automatically and unpredictably per process. For deterministic output, for example when snapshot-testing against a fixed value, seed it explicitly at the start of a test:

setup do
  NeoFaker.seed(12_345)
end

Next steps

  • Cheat Sheet, a one-page reference of every domain generator function with examples, grouped by domain.
  • Locale Cheat Sheet, the same kind of reference for locale-exclusive generators, grouped by locale.
  • Supported Locales, covering the list of available locales and how locale resolution works across processes, config, and per-call overrides.
  • Ecto Test Factories, for wiring NeoFaker into a test/support/factory.ex module for Ecto.Schema-based tests.
  • Adding a Locale, a contributor guide for submitting a new locale as a pull request.
  • API Reference, the full module and function documentation.

License

Licensed under the MIT License.