An Elixir library for generating test data. Define factories with deffactory, and FactoryMan generates functions for building params and structs, and inserting 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 and a plain params argument that defaults to an empty map, the following functions are available. Insert functions require a configured repo, a table-backed Ecto schema, and insert? not set to false.

Builders and insert_user accept factory params. insert_user_struct takes an existing %User{} instead. Insert functions also accept repo options. Each list item is built independently.

Zero-arity builders and inserts require a default argument in the factory head. For struct factories, count-only list functions pass %{} and are omitted when the head pattern-matches its argument. Non-struct count-only list functions require a default argument and use that default.

What gets generated depends on the factory configuration:

Value builders use build_<name> and build_<name>_list. Params builders include atom-keyed and string-keyed functions. Inserts require a configured repo and insert? not set to false. Setting body: :struct changes how the struct is built, not which function families are generated.

The diagram shows the build pipeline with body: :params. Configured :associations are normalized after before_build_params and before the factory body. Each function shown has a list counterpart that builds every item independently. insert_user_struct, not shown, starts at the insert pipeline and has no list counterpart:

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 defines a named factory with one argument and a body. With struct: and the default body: :params, return a plain map containing only fields of that struct. With body: :struct, return the struct directly. Without struct:, the body can return any value.

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 — configure nested params with the :associations option (see the Cookbook):

deffactory author(params \\ %{}), struct: Author, associations: [user: :user] do
  base_params = %{
    name: "Test Author",
    user: build_user_struct()
  }

  Map.merge(base_params, params)
end

The association key is resolved only when supplied by the caller. A nested params map becomes the associated struct, while an existing struct is reused. Missing keys continue to use the factory's ordinary base_params defaults.

Association targets are factory names, not schema names:

• associations: [user: :user] references a factory registered in the current module.
• associations: [user: {MyApp.AccountFactory, :user}] references another factory module.
• Registered variants can be targets using their full registered names.

Ecto supplies the related schema and cardinality. Factory references are checked at runtime, including when the caller omits an association key. A same-module target may therefore be declared later in the module. The atom shorthand does not search imported or ancestor modules; use an explicit module tuple for those factories.

Wrong struct types, invalid list members, and incorrectly typed builder results raise. Only configured keys are normalized. Direct Ecto associations are supported; embeds and through associations are not. Normalization calls struct builders, not insert functions.

Factory defaults remain ordinary Elixir expressions: eager default builders run even when overridden. Use existing lazy attributes when a default should only be built if retained. FactoryMan does not automatically build omitted relationships or prevent recursion caused by mutually recursive default builders.

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, its foreign key is set instead. Ordinary fields retain nil values, but nil embeds are omitted. Struct values such as 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

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
• :associations — Keyword list mapping Ecto association keys to FactoryMan factories. Use an atom for a same-module factory or {FactoryModule, :factory} across modules. Ecto supplies the associated schema and cardinality; caller-provided nested params are normalized before the factory body runs.
• :strict — Reject unknown param keys at the factory boundary (see Strict Params below)

Options that only apply to struct factories (:body, :associations, :strict) cascade from the module level. :body and :strict are ignored by non-struct factories; non-empty :associations requires an Ecto-backed struct factory.

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:
  strict validation → before_build_params → configured association normalization
  → [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

With body: :struct, configured associations are normalized after strict validation and before the body. Params-stage hooks remain skipped. Variants preprocess input before delegating to the base builder, which performs normalization. insert_*_struct receives an already-built struct and does not run association normalization.

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 sequential values or cycle through a list:

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_*_struct, build_*_params, and build_*_string_params, plus their matching *_list functions. They do not generate 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

A practical progression from a first factory through realistic defaults, variants, associations, suite organization, hooks, strict params, and advanced presets lives in the Cookbook guide.

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