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 section):

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

  params = Map.put(params, :user, 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
• :suppress_duplicate_option_warning — Suppress warnings for redundant options

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 (most common hook usage):

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: 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:

sequence("user")                                          # "user0", "user1", ...
sequence(:email, fn n -> "user#{n}@example.com" end)     # custom formatter
sequence(:role, ["admin", "moderator", "user"])           # cycles through list
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

Building associations

Use assoc/4 to let callers pass a prebuilt association, params to build one from, or nothing at all:

deffactory post(params \\ %{}), struct: Post do
  base_params = %{title: sequence("post")}

  params =
    Map.put(params, :author, assoc(params, :author, &build_author_struct/1, struct: Author))

  Map.merge(base_params, params)
end

build_post_struct()                          # builds a default author
build_post_struct(%{author: my_author})      # reuses the given struct
build_post_struct(%{author: %{name: "Ann"}}) # builds an author from params

In merge-style factories, resolve into params (as above), not into the defaults map — the final Map.merge would clobber a resolved default with the caller's raw input. Factories with body: :struct don't merge, so they can use assoc/4 directly in field position.

The struct: option raises on a struct of the wrong type — without it, a mistyped value would be reused silently. See assoc/4 for the full semantics (:inherit defaults, optional associations via on_nil: :keep and on_missing: nil) and assoc_list/4 for has_many-style lists.

When the schema only needs a foreign key (and the record must exist), insert the association and use its ID:

deffactory comment(params \\ %{}), struct: Comment do
  base_params = %{
    body: "Nice post!",
    post_id: Map.get_lazy(params, :post_id, fn -> insert_post().id end)
  }

  Map.merge(base_params, params)
end

Post-build presets

Variants preprocess params — they cannot transform the built value. When a preset needs to derive fields from the built struct, define a separate factory with body: :struct whose body calls the base build function and transforms the result:

deffactory anonymized_user(params \\ %{}), struct: User, body: :struct do
  user = build_user_struct(params)

  %{user | email: "redacted+#{user.id}@example.com", display_name: "anonymous"}
end

Unlike a hand-written build_anonymized_user/1 function, this keeps the whole generated family: build_anonymized_user_params, the _list builders, and insert_anonymized_user all come for free.

One caveat: an after_build_struct hook runs twice — once inside the base build call and once for the wrapping factory. Insert hooks run once (only the wrapping factory's insert is called).

Validated presets

A variant that promises a property of its result ("this post is always published") can be silently broken by caller params. To make the promise explicit, assert it over the merged result and raise:

defvariant published(params \\ %{}), for: :post do
  base_params = %{published_at: DateTime.utc_now(), draft: false}
  result_params = Map.merge(base_params, params)

  if Post.published?(result_params),
    do: result_params,
    else: raise("params contradict the published preset")
end

A misuse like build_published_post_struct(%{draft: true}) now fails at the factory boundary instead of producing a self-contradictory record. The same shape works in the opposite polarity (a draft variant raising when the params imply a published post).

Note the check runs on raw params, before lazy evaluation — the predicate cannot see resolved values of lazy (function) fields.

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