An Elixir library for generating test data. Define factories with deffactory, and FactoryMan generates functions for building params, structs, and database records.

Quick Start

defmodule MyApp.Factory do
  use FactoryMan, repo: MyApp.Repo

  alias MyApp.Users.User

  deffactory user(params \\ %{}), struct: User do
    base_params = %{username: "user-#{System.os_time()}"}

    Map.merge(base_params, params)
  end
end

Generated Functions

For a factory named :user with struct: User:

All functions accept optional params for customization. Insert functions also accept repo options. Each item in a list is evaluated independently (unique timestamps, sequences, etc.).

What gets generated depends on the options:

Params functions are derived from the built struct, so they exist for every struct factory — including body: :struct factories, whose body returns a struct directly.

How the functions relate (list variants omitted — each generated function also has a *_list counterpart that evaluates every item independently):

flowchart TD
    body["factory body<br/>(returns params map)"]
    struct_fn["build_user_struct/0,1<br/>params hooks → lazy eval → struct!/2 → struct hooks"]
    params_fn["build_user_params/0,1<br/>struct stripped to a clean map"]
    string_params_fn["build_user_string_params/0,1<br/>keys converted to strings"]
    insert_fn["insert_user/0,1,2<br/>insert hooks → Repo.insert!/2"]

    body --> struct_fn
    struct_fn --> params_fn
    params_fn --> string_params_fn
    struct_fn --> insert_fn

Defining Factories

The deffactory macro works like defining a function — specify a name, a parameter, and a body that returns a plain map. For struct factories, the map's keys must be fields of the struct (it is passed to struct!/2):

deffactory user(params \\ %{}), struct: User do
  base_params = %{username: "user-#{System.os_time()}"}

  Map.merge(base_params, params)
end

You can name the parameter anything, and use pattern matching:

deffactory user_from_config(%{username: username} = params), struct: User do
  base_params = %{username: username}

  Map.merge(base_params, params)
end

Struct vs. Non-Struct Factories

The struct: option controls both what functions are generated and how they're named:

# Struct factory — generates build_user_params, build_user_struct, insert_user, etc.
deffactory user(params \\ %{}), struct: User do
  base_params = %{username: "user-#{System.os_time()}"}
  Map.merge(base_params, params)
end

# Non-struct factory — generates build_api_payload and build_api_payload_list only
deffactory api_payload(params \\ %{}) do
  %{action: "create", data: params}
end

Non-struct factories use simplified names (build_* instead of build_*_params) because they can return any value — maps, strings, keyword lists, tuples, nil, etc.:

deffactory greeting(name \\ "world") do
  "Hello, #{name}!"
end

deffactory search_opts(overrides \\ []) do
  Keyword.merge([page: 1, per_page: 20], overrides)
end

Lazy evaluation works in keyword lists the same way it does in maps — 0-arity and 1-arity functions are resolved at build time. Non-map, non-keyword-list values are passed through unchanged.

Associations — resolve related records with assoc/4 (see the Cookbook):

deffactory author(params \\ %{}), struct: Author do
  base_params = %{name: "Test Author"}

  params = Map.put(params, :user, FactoryMan.assoc(params, :user, &build_user_struct/1, struct: User))

  Map.merge(base_params, params)
end

Resolve into params rather than into the defaults map: the final Map.merge gives params the last word, so a value resolved only in the defaults would be clobbered by the caller's raw input.

Params Functions

For struct factories, build_*_params and build_*_string_params build the struct and convert it to a clean map suitable for changesets or controller tests. For Ecto schemas, all Ecto metadata is stripped; for plain structs, the struct is converted with Map.from_struct/1:

# Returns %{username: "alice", first_name: nil, ...}
# (no __struct__, __meta__, autogenerated :id, or NotLoaded associations)
build_user_params(%{username: "alice"})

# Same but with string keys: %{"username" => "alice", ...}
build_user_string_params(%{username: "alice"})

belongs_to associations are removed from the output; if the association is persisted, the foreign key is set instead. Unlike ExMachina, nil values are preserved (a nil field may be intentional), and struct values like DateTime are left untouched.

Factory Options

Options cascade: parent module -> child module -> individual factory.

Module-level (set with use FactoryMan):

• :repo — Ecto repo for database operations
• :extends — Parent factory module to inherit configuration from
• :hooks — Hooks applied to all factories in the module
• :suppress_duplicate_option_warning — Suppress warnings for redundant options

Factory-level (set with deffactory):

