An Elixir library for generating test data. Define factories with deffactory, and FactoryMan generates functions for building params and structs, and inserting 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: FactoryMan.sequence("user")}

    Map.merge(base_params, params)
  end
end

Generated Functions

For a factory named :user with struct: User and a params argument that defaults to an empty map:

The insert functions use the default insert target, the repo's insert!/2, which requires a configured repo and a table-backed Ecto schema (see Insert Targets). Each list item is built independently. insert_user_struct has no list counterpart.

Every builder takes options after its params (build_user_struct/2, build_user_struct_list/3, and so on). The only builder option is variants: (see Variant Factories). Insert functions take one keyword list: FactoryMan uses :variants, and every other option is passed to the insert target unchanged. The *_struct insert forms take no variants:, since the struct is already built:

insert_user(%{username: "alice"}, variants: [:admin], returning: true, prefix: "tenant_a")
#                                 └─ FactoryMan ───┘  └─ Ecto (Repo.insert!/2) ───────┘

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 are build_<name> and build_<name>_list. Any struct factory also gets an insert_<name>_via_<target> family for each insert_via: target. body: :struct changes how the struct is built, not which functions are generated.

Disabling function families

disable: switches off function families that a test suite does not use. true disables a family, and false enables an inherited one again:

use FactoryMan, repo: MyApp.Repo, disable: [string_params: true, insert_list: true]

deffactory user(params \\ %{}), struct: User, disable: [string_params: false] do
  Map.merge(%{username: FactoryMan.sequence("user")}, params)
end

• :params and :string_params are independent: build_*_string_params does not use build_*_params, so either can be disabled alone.
• Everything else is always generated. build_*_struct cannot be disabled, since every other family builds on it, and inserts are switched off with insert: and insert_via:.
• disable: cascades per key, and variants follow their base factory. false on a family that is not disabled has no effect.
• A key for the other kind of factory (:non_struct_list on a struct factory, or any other key on a non-struct factory) raises when written on the factory itself, whatever its value, and is ignored when inherited.
• A disabled function's name is free: the module can define a function with that name.

Defining Factories

deffactory defines a named factory with one argument and a body. With struct: and the default body: :params, the body returns a map of that struct's fields (a key that is not a field raises, naming it). With body: :struct, it returns the struct itself. Without struct:, the body can return any value, and the factory generates only build_<name> and build_<name>_list:

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

The argument can have any name, and can pattern-match (%{username: _} = params). Merge the params yourself, last, so the caller's values win: FactoryMan does not merge them for you.

Associations

Declare association builders with assocs: (Ecto schema struct: only). Each declared key is resolved before the body, so the body always receives it resolved, and the final Map.merge(base_params, params) stays correct:

deffactory author(params \\ %{}), struct: Author, assocs: [user: &build_user_struct/1] do
  base_params = %{name: "Author of #{params.user.username}"}

  Map.merge(base_params, params)
end

A builder is a 1-arity function (a local or remote capture, or an anonymous function), a 2-arity function (params, factory_params), or {builder, options}. The builder is the default: an absent key is built with %{} (a list key with []), so a base_params default for a declared key is never used.

• Keys must be direct associations; embeds and :through associations are not supported. Supplied structs and builder results must be the related schema (a singular builder may return nil, unless the key is required: true).
• default: value is what an absent key is treated as: nil or a params map for a singular association, a list of params maps for a plural one. It is evaluated on every build, even when the caller supplies the key, so keep it a literal. A record at an association position inside default: raises.
• required: true (singular keys only, not with default: nil) raises when the key resolves to nil, from the caller, a before_build_params hook, or the builder. It does not check the finished struct.
• Keys resolve top to bottom. A 2-arity builder's factory_params holds the caller's params with the keys declared above it resolved; the current key and the keys below it are hidden, and undeclared keys are visible as given. See Chain associations.
• A self-referential or mutually recursive default build raises instead of recursing forever. This includes recursion that would stop on its own while the key stays absent. Declare such a key with default: nil (or default: []), or pass a value at each level. See Avoid recursive defaults.
• assocs: is evaluated at build time, like the body, and the factory's params variable is not in scope there. The declaration is validated when the factory first builds.
• assoc/3,4 and assoc_list/3,4 apply the same rules to one key, for helper functions and values computed in the body (without required: or the schema check). They return the resolved value without changing the params, so put it back (or drop the key) before the final merge.

Params Functions

For struct factories, build_*_params and build_*_string_params build the struct and convert it to a clean map for changesets or controller tests. For Ecto schemas, Ecto metadata, autogenerated IDs, and unloaded associations are removed; plain structs are converted with Map.from_struct/1:

build_user_params(%{username: "alice"})         # %{username: "alice", first_name: nil, ...}
build_user_string_params(%{username: "alice"})  # %{"username" => "alice", ...}

Fields whose value is nil are kept, so a changeset test sees a nil field as given, not as absent; nil embeds are omitted. belongs_to associations are removed, and their foreign key is set when the associated record is persisted. 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, :extends (the parent factory module), :hooks, :insert, :insert_via, :disable, :body, :strict, and :struct.

Factory-level (set with deffactory):

• :struct - The struct or Ecto schema to build (enables struct, params, and insert functions)
• :body - What the body returns: :params (default) or :struct. Ignored for non-struct factories.
• :assocs - Association builders (see Associations). Factory-level only.
• :strict - true, false, or [allow: [...]] (see Strict Params). Ignored for non-struct factories.
• :hooks - Chained with the module's hooks (see Hooks)
• :repo - Overrides the module's repo
• :insert and :insert_via - The default and named insert targets (see Insert Targets)
• :disable - Function families to switch off (see Disabling function families)

Variant-level (set with defvariant): :for, :as, :extends, :assocs, and, for a variant without a body, :defaults and :force (see Variant Factories). Unknown options raise at every level.

Insert Targets

An insert target is the function that inserts a built struct. The default target, set with insert:, is used by insert_*, insert_*_list, and insert_*_struct:

• :ecto (the default) - the repo's insert!/2. Generated for a table-backed Ecto schema when a repo is configured; otherwise nothing is generated. Written on a factory that cannot be inserted with Ecto, it raises.
• false - no default insert functions.
• A remote capture of arity 2, such as &MyApp.Factory.put!/2 - generated for any struct factory: plain structs, embedded schemas, and Ecto schemas. Anonymous functions and local captures raise.

insert_via: adds named targets, each with its own family of functions:

use FactoryMan, repo: MyApp.Repo, insert_via: [search: &MyApp.Factory.index!/2]

deffactory user(params \\ %{}), struct: User do
  Map.merge(%{username: FactoryMan.sequence("user")}, params)
end

insert_user()                        # MyApp.Repo.insert!/2, with the insert hooks
insert_user_via_search()             # MyApp.Factory.index!/2
insert_user_via_search_list(3)
insert_user_struct_via_search(user)

An insert function receives the built struct and the caller's options (without :variants), and returns the inserted struct. A store that takes no options ignores them: def index!(struct, _opts).

• insert: and insert_via: cascade like other options. insert_via: merges by name: a lower level adds a target, replaces the inherited target of the same name, or removes it with name: false (removing a target that is not inherited raises). The name ecto is reserved.
• insert: false removes the default family only; insert_via: targets remain. disable: [insert_list: true] removes the list functions of both.
• The insert hooks (before_insert, after_insert) run for the default target, not for insert_via: targets. A target that needs more steps does them in its own function.
• Captures and targets do not run the :ecto insert's already-inserted check (see Hook Pipeline).
• A target receives the struct with any built associations still in place. The :ecto insert cascades them; a capture or target stores them only if its function does. An after_build_struct hook applies to every family.
• Variants get their base factory's targets, building through the variant.
• Both options apply to struct factories only: written on a non-struct factory they raise, and inherited ones are ignored.

The Cookbook has recipes for inserting into other stores.

Strict Params

strict: true catches params that a factory silently ignores. It runs two checks:

1. Unknown keys, when building starts (before hooks and the body): every key must be a key of the :struct option's struct, which includes virtual fields and association keys.
2. Ignored or changed params, after the body and its lazy values (before after_build_params): every field in the params that entered the body (after before_build_params and assocs:) must come out of the body with the same value, compared with ==. A plain map has been kept when each of its keys has been kept, including when the body builds a struct such as an embed from it. Function values and association keys are not checked.

deffactory user(params \\ %{}), struct: User, strict: true do
  %{username: "default"}
end

build_user_struct(%{username: "alice"})
# ** (ArgumentError) strict factory :user in MyApp.Factory ignored or changed params it was given:
#
#      :username - given "alice", built "default"
#    ...

Both checks cover every derived function. The second check runs in the base factory's body, so it sees what the variants pass on; a variant body that drops a caller's key is not checked.

strict: [allow: [...]] exempts keys from both checks: a key that is not a field may be passed (e.g. an input used only to derive other fields), and a field may be changed by the body. An allowed key that is not a field must not reach the struct, so the body removes it (here with Map.pop/3):

deffactory invoice(params \\ %{}), struct: Invoice, strict: [allow: [:line_item_count]] do
  {count, params} = Map.pop(params, :line_item_count, 1)

  Map.merge(%{total: count * 100}, params)
end

Set it once in a base factory (use FactoryMan, strict: true); a factory can override it. It is ignored for non-struct factories.

Hooks

Hooks transform data at specific stages. Every stage has a before and an after hook.

Hook Pipeline

build_user_struct:
  params validation → before_build_params → assocs: resolution
  → [factory body + lazy eval] → strict params check → 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

• The insert hooks belong to the default insert target's functions (insert_*, insert_*_list, and insert_*_struct). insert_via: targets run no hooks.
• With body: :struct, the params-stage hooks (before_build_params, after_build_params, and before_build_struct) are skipped; assocs: are resolved after params validation, and the returned struct is lazily evaluated.
• For non-struct factories, build_* runs before_build_params, the body with lazy evaluation, then after_build_params.
• insert_user_struct/1,2 runs the insert pipeline on an already-built struct (it does not resolve associations). Use it after modifying a built struct, so records are shaped the same way however they were built; a raw Repo.insert!/2 skips the insert hooks. With the :ecto insert, it raises on a struct that has already been inserted (or deleted). To insert a copy on purpose, mark it as built first: Ecto.put_meta(struct, state: :built).

Hook Reference

A hook is a 1-arity remote capture such as &__MODULE__.my_hook/1, or a list of them, run in order (after_insert: [&M.reset/1, &M.log/1]). Hooks are compiled into the generated functions, so anything else, such as an anonymous function, raises at compile time. See the Cookbook for recipes.

Hook Order

Hooks can be set at three levels, and a hook set at a lower level is chained with the hooks it inherits instead of replacing them:

1. Parent module - use FactoryMan, hooks: [...]
2. Child module - use FactoryMan, extends: Parent, hooks: [...] (any number of levels)
3. Individual factory - deffactory name(params), hooks: [...]

The order is onion-style, like middleware: the parent wraps the child. For a before_* hook the parent's runs first, and for an after_* hook the parent's runs last.

To place a hook (or a list of hooks) explicitly, pass {hook, placement}:

"Parent" means everything inherited for that hook name, from every level above. Each level is resolved against the list built so far. For example, with after_insert:

# Parent module:       after_insert: &P.hook/1                      -> [P]
# Child module:        after_insert: {&C.hook/1, :after_parent}     -> [P, C]
# Factory:             after_insert: &F.hook/1                      -> [F, P, C]

Each hook receives the previous hook's result. The same hook set at two levels runs twice. On a module with no parent, a placement behaves like a plain hook. To switch off the inherited hooks for one factory, use hooks: [after_insert: {[], :replace_parent}]; an empty list with any other placement raises. Unknown hook names and a hook name set twice at one level raise.

Factory Inheritance

A child module inherits its parent's options (repo, hooks, insert targets, strict:, ...) and can call the parent's helper functions unqualified (here, a generate_username/0 defined in MyApp.Factory). Chains can be any length:

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

  deffactory user(params \\ %{}), struct: User do
    Map.merge(%{username: generate_username()}, params)
  end
end

Variant Factories (defvariant)

A variant is a preprocessor for a base factory: its body runs first, on the caller's params, and passes the result to the base factory:

defvariant admin(params \\ %{}), for: :user do
  Map.merge(%{role: "admin"}, params)
end

build_admin_user_struct()   # same as build_user_struct(%{role: "admin"})

• Its functions are named {variant}_{base} (build_admin_user_struct, insert_admin_user, ...), with the base factory's full family. as: :mod renames them (build_mod_struct); the variant is still listed as :admin in variants: and extends:.
• for: must name a factory. A variant is defined after its base factory, in the same module, and variant names are unique per factory.
• Params last (Map.merge(%{role: "admin"}, params)) makes the variant's values defaults, which the caller can override. Params first (Map.merge(params, %{banned: true})) forces them: they win over the caller and over later variants. See Choose defaults or forced values.

Variants without a body

A variant that only sets values can declare them instead of writing a body:

defvariant admin, for: :user, defaults: %{role: "admin"}
defvariant banned, for: :user, force: %{banned: true}
defvariant banned_admin, for: :user, extends: [:admin, :banned]

• defaults: is merged under the params (Map.merge(defaults, params)), so the caller wins. force: is merged over them (Map.merge(params, force)), so the variant wins. With both, a key in both is taken from force:.
• A variant without a body needs defaults:, force:, extends:, or assocs:, and its head takes no argument (admin or admin()). defaults: and force: with a do block raise.
• defaults: and force: are code, evaluated on every build like a body, so they can call functions (defaults: admin_defaults()); each must evaluate to a map. Lazy values in them reach the base factory as params and are resolved there.
• With assocs:, the values are merged first and the associations resolved after, so a defaults: value for a declared key is what the variant's builder builds from.
• Any base factory works, as long as its params are maps.
• A variant without a body never drops a caller's key, so the base factory's strict check sees every key the caller passed.
• To keep mix format from adding parentheses, add :factory_man to import_deps in .formatter.exs. import_deps needs the dependency in the environment mix format runs in (only: [:dev, :test]); otherwise add defvariant: 2 to your own locals_without_parens.

Combining variants with variants:

Every generated function of a factory takes a variants: option, which applies several variants in one build:

build_user_struct(%{}, variants: [:admin, :confirmed])
insert_user(%{}, variants: [:admin], returning: true)

List variants by their defvariant name (:admin, not :admin_user). For variants that merge params last, the caller's params win, then a later variant wins over an earlier one. The chain runs from the last variant to the base factory, so a later variant's values reach an earlier one as params. A variant's own functions count the variant as the first in the list: build_admin_user_struct(params, variants: [:confirmed]) is build_user_struct(params, variants: [:admin, :confirmed]). An unknown variant name raises and lists the known variants.

Building on other variants with extends:

A variant builds on other variants of the same factory with extends:, and wins over them:

defvariant senior(params \\ %{}), for: :user, extends: [:admin] do
  Map.merge(%{title: "Senior admin"}, params)
end

A listed variant brings the variants it extends, and each variant is applied once, at its first position in the list, so a variant wins over the variants it extends whatever the list order. A variant is defined after the variants it extends. A variant with only extends: and no body gives a recurring combination a name (see Variants without a body).

Sequences

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

FactoryMan.Sequence.reset/0 clears every counter, for every test. Tests that run at the same time share the counters, so in async tests reset only the sequence names that test uses: FactoryMan.Sequence.reset(:invoice_number).

Lazy Evaluation

Functions in a body's map or keyword list are evaluated at build time. Other values are passed through unchanged:

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

Embedded Schemas

A factory for an embedded schema generates the struct and params builders. It has no table, so it gets insert functions only from an insert: capture or insert_via: targets:

deffactory settings(params \\ %{}), struct: MyApp.Users.Settings do
  Map.merge(%{theme: "dark", notifications: true}, params)
end

Direct Struct Factories (body: :struct)

With body: :struct, the body returns the struct itself, for factories that need full control over construction. The full function family is still generated, including build_*_params, and lazy values in the struct are resolved. It can be set at the module level and overridden per factory:

deffactory invoice(params \\ %{}), struct: Invoice, body: :struct do
  %Invoice{total: Map.get(params, :total, 100), customer: build_customer_struct()}
end

Cookbook

The Cookbook is a practical progression from a first factory through realistic defaults, variants, associations, suite organization, hooks, strict params, insert targets, and advanced presets.

Reflection and Debugging

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

iex> MyApp.Factory.__factory_man__(:opts)
[disable: [], insert_via: [], insert: :ecto, repo: MyApp.Repo]

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

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

iex> MyApp.Factories.Users.__factory_man__(:variants, :user)
[:admin]

• :opts shows the resolved options, including each hook name's list in run order, the resolved insert: and insert_via:, and the disabled families (disable:). assocs: is code evaluated at build time, so it does not appear.
• :factories lists every factory and variant in the module (variants under their full name), for runtime dispatch without building function names from strings.
• :variants lists a factory's variants by the names that variants: and extends: accept.