1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
# factory_bot_rails [![Code Climate][grade-image]][grade] [![Gem Version][version-image]][version]
[factory_bot][fb] is a fixtures replacement with a straightforward definition
syntax, support for multiple build strategies (saved instances, unsaved
instances, attribute hashes, and stubbed objects), and support for multiple
factories for the same class (`user`, `admin_user`, and so on), including factory
inheritance.
### Transitioning from factory\_girl\_rails?
Check out the [guide](https://github.com/thoughtbot/factory_bot/blob/4-9-0-stable/UPGRADE_FROM_FACTORY_GIRL.md).
## Rails
factory\_bot\_rails provides Rails integration for [factory_bot][fb].
Supported Rails versions are listed in [`Appraisals`](Appraisals). Supported
Ruby versions are listed in [`.github/workflows/build.yml`](.github/workflows/build.yml).
## Download
Github: http://github.com/thoughtbot/factory_bot_rails
Gem:
$ gem install factory_bot_rails
## Configuration
Add `factory_bot_rails` to your Gemfile in both the test and development groups:
```ruby
group :development, :test do
gem 'factory_bot_rails'
end
```
You may want to configure your test suite to include factory\_bot methods; see
[configuration](https://github.com/thoughtbot/factory_bot/blob/main/GETTING_STARTED.md#configure-your-test-suite).
### Automatic Factory Definition Loading
By default, factory\_bot\_rails will automatically load factories
defined in the following locations,
relative to the root of the Rails project:
```
factories.rb
test/factories.rb
spec/factories.rb
factories/*.rb
test/factories/*.rb
spec/factories/*.rb
```
You can configure by adding the following to `config/application.rb` or the
appropriate environment configuration in `config/environments`:
```ruby
config.factory_bot.definition_file_paths = ["custom/factories"]
```
This will cause factory\_bot\_rails to automatically load factories in
`custom/factories.rb` and `custom/factories/*.rb`.
It is possible to use this setting to share factories from a gem:
```rb
begin
require 'factory_bot_rails'
rescue LoadError
end
class MyEngine < ::Rails::Engine
config.factory_bot.definition_file_paths +=
[File.expand_path('../factories', __FILE__)] if defined?(FactoryBotRails)
end
```
You can also disable automatic factory definition loading entirely by
using an empty array:
```rb
config.factory_bot.definition_file_paths = []
```
### File Fixture Support
Factories have access to [ActiveSupport::Testing::FileFixtures#file_fixture][]
helper to read files from tests.
To disable file fixture support, set `file_fixture_support = false`:
```rb
config.factory_bot.file_fixture_support = false
```
[ActiveSupport::Testing::FileFixtures#file_fixture]: https://api.rubyonrails.org/classes/ActiveSupport/Testing/FileFixtures.html#method-i-file_fixture
### Generators
Including factory\_bot\_rails in the development group of your Gemfile
will cause Rails to generate factories instead of fixtures.
If you want to disable this feature, you can either move factory\_bot\_rails out
of the development group of your Gemfile, or add the following configuration:
```ruby
config.generators do |g|
g.factory_bot false
end
```
If fixture replacement is enabled and you already have a `test/factories.rb`
file (or `spec/factories.rb` if using rspec_rails), generated factories will be
inserted at the top of the existing file.
Otherwise, factories will be generated in the
`test/factories` directory (`spec/factories` if using rspec_rails),
in a file matching the name of the table (e.g. `test/factories/users.rb`).
To generate factories in a different directory, you can use the following
configuration:
```ruby
config.generators do |g|
g.factory_bot dir: 'custom/dir/for/factories'
end
```
Note that factory\_bot\_rails will not automatically load files in custom
locations unless you add them to `config.factory_bot.definition_file_paths` as
well.
The suffix option allows you to customize the name of the generated file with a
suffix:
```ruby
config.generators do |g|
g.factory_bot suffix: "factory"
end
```
This will generate `test/factories/users_factory.rb` instead of
`test/factories/users.rb`.
For even more customization, use the `filename_proc` option:
```ruby
config.generators do |g|
g.factory_bot filename_proc: ->(table_name) { "prefix_#{table_name}_suffix" }
end
```
To override the [default factory template][], define your own template in
`lib/templates/factory_bot/model/factories.erb`. This template will have
access to any methods available in `FactoryBot::Generators::ModelGenerator`.
Note that factory\_bot\_rails will only use this custom template if you are
generating each factory in a separate file; it will have no effect if you are
generating all of your factories in `test/factories.rb` or `spec/factories.rb`.
Factory\_bot\_rails will add a custom generator:
```shell
rails generate factory_bot:model NAME [field:type field:type] [options]
```
[default factory template]: https://github.com/thoughtbot/factory_bot_rails/tree/main/lib/generators/factory_bot/model/templates/factories.erb
## Contributing
Please see [CONTRIBUTING.md](CONTRIBUTING.md).
factory_bot_rails was originally written by Joe Ferris and is maintained by thoughtbot. Many improvements and bugfixes were contributed by the [open source
community](https://github.com/thoughtbot/factory_bot_rails/graphs/contributors).
## License
factory_bot_rails is Copyright © 2008 Joe Ferris and thoughtbot. It is free
software, and may be redistributed under the terms specified in the
[LICENSE](LICENSE) file.
<!-- START /templates/footer.md -->
## About thoughtbot
This repo is maintained and funded by thoughtbot, inc.
The names and logos for thoughtbot are trademarks of thoughtbot, inc.
We love open source software!
See [our other projects][community].
We are [available for hire][hire].
[community]: https://thoughtbot.com/community?utm_source=github
[hire]: https://thoughtbot.com/hire-us?utm_source=github
<!-- END /templates/footer.md -->
[fb]: https://github.com/thoughtbot/factory_bot
[grade]: https://codeclimate.com/github/thoughtbot/factory_bot_rails
[grade-image]: https://codeclimate.com/github/thoughtbot/factory_bot_rails.svg
[community]: https://thoughtbot.com/community?utm_source=github
[hire]: https://thoughtbot.com/hire-us?utm_source=github
[version-image]: https://badge.fury.io/rb/factory_bot_rails.svg
[version]: https://badge.fury.io/rb/factory_bot_rails
[hound-image]: https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg
[hound]: https://houndci.com
|