• :struct — Ecto schema module (enables struct, params, and insert functions)
• :insert? — Set to false to skip insert functions
• :body — What the factory body returns: :params (default, a params map) or :struct (a struct built directly by the body). Params functions are generated either way (derived from the struct). Ignored for non-struct factories.
• :hooks — Merged with module-level hooks
• :strict — Reject unknown param keys at the factory boundary (see Strict Params below)
• :suppress_duplicate_option_warning — Suppress warnings for redundant options

Options that only apply to struct factories (:body, :strict) cascade harmlessly from the module level — they are ignored by non-struct factories.

Strict Params

Factories can silently ignore misspelled param keys: merge-style bodies surface the typo late (in struct!/2, with an unhelpful message), and body: :struct bodies — which read params selectively — never surface it at all. Opt in to strict: true to reject unknown keys up front:

deffactory user(params \\ %{}), struct: User, strict: true do
  base_params = %{username: FactoryMan.sequence("user")}

  Map.merge(base_params, params)
end

build_user_struct(%{usernme: "typo"})
# ** (ArgumentError) unknown params [:usernme] for strict factory :user ...

The check runs when building starts — before hooks and the factory body — against the keys of the :struct option's struct (which includes virtual fields and association keys). All derived functions (params builders, inserts, lists, and variants of the factory) are covered.

When a factory intentionally accepts keys that are not struct fields (e.g. an input used only to derive other fields), allow them explicitly:

deffactory invoice(params \\ %{}), struct: Invoice, strict: [allow: [:line_item_count]],
  body: :struct do
  %Invoice{total: Map.get(params, :line_item_count, 1) * 100}
end

Like other options, :strict can be set module-wide with use FactoryMan, strict: true and overridden per-factory (e.g. strict: false). Non-struct factories have no reference field set, so the option is ignored for them.

Hooks

Transform data at specific stages. Every factory action has both a before and after hook.

Hook Pipeline

Each generated function uses a subset of the pipeline. The full flow for insert_user is:

build_user_struct:
  before_build_params → [factory body + lazy eval] → after_build_params
  → before_build_struct → struct!() → after_build_struct

build_user_params (calls build_user_struct internally):
  → strip Ecto metadata (or Map.from_struct/1 for plain structs)

insert_user (calls build_user_struct internally):
  → before_insert → Repo.insert!() → after_insert

For non-struct factories, build_* runs before_build_params, the factory body with lazy evaluation, then after_build_params.

insert_user_struct/1,2 runs the same before_insert → insert → after_insert pipeline on an already-built struct — use it after modifying a built struct, so records are shaped consistently no matter how they were constructed. A raw Repo.insert!/2 would skip the insert hooks.

Hook Reference

Hook Precedence

Hooks can be set at three levels. Later levels override earlier ones for the same hook key:

1. Parent module — use FactoryMan, hooks: [...]
2. Child module — use FactoryMan, extends: Parent, hooks: [...]
3. Individual factory — deffactory name(params), hooks: [...]

Examples

Reset associations after insert:

defmodule MyApp.Factory do
  use FactoryMan,
    repo: MyApp.Repo,
    hooks: [after_insert: &__MODULE__.reset_assocs/1]

  def reset_assocs(struct) do
    Ecto.reset_fields(struct, struct.__struct__.__schema__(:associations))
  end
end

Log factory usage for debugging:

deffactory user(params \\ %{}), struct: User,
  hooks: [after_build_params: &__MODULE__.log_params/1] do
  base_params = %{username: "user-#{System.os_time()}"}

  Map.merge(base_params, params)
end

def log_params(params) do
  IO.inspect(params, label: "factory params")
  params
end

Factory Inheritance

Child factories inherit the parent's repo, hooks, and helper functions via :extends:

defmodule MyApp.Factory do
  use FactoryMan, repo: MyApp.Repo
  def generate_username, do: "user-#{System.os_time()}"
end

defmodule MyApp.Factory.Accounts do
  use FactoryMan, extends: MyApp.Factory

  deffactory user(params \\ %{}), struct: User do
    base_params = %{username: generate_username()}

    Map.merge(base_params, params)
  end
end

Inheritance chains are unlimited — a child factory can itself be extended.

Variant Factories (defvariant)

A variant wraps an existing base factory. It transforms the caller's params before passing them to the base factory. Think of it as a preprocessor: the variant runs first, then the base factory runs with the transformed params.

This ordering can be counterintuitive because the variant is defined after the base factory in your code, but its logic executes before the base factory at runtime:

Code order:     deffactory user(...)   ->  defvariant admin(...), for: :user
Execution order:  admin (preprocessor)  ->  user (base factory)

Example

