Ecto's own guide, Test factories, starts from this premise:
Many projects depend on external libraries to build their test data. Some of those libraries are called factories because they provide convenience functions for producing different groups of data. However, given Ecto is able to manage complex data trees, we can implement such functionality without relying on third-party projects.
The guide has you write a test/support/factory.ex module by hand: a build/1 clause per
schema, build/2 to override fields, and insert!/2 to persist through your Repo.
NeoFaker is not a factory library. It knows nothing about Ecto.Schema, builds no structs, and
never touches a Repo. Its job is narrower: given a field, produce a realistic-looking value for
it, such as a name, an email, a date, or a UUID. It belongs to the same category as Ruby's
Faker or JavaScript's Faker.js. It slots into the build/1 clauses from Ecto's guide instead
of replacing them.
Usage
The factory's shape doesn't change. NeoFaker only replaces the right-hand side of each field:
defmodule MyApp.Factory do
alias MyApp.Repo
def build(:user) do
%MyApp.User{
email: NeoFaker.Internet.email(),
username: NeoFaker.Internet.username(),
full_name: NeoFaker.Person.full_name()
}
end
def build(:post) do
%MyApp.Post{
title: NeoFaker.Lorem.sentence(),
body: NeoFaker.Lorem.paragraphs(3) |> Enum.join("\n\n"),
inserted_at: NeoFaker.Date.past(30)
}
end
def build(:post_with_comments) do
%MyApp.Post{
title: NeoFaker.Lorem.sentence(),
comments: [
build(:comment),
build(:comment)
]
}
end
def build(:comment) do
%MyApp.Comment{body: NeoFaker.Lorem.sentence()}
end
def build(factory_name, attributes) do
factory_name |> build() |> struct!(attributes)
end
def insert!(factory_name, attributes \\ []) do
factory_name |> build(attributes) |> Repo.insert!()
end
endbuild(:post), build(:post, title: "custom title"), and insert!(:post) all work exactly as
described in Ecto's guide. The only difference is that the values come from NeoFaker instead of
being hardcoded.
Ecto's own examples use fixed placeholders, such as title: "hello world". That's enough to show
the pattern, but every generated record ends up with the same shape, so formatting, length, or
encoding edge cases never show up in a real test suite. NeoFaker fixes that: it returns a
different, realistic value on each call, across more domains than are worth writing by hand:
NeoFaker.Person, NeoFaker.Address, NeoFaker.Date, NeoFaker.Time, NeoFaker.Internet,
NeoFaker.Lorem, NeoFaker.Color, NeoFaker.Crypto, and more. See the Cheat Sheet
for the full list.
Generating unique values
NeoFaker guarantees realism, not uniqueness. It draws from a finite, locale-specific dataset (see
Supported Locales) and keeps no record of what it has already returned, so
NeoFaker.Person.first_name() can return the same value on two separate calls.
Ecto already has a complete answer for uniqueness, and NeoFaker isn't part of it: a
unique_index enforces it at the database level, and Ecto.Changeset.unique_constraint/3 turns
a violation into an ordinary changeset error. Ecto's guide also uses System.unique_integer/1
for factory emails and usernames. That's a different tool for a different job: it keeps test data
from colliding with itself by accident, rather than enforcing anything. Keep using it for that,
and use NeoFaker only for the part of the value that doesn't need to be unique:
def build(:user) do
%MyApp.User{
email: "#{NeoFaker.Internet.username()}+#{System.unique_integer([:positive])}@example.com",
full_name: NeoFaker.Person.full_name()
}
endNeoFaker.Internet.username/1 and NeoFaker.Internet.email/1 accept a number: true option
that appends a random suffix. That lowers the odds of a collision for quick scripts or seed data,
but the suffix is still random, not unique. Use System.unique_integer/1 wherever a value must
not collide.
Setup
Add NeoFaker as a dev/test-only dependency:
def deps do
[
{:neo_faker, "~> 0.15.0", only: [:dev, :test]}
]
endIf the factory module lives under test/support/, that directory must be compiled in the
:test environment. A Phoenix app generated with mix phx.new already wires this up, so there's
nothing to do there.
For a plain Mix project, add it yourself in mix.exs:
def project do
[
# ...
elixirc_paths: elixirc_paths(Mix.env())
]
end
defp elixirc_paths(:test), do: ["lib", "test/support"]
defp elixirc_paths(_), do: ["lib"]This applies to the factory pattern itself, not just NeoFaker.
Set a default locale for tests in config/test.exs (see
Getting Started for the full configuration guide,
including notes for Phoenix projects):
config :neo_faker, locale: :default