SeedFactory

A toolkit for test data generation.

The main idea of SeedFactory is to generate data in tests according to your application business logic (read as context functions if you use Phoenix Contexts) whenever possible and avoid direct inserts to the database (as opposed to ex_machina). This approach allows you to minimize testing of invalid states as you're not forced to keep complex database structure in your head in order to prepare test data. Even in cases where calling business logic functions is impractical (e.g. for performance reasons), SeedFactory serves as a centralized hub for test data creation, ensuring a consistent approach across your test suite. Dependent entities are resolved and created automatically, so you can focus on what matters for your test. The library is completely agnostic to the database toolkit.

See docs for details https://hexdocs.pm/seed_factory.

Installation

The package can be installed by adding seed_factory to your list of dependencies in mix.exs:

def deps do
  [
    {:seed_factory, "~> 0.7"}
  ]
end

Overview

This section provides a brief overview of the API. For comprehensive explanations please refer to docs.

To use the library, define a schema with commands that describe the processes of your application. When a command is executed it modifies the context by producing/updating/deleting entities.

Entities can have traits — labels that describe how an entity was created or what state it is in. Traits can build on each other using from (e.g. :active requires :pending first) and can be tied to specific argument values using args_pattern.

Schema example

defmodule MyApp.SeedFactorySchema do
  use SeedFactory.Schema

  command :create_company do
    param :name, generate: &Faker.Company.name/0

    resolve(fn args ->
      with {:ok, company} <- MyApp.Companies.create_company(args) do
        {:ok, %{company: company}}
      end
    end)

    produce :company
  end

  command :create_user do
    param :name, generate: &Faker.Person.name/0
    param :role, value: :normal
    param :company, entity: :company

    resolve(fn args -> MyApp.Users.create_user(args.company, args.name, args.role) end)

    produce :user
    produce :profile
  end

  command :activate_user do
    # with_traits ensures the user has the :pending trait before activation
    param :user, entity: :user, with_traits: [:pending]

    resolve(fn args ->
      user = MyApp.Users.activate_user!(args.user)

      {:ok, %{user: user}}
    end)

    update :user
  end

  # :pending is assigned when :create_user is executed
  trait :pending, :user do
    exec :create_user
  end

  # :active requires :pending first — :activate_user replaces :pending with :active
  trait :active, :user do
    from :pending
    exec :activate_user
  end

  # :admin and :normal are determined by the :role argument
  trait :admin, :user do
    exec :create_user, args_pattern: %{role: :admin}
  end

  trait :normal, :user do
    exec :create_user, args_pattern: %{role: :normal}
  end
end

Usage example

import SeedFactory

context = %{}
context = init(context, MyApp.SeedFactorySchema)

# Execute a command with automatically generated args
%{company: _} = exec(context, :create_company)

# Arguments can be passed explicitly
%{company: _, user: _, profile: _} =
  context
  |> exec(:create_company, name: "GitHub")
  |> exec(:create_user, name: "John Doe")
  |> exec(:activate_user)

# Dependencies are resolved automatically — :create_company runs implicitly
%{company: _, user: _} = exec(context, :create_user)

# produce/2 executes the full chain of commands for requested entities
%{company: _company} = produce(context, :company)
%{user: _user, company: _company} = produce(context, [:company, :user])

# Rebind entities to other names
%{profile1: _, user1: _} = produce(context, user: :user1, profile: :profile1)

# Specify traits — these two are equivalent
%{user: _user} = produce(context, user: [:admin, :active])

%{user: _user} =
  context
  |> exec(:create_user, role: :admin)
  |> exec(:activate_user)

# Combine traits with rebinding using :as option
%{active_admin: _} = produce(context, user: [:admin, :active, as: :active_admin])

Usage with ExUnit:

defmodule MyApp.MyTest do
  use ExUnit.Case
  use SeedFactory.Test, schema: MyApp.SeedFactorySchema

  describe "produce/1 macro" do
    produce [:company, user: [:active, :admin, as: :active_admin]]

    test "inspect data", %{company: company, active_admin: active_admin} do
      dbg(company)
      dbg(active_admin)
    end
  end


  describe "produce/2 and exec/3 functions" do
    test "demo #1", ctx do
      ctx =
        ctx
        |> exec(:create_company, name: "GitHub")
        |> produce(user: [:normal, :active])

      dbg(ctx)
    end

    test "demo #2", ctx do
      ctx
      |> produce(company: :company1, user: :user1, profile: :profile1)
      |> produce(company: :company2, user: :user2, profile: :profile2)
      |> dbg()
    end

    test "demo #3", ctx do
      ctx = produce(ctx, :company)
      ctx1 = ctx |> exec(:create_user, name: "John")
      ctx2 = ctx |> exec(:create_user, name: "Jane") |> exec(:activate_user)

      dbg(ctx1)
      dbg(ctx2)
    end
  end
end

Advanced features

Reusing dependencies with pre_exec / pre_produce

Create dependencies without executing the command itself. Useful when you need multiple variations sharing the same base:

# Create company without creating user
ctx = pre_produce(ctx, :user)

# Now create multiple users in the same company
%{user: user1} = produce(ctx, :user)
%{user: user2} = produce(ctx, :user)
# Both users belong to the same company

Dynamic trait matching with args_match and generate_args

For complex trait conditions that can't be expressed with simple args_pattern, use function-based matching:

trait :not_expired, :subscription do
  exec :create_subscription do
    args_match(fn args -> Date.compare(args.expires_at, Date.utc_today()) == :gt end)
    generate_args(fn -> %{expires_at: Date.add(Date.utc_today(), 30)} end)
  end
end

Trail tracking

The context maintains a history of how each entity was created and modified. Useful for debugging:

ctx = produce(ctx, user: [:admin, :active])
IO.inspect(ctx.__seed_factory_meta__)
# #SeedFactory.Meta<
#   current_traits: %{company: [], profile: [], user: [:admin, :active]},
#   trails: %{
#     company: #trail[:create_company],
#     profile: #trail[:create_user],
#     user: #trail[create_user: +[:pending, :admin] -> activate_user: +[:active] -[:pending]]
#   },
#   execution_history: [
#     #execution[produce(user: [:admin, :active]): create_company → create_user → activate_user]
#   ],
#   ...
# >