deffactory user(params \\ %{}), struct: User do
  base_params = %{username: FactoryMan.sequence("user"), role: "member"}

  Map.merge(base_params, params)
end

defvariant admin(params \\ %{}), for: :user do
  base_params = %{role: "admin"}

  Map.merge(base_params, params)
end

Calling build_admin_user_struct() is equivalent to build_user_struct(%{role: "admin"}). Calling build_admin_user_struct(%{role: "superadmin"}) passes %{role: "superadmin"} to the base factory because the caller's params override the variant defaults.

Generated functions follow the pattern {variant}_{base}: build_admin_user_params/0,1, build_admin_user_struct/0,1, insert_admin_user/0,1,2, plus list variants.

Custom naming with :as

The :as option overrides the combined {variant}_{base} name:

defvariant moderator(params \\ %{}), for: :user, as: :mod do
  base_params = %{role: "moderator"}

  Map.merge(base_params, params)
end

This generates build_mod_struct/0,1, insert_mod/0,1,2, etc. — instead of the default build_moderator_user_struct.

Sequences

Generate unique values across builds:

FactoryMan.sequence("user")                                          # "user0", "user1", ...
FactoryMan.sequence(:email, fn n -> "user#{n}@example.com" end)     # custom formatter
FactoryMan.sequence(:role, ["admin", "moderator", "user"])           # cycles through list
FactoryMan.sequence(:order, fn n -> "ORD-#{n}" end, start_at: 1000) # custom start value

Reset in test setup: FactoryMan.Sequence.reset()

Lazy Evaluation

Functions in factory params are evaluated at build time. This works in both maps and keyword lists:

# In maps
%{
  created_at: fn -> DateTime.utc_now() end,               # 0-arity: called with no args
  display_name: fn user -> "#{user.username} (User)" end # 1-arity: receives parent map
}

# In keyword lists
[
  created_at: fn -> DateTime.utc_now() end,
  label: fn kw -> "timeout-#{kw[:timeout]}" end          # 1-arity: receives parent keyword list
]

Embedded Schemas

Factories for embedded schemas work like regular struct factories but without database insertion:

defmodule MyApp.Factories.Settings do
  use FactoryMan, extends: MyApp.Factory

  alias MyApp.Users.Settings

  deffactory settings(params \\ %{}), struct: Settings do
    base_params = %{
      theme: "dark",
      notifications: true
    }

    Map.merge(base_params, params)
  end
end

Embedded schemas generate build_*_params and build_*_struct functions only (as well as the matching *_list functions), but do not generate any insert_* functions.

Direct Struct Factories (body: :struct)

For complex factories that need full control over struct construction, set body: :struct. The factory body returns a struct directly instead of a params map:

deffactory invoice(params \\ %{}), struct: Invoice, body: :struct do
  customer =
    case params[:customer] do
      %Customer{} = customer -> customer
      _ -> MyApp.Factory.Accounts.insert_customer()
    end

  %Invoice{
    customer: customer,
    total: Map.get(params, :total, Enum.random(100..10_000))
  }
end

This generates the full function family, including build_invoice_params (derived from the built struct). The after_build_struct, before_insert, and after_insert hooks still run. The before_build_params, after_build_params, and before_build_struct hooks are skipped since there is no params-to-struct conversion stage.

body: :struct can also be set at the module level with use FactoryMan, body: :struct, then overridden per-factory with body: :params if needed. Non-struct factories in the same module are unaffected — their build_* functions are always generated.

Cookbook

Recipes for common patterns — building associations, post-build presets, validated presets — live in the Cookbook guide.

Duplicate Option Warnings

If a child factory module specifies an option that is already defined by its parent with the same value, FactoryMan will emit a compile-time warning. This helps catch redundant options that were likely copy-pasted from the parent.

To suppress the warning for a specific module or factory, add suppress_duplicate_option_warning: true to the options.

Reflection and Debugging

Every factory module gets a __factory_man__/1,2 reflection function:

iex> MyApp.Factory.__factory_man__(:opts)
[repo: MyApp.Repo]

iex> MyApp.Factories.Users.__factory_man__(:opts, :user)
[repo: MyApp.Repo, struct: User]

iex> MyApp.Factories.Users.__factory_man__(:factories)
[:user, :admin_user]

:factories lists every factory and variant registered in the module (variants under their full name), which enables runtime dispatch without string-building function names:

def build_any(factory_module, factory_name, params) do
  if factory_name not in factory_module.__factory_man__(:factories) do
    raise ArgumentError, "unknown factory #{inspect(factory_name)}"
  end

  apply(factory_module, :"build_#{factory_name}_struct", [params])
end