Share FactoryBot data safely across RSpec examples
Features · Installation · Quick Start · Usage · Configuration · How It Works
FactoryHoist creates FactoryBot records once at the smallest shared RSpec example-group boundary, then gives every example an isolated in-memory copy. ActiveRecord changes are isolated with savepoints and rolled back when the group exits.
- Hoists referenced FactoryBot records to the nearest shared RSpec group
- Preserves object relationships while returning an isolated copy to each example
- Rolls back example and group changes with ActiveRecord savepoints
- Falls back to example-local creation for dynamic or unsupported declarations
- Seeds factory and Faker values deterministically for hoisted declarations
- Accelerates simple callback-free FactoryBot builds
- Reports hoist candidates, unused declarations, degradation, and materialization cost
- Clones PostgreSQL and SQLite databases safely for parallel workers
Add FactoryHoist to the test group in your Gemfile:
group :test do
gem "factory_hoist"
endThen install:
bundle install- Ruby 3.2+
- FactoryBot 6.5+
- ActiveRecord 7.1+ for database-backed features
- RSpec 3.12+ or Minitest 5+
Load FactoryHoist from your test helper:
require "factory_hoist"Declare shared factories with hoist:
RSpec.describe Order do
hoist(:company)
hoist(:user) { {company: company} }
context "paid" do
hoist(:order) { {user: user, state: :paid} }
it "can update its isolated copy" do
order.update!(state: :cancelled)
expect(order.state).to eq("cancelled")
end
it "preserves relationships" do
expect(order.user).to equal(user)
end
end
endThe declaration name is used as the FactoryBot factory name by default. FactoryHoist creates each hoisted record once, rolls example changes back, and lazily copies the visible object graph for each example.
Pass an alternate factory name, traits, and attributes after the declaration name:
hoist(:admin, :user, :admin, active: true)A declaration block returns dynamic attributes and can reference ancestor declarations:
hoist(:account)
hoist(:owner) { {account: account} }FactoryHoist mirrors FactoryBot's direct APIs and preserves their block behavior:
FactoryHoist.build(:user)
FactoryHoist.create(:user)
FactoryHoist.build_list(:user, 3)
FactoryHoist.create_list(:user, 3)Simple callback-free builds are compiled to a Ruby file under the system temporary directory and bypass FactoryBot's evaluation pipeline. Traits, callbacks, required constructors, and unsupported definitions automatically fall back to FactoryBot.
Run the fixed-condition benchmark with:
bundle exec ruby bench/fast_build.rbunsafe_bulk_insert uses FactoryBot's attributes_for and ActiveRecord's insert_all!:
FactoryHoist.unsafe_bulk_insert(:user, 10_000)It intentionally skips validations and callbacks, so use it only for performance tests and seed data.
Run the selected RSpec suite and report repeated literal factory calls, unused hoists, degradation, and the most expensive materializations:
bundle exec factory_hoist advise spec/Runtime counters are also available through FactoryHoist.stats.to_h.
Clone a disconnected PostgreSQL template under an advisory lock, or a SQLite database through SQLite's online backup API:
FactoryHoist.clone_database(
source: "postgresql:///app_test_template",
target: "app_test_1",
adapter: :postgresql
)Configure FactoryHoist in your test helper:
FactoryHoist.configure do |config|
config.subxid_budget = 60
config.suite_seed = ENV.fetch("FACTORY_HOIST_SEED", 0).to_i
config.paranoid_mode = false
end| Option | Type | Default | Description |
|---|---|---|---|
factory_adapter |
Callable | nil |
Override FactoryBot for custom factory backends |
paranoid_mode |
Boolean | false |
Reject changes to hoisted ActiveRecord rows inside an example |
subxid_budget |
Integer | 60 |
Rebuild an owned outer transaction after this many examples |
suite_seed |
Integer | 0 |
Seed deterministic declaration and Faker values |
Set subxid_budget to 0 to disable rebuilding. Rebuilding is deferred while an active before(:context) hook has written database state that FactoryHoist cannot rematerialize; move that setup into hoist when the budget must remain strict.
- Scheduler Analysis inspects selected RSpec examples and finds referenced declarations
- LCA Placement schedules each declaration at the nearest shared example-group boundary
- Group Materialization creates the records inside an outer transaction and group savepoint
- Example Isolation opens a savepoint and lazily copies the visible object graph for each example
- Rollback discards example changes immediately and group data when the group exits
- Safe Degradation creates values locally when static scheduling or copying is unsafe
- Minitest accepts the same DSL but creates values once per test because it has no portable example-group lifecycle.
- Declarations that use example-local helpers, instance variables,
initialize_with, orto_createare created inside the example transaction instead of being shared. after_commitdoes not fire inside the managed transaction.- Objects that
Marshalcannot copy use example-local creation and increment the degradation counter. - DatabaseCleaner truncation is incompatible and emits a warning; use its transaction strategy.
- System specs need a shared database connection. Multi-database applications are not supported.
- Raw SQL and
update_allare rolled back between examples but can still create ordering effects inside one example.
Install dependencies and run the test suite:
bundle install
bundle exec rakeRun the performance gates:
bundle exec ruby bench/fast_build.rb
bundle exec ruby bench/phase0_synthetic.rbWith a local PostgreSQL server available, verify the subtransaction budget, database statistics, failure recovery, and clone paths:
DATABASE_URL=postgresql:///postgres bundle exec ruby script/verify_postgresql
bundle exec ruby script/verify_postgresql_cloneThe design-to-implementation review is recorded in docs/adversarial-audit.md, and the reproducible synthetic benchmark is recorded in docs/phase0-synthetic.md.
Bug reports and pull requests are welcome at https://github.com/ydah/factory_hoist.
Released under the MIT License.