Skip to content
Newer
Older
100644 295 lines (193 sloc) 7.98 KB
4dade1a @notahat Started taking notes for the README.
authored Jun 15, 2010
1 # Machinist 2
2
634ec69 @notahat More documentation scribblings.
authored Jun 19, 2010
3 *Fixtures aren't fun. Machinist is.*
4
67c6b28 @notahat Encourage the use of Machinist 2.
authored Jun 19, 2011
5 Machinist 2 is **still in beta**!
6
7 If you're using Rails 3, you'll want to give Machinist 2 a go, but be aware
8dcfcaa @notahat Slowly getting the docs in place.
authored Jun 19, 2011
8 that the documentation is still patchy.
67c6b28 @notahat Encourage the use of Machinist 2.
authored Jun 19, 2011
9
10 That said, have a look at [the
11 specs](https://github.com/notahat/machinist/tree/master/spec), starting with
12 [the spec for
13 Machinable](https://github.com/notahat/machinist/blob/master/spec/machinable_spec.rb).
14 No, really, have a look. I wrote this code to be read, and the specs do a
15 pretty clean job of documenting what it all does.
16
17 If, on the other hand, you want the tried, tested, and well-documented official
18 release version of Machinist, [then go with Machinist
3761daa @notahat Added a link back to Machinist 1 to the readme.
authored Jul 7, 2010
19 1](http://github.com/notahat/machinist/tree/1.0-maintenance).
20
df75114 @notahat README had a link to the old machinist2 branch.
authored Jul 7, 2010
21 - [Home page](http://github.com/notahat/machinist)
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
22 - [Google group](http://groups.google.com/group/machinist-users), for support
8dcfcaa @notahat Slowly getting the docs in place.
authored Jun 19, 2011
23 - [Bug tracker](http://github.com/notahat/machinist/issues), for reporting Machinist bugs
634ec69 @notahat More documentation scribblings.
authored Jun 19, 2010
24
966d19e @notahat Moved more stuff from the README to the wiki.
authored Jun 26, 2010
25
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
26 ## Introduction
634ec69 @notahat More documentation scribblings.
authored Jun 19, 2010
27
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
28 Machinist makes it easy to create objects for use in tests. It generates data
d0f0941 @notahat Documentation.
authored Jul 4, 2010
29 for the attributes you don't care about, and constructs any necessary
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
30 associated objects, leaving you to specify only the fields you care about in
31 your test. For example:
634ec69 @notahat More documentation scribblings.
authored Jun 19, 2010
32
ba72241 @notahat Working my way through documenting everything.
authored Jun 20, 2010
33 describe Comment do
34 it "should not include spam in the without_spam scope" do
d0f0941 @notahat Documentation.
authored Jul 4, 2010
35 # This will make a Comment, a Post, and a User (the author of the
36 # Post), generate values for all their attributes, and save them:
ba72241 @notahat Working my way through documenting everything.
authored Jun 19, 2010
37 spam = Comment.make!(:spam => true)
634ec69 @notahat More documentation scribblings.
authored Jun 19, 2010
38
ba72241 @notahat Working my way through documenting everything.
authored Jun 19, 2010
39 Comment.without_spam.should_not include(spam)
40 end
634ec69 @notahat More documentation scribblings.
authored Jun 19, 2010
41 end
42
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
43
ba72241 @notahat Working my way through documenting everything.
authored Jun 19, 2010
44 You tell Machinist how to do this with blueprints:
634ec69 @notahat More documentation scribblings.
authored Jun 19, 2010
45
ba72241 @notahat Working my way through documenting everything.
authored Jun 19, 2010
46 require 'machinist/active_record'
634ec69 @notahat More documentation scribblings.
authored Jun 19, 2010
47
ba72241 @notahat Working my way through documenting everything.
authored Jun 19, 2010
48 User.blueprint do
49 username { "user#{sn}" } # Each user gets a unique serial number.
50 end
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
51
ba72241 @notahat Working my way through documenting everything.
authored Jun 19, 2010
52 Post.blueprint do
53 author
54 title { "Post #{sn}" }
55 body { "Lorem ipsum..." }
56 end
634ec69 @notahat More documentation scribblings.
authored Jun 19, 2010
57
ba72241 @notahat Working my way through documenting everything.
authored Jun 19, 2010
58 Comment.blueprint do
59 post
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
60 email { "commenter#{sn}@example.com" }
ba72241 @notahat Working my way through documenting everything.
authored Jun 19, 2010
61 body { "Lorem ipsum..." }
62 end
634ec69 @notahat More documentation scribblings.
authored Jun 19, 2010
63
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
64
65 ## Installation
66
67 ### Upgrading from Machinist 1
68
7e439d5 @notahat More README improvements.
authored Jun 19, 2011
69 See [the wiki](http://wiki.github.com/notahat/machinist/machinist-2).
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
70
71 ### Rails 3
72
73 In your app's `Gemfile`, in the `group :test` section, add:
74
75 gem 'machinist', '>= 2.0.0.beta2'
76
77 Then run:
78
79 bundle
80 rails generate machinist:install
81
82 If you want Machinist to automatically add a blueprint to your blueprints file
83 whenever you generate a model, add the following to your
84 `config/application.rb` in the `config.generators` section:
85
86 g.fixture_replacement :machinist
87
88
89 ### Rails 2
90
7e439d5 @notahat More README improvements.
authored Jun 19, 2011
91 See [the wiki](http://wiki.github.com/notahat/machinist/rails-2).
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
92
93
94 ## Usage
95
96 ### Blueprints
97
7e439d5 @notahat More README improvements.
authored Jun 19, 2011
98 A blueprint describes how to generate an object. The blueprint takes care of
99 providing attributes that your test doesn't care about, leaving you to focus on
100 the just the attributes that are important for the test.
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
101
102 A simple blueprint might look like this:
103
104 Post.blueprint do
7e439d5 @notahat More README improvements.
authored Jun 19, 2011
105 title { "A Post" }
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
106 body { "Lorem ipsum..." }
107 end
108
109 You can then construct a Post from this blueprint with:
110
111 Post.make!
112
113 When you call `make!`, Machinist calls `Post.new`, then runs through the
114 attributes in your blueprint, calling the block for each attribute to generate
115 a value. It then saves and reloads the Post. (It throws an exception if the
116 Post can't be saved.)
117
118 You can override values defined in the blueprint by passing a hash to make:
119
120 Post.make!(:title => "A Specific Title")
7e439d5 @notahat More README improvements.
authored Jun 19, 2011
121
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
122 If you want to generate an object without saving it to the database, replace
123 `make!` with `make`.
124
125
7e439d5 @notahat More README improvements.
authored Jun 19, 2011
126 ### Unique Attributes
127
128 For attributes that need to be unique, you can call the `sn` method from
129 within the attribute block to get a unique serial number for the object.
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
130
131 User.blueprint do
7e439d5 @notahat More README improvements.
authored Jun 19, 2011
132 username { "user-#{sn}" }
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
133 end
7e439d5 @notahat More README improvements.
authored Jun 19, 2011
134
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
135
136 ### Associations
137
138 If your object needs associated objects, you can generate them like this:
139
140 Comment.blueprint do
141 post { Post.make }
142 end
143
144 Calling `Comment.make!` will construct a Comment and its associated Post, and
145 save both.
146
147 If you want to override the value for post when constructing the comment, you
148 can do this:
149
150 post = Post.make(:title => "A particular title)
151 comment = Comment.make(:post => post)
152
153 Machinist is smart enough to look at the association and work out what sort of
154 object it needs to create, so you can shorten the above blueprint to:
155
156 Comment.blueprint do
157 post
158 end
159
160 For `has_many` and `has_and_belongs_to_many` associations, you can create
161 multiple associated objects like this:
162
163 Post.blueprint do
164 comments(3)
165 end
166
167
7e439d5 @notahat More README improvements.
authored Jun 19, 2011
168 ### Named Blueprints
169
170 Named blueprints let you define variations on an object. For example, suppose
171 some of your Users are administrators:
172
173 User.blueprint do
174 name { "User #{sn}" }
175 email { "user-#{sn}@example.com" }
176 end
177
178 User.blueprint(:admin) do
179 name { "Admin User #{sn}" }
180 admin { true }
181 end
182
183 Calling:
184
185 User.make!(:admin)
186
187 will use the `:admin` blueprint.
188
189 Named blueprints call the default blueprint to set any attributes not
190 specifically provided, so in this example the `email` attribute will still be
191 generated even for an admin user.
192
193 You must define a default blueprint for any class that has a named blueprint,
194 even if the default blueprint is empty.
195
196
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
197 ### Blueprints on Plain Old Ruby Objects
198
199 Machinist also works with plain old Ruby objects. Let's say you have a class like:
200
201 class Post
202 extend Machinist::Machinable
203
204 attr_accessor :title
205 attr_accessor :body
206 end
207
208 You can blueprint the Post class just like anything else:
209
210 Post.blueprint do
211 title { "A title!" }
212 body { "A body!" }
213 end
214
215 And `Post.make` will construct a new Post.
7e439d5 @notahat More README improvements.
authored Jun 19, 2011
216
217
218 ### Other Tricks
219
220 You can refer to already assigned attributes when constructing a new attribute:
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
221
7e439d5 @notahat More README improvements.
authored Jun 19, 2011
222 Post.blueprint do
223 author { "Author #{sn}" }
224 body { "Post by #{object.author}" }
225 end
226
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
227
228 ## Compatibility
229
230 I've tested this with:
231
232 Ruby versions: 1.8.7, 1.9.2
8dcfcaa @notahat Slowly getting the docs in place.
authored Jun 19, 2011
233 Rails versions: 2.3, 3.0
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
234
235 It may well be happy with other versions too, but I'm not promising anything.
236 Compatibility patches are welcome.
237
238
239 ## Developing
240
241 The Machinist specs and source code were written to be read, and I'm pretty
242 happy with them. Don't be have a look under the hood.
243
8dcfcaa @notahat Slowly getting the docs in place.
authored Jun 19, 2011
244 If you want to submit a patch:
245
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
246 - Fork the project.
247 - Make your feature addition or bug fix.
248 - Add tests for it. This is important so I don't break it in a
249 future version unintentionally.
250 - Commit, do not mess with rakefile, version, or history.
251 (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
252 - Send me a pull request. Bonus points for topic branches.
253
254
255 ## Status
256
257 In active use in a number of large Rails 2 apps.
258
259 Development has been sporadic, but is picking up again.
d7dbd50 @notahat Added Rails 2 installation instructions.
authored Jun 26, 2010
260
261
ba72241 @notahat Working my way through documenting everything.
authored Jun 19, 2010
262 ## Contributors
263
264 Machinist is maintained by Pete Yandell ([pete@notahat.com](mailto:pete@notahat.com), [@notahat](http://twitter.com/notahat))
265
266 Other contributors include:
267
268 [Marcos Arias](http://github.com/yizzreel),
269 [Jack Dempsey](http://github.com/jackdempsey),
df48e93 @notahat Added Jeremy Durham to contributors.
authored Jul 5, 2010
270 [Jeremy Durham](http://github.com/jeremydurham),
ba72241 @notahat Working my way through documenting everything.
authored Jun 19, 2010
271 [Clinton Forbes](http://github.com/clinton),
272 [Perryn Fowler](http://github.com/perryn),
273 [Niels Ganser](http://github.com/Nielsomat),
274 [Jeremy Grant](http://github.com/jeremygrant),
275 [Jon Guymon](http://github.com/gnarg),
276 [James Healy](http://github.com/yob),
417d24c @notahat Belatedly added Ben H and Xavier to contributors.
authored Jul 7, 2010
277 [Ben Hoskings](http://github.com/benhoskings),
ba72241 @notahat Working my way through documenting everything.
authored Jun 19, 2010
278 [Evan David Light](http://github.com/elight),
279 [Chris Lloyd](http://github.com/chrislloyd),
280 [Adam Meehan](http://github.com/adzap),
281 [Kyle Neath](http://github.com/kneath),
282 [Lawrence Pit](http://github.com/lawrencepit),
417d24c @notahat Belatedly added Ben H and Xavier to contributors.
authored Jul 6, 2010
283 [Xavier Shay](http://github.com/xaviershay),
ba72241 @notahat Working my way through documenting everything.
authored Jun 19, 2010
284 [T.J. Sheehy](http://github.com/tjsheehy),
285 [Roland Swingler](http://github.com/knaveofdiamonds),
286 [Gareth Townsend](http://github.com/quamen),
287 [Matt Wastrodowski](http://github.com/towski),
288 [Ian White](http://github.com/ianwhite)
289
290 Thanks to Thoughtbot's [Factory
291 Girl](http://github.com/thoughtbot/factory_girl/tree/master). Machinist was
292 written because I loved the idea behind Factory Girl, but I thought the
293 philosophy wasn't quite right, and I hated the syntax.
cc9bd03 @notahat Working on the README.
authored Jun 19, 2011
294
Something went wrong with that request. Please try again.