/
README_rdoc.html
314 lines (304 loc) · 16 KB
/
README_rdoc.html
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
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html lang='en'>
<head>
<title>File: README.rdoc [pickle API docs]</title>
<meta content='text/html; charset=UTF-8' http-equiv='Content-Type'>
<link href='../rdoc-style.css' media='screen' rel='stylesheet' type='text/css'>
<script type='text/javascript'>
//<![CDATA[
function popupCode(url) {
window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
}
function toggleCode(id) {
var code = document.getElementById(id)
code.style.display = code.style.display != 'block' ? 'block' : 'none'
return true
}
// Make codeblocks hidden by default
document.writeln('<' + 'style type="text/css">.method .source pre { display: none }<\/style>')
//]]>
</script>
</head>
<body class='page'>
<div class='file' id='wrapper'>
<div class='header'>
<div class='name'>README.rdoc</div>
<div class='paths'>
README.rdoc
</div>
<div class='last-update'>
Last Update:
<span class='datetime'>Wed Mar 17 13:05:51 +0000 2010</span>
</div>
</div>
<div id='content'>
<div id='text'>
<div id='description'>
<h1>pickle</h1>
<p>
<a href="../classes/Pickle.html">Pickle</a> gives you cucumber steps that
create your models easily from factory-girl or machinist
factories/blueprints. You can also just use ActiveRecord but it’s not
as cool.
</p>
<p>
References to the models are stored in the current world, not necessarily
for the purpose of checking the db (although you could use it for that),
but for enabling easy reference to urls, and for building complex givens
which require a bunch of models collaborating
</p>
<h2>Resources</h2>
<p>
<b>Github</b> for code: <a
href="http://github.com/ianwhite/pickle">github.com/ianwhite/pickle</a>
</p>
<p>
<b>Gemcutter</b> for the gem: <a
href="http://gemcutter.org/gems/pickle">gemcutter.org/gems/pickle</a>
</p>
<p>
<b>API</b> docs: <a href="http://ianwhite.github.com/pickle/doc/">Pickle
rdoc on github</a>
</p>
<p>
<b>Google group</b> for questions: <a
href="http://groups.google.com/group/pickle-cucumber">groups.google.com/group/pickle-cucumber</a>
</p>
<p>
<b>Lighthouse</b> for bugs: <a
href="http://ianwhite.lighthouseapp.com/projects/25941-pickle">ianwhite.lighthouseapp.com/projects/25941-pickle</a>
</p>
<p>
<b>Railscast</b> presentation: <a
href="http://railscasts.com/episodes/186-pickle-with-cucumber">railscasts.com/episodes/186-pickle-with-cucumber</a>
</p>
<p>
<b>Blog articles</b>: <a
href="http://blog.dynamic50.com/index.php/2009/04/integration-testing-with-cucumber-and-pickle/">dynamic50:
Integration testing with cucumber and pickle</a>, <a
href="http://rubyflare.com/2009/10/28/pickle-my-cucumber/">rubyflare:
pickle my cucumber</a>
</p>
<h2>Install</h2>
<p>
Install pickle either as a rails plugin, or a gem
</p>
<pre># gem from gemcutter
sudo gem install pickle

# gem dependency (in config/environments/cucumber.rb)
config.gem 'pickle'

# plugin
script/plugin install git://github.com/ianwhite/pickle.git

# or, plugin as submodule
git submodule add git://github.com/ianwhite/pickle.git vendor/plugins/pickle</pre>
<h2>CI</h2>
<p>
It’s tested against all stable branches of 2.x rails, and edge, with
the latest versions of rspec, cucumber, factory_girl, machinist.
</p>
<h2>Run the tests</h2>
<p>
You can run the test with <b>garlic</b> <a
href="http://github.com/ianwhite/garlic">github.com/ianwhite/garlic</a>,
which tests against different versions of rails.
</p>
<p>
Or, you can make a test rails app:
</p>
<pre>cd ~/wherever_you_work
rails pickle_test_project; cd pickle_test_project
script/generate rspec
script/generate cucumber --rspec
script/plugin install git://github.com/ianwhite/pickle.git
cd vendor/plugins/pickle
rake spec
cucumber features</pre>
<h2>Contributors</h2>
<p>
The following people have made <a href="../classes/Pickle.html">Pickle</a>
better:
</p>
<ul>
<li><a href="http://github.com/nruth">Nick Rutherford</a>
</li>
<li><a href="http://github.com/guenter">Tobi Knaup</a>
</li>
<li><a href="http://github.com/schlick">Michael MacDonald</a>
</li>
<li><a href="http://github.com/UnderpantsGnome">Michael Moen</a>
</li>
<li><a href="http://github.com/myronmarston">Myron Marston</a>
</li>
<li><a href="http://github.com/xing">Stephan Hagemann</a>
</li>
<li><a href="http://github.com/cflipse">Chris Flipse</a>
</li>
</ul>
<h2>Get Started</h2>
<p>
(you’d better install cucumber)
</p>
<pre>script/generate pickle [paths] [email]</pre>
<p>
Now have a look at <tt>features/step_definitions/pickle_steps.rb</tt>
</p>
<p>
If you want path steps and email steps then just add ‘paths’
and/or ‘email’. The code/steps will be written to
<tt>features/env/paths.rb</tt> and
<tt>features/step_definitions/email_steps.rb</tt> respectively.
</p>
<h3>Using with plain ole Active Record</h3>
<p>
If you have an AR called ‘Post’, with required fields
‘title’, and ‘body’, then you can now write steps
like this
</p>
<pre>Given a post exists with title: "My Post", body: "My body"</pre>
<h3>Using with factory-girl or machinist</h3>
<p>
But you’re using Machinist or FactoryGirl right?! To leverage all of
the factories/blueprints you’ve written, you can just do stuff like
</p>
<pre>Given a user exists
And another user exists with role: "admin"

# later
Then a user should exist with name: "Fred"
And that user should be activated # this uses rspec predicate matchers</pre>
<h4>Machinst: require your blueprints and reset Shams</h4>
<p>
(The latest version of pickle supports <a
href="http://github.com/notahat/machinist/commit/d6492e6927a8aa1819926e48b22377171fd20496">multiple
blueprints</a>, for earlier versions of machinist use pickle <= 0.1.10)
</p>
<p>
In your <tt>features/support/env.rb</tt> add the following lines at the
bottom
</p>
<pre>require "#{Rails.root}/spec/blueprints" # or wherever they live
Before { Sham.reset } # reset Shams in between scenarios</pre>
<h4>FactoryGirl: make sure factories are loaded</h4>
<p>
In your config/environments/cucumber.rb file, make sure the factory-girl
gem is included (unless it’s installed as a plugin).
</p>
<p>
If that doesn’t solve loading issues then require your factories.rb
file directly in a file called
‘features/support/factory_girl.rb‘
</p>
<pre># example features/support/factory_girl.rb
require File.dirname(__FILE__) + '/../../spec/factories'</pre>
<h3>Configuring <a href="../classes/Pickle.html">Pickle</a></h3>
<p>
You can tell pickle to use another factory adapter (see <a
href="../classes/Pickle/Adapter.html">Pickle::Adapter</a>), or create
mappings from english expressions to pickle model names. You can also
override many of the options on the <a
href="../classes/Pickle/Config.html">Pickle::Config</a> object if you so
choose.
</p>
<p>
In: <tt>features/support/pickle.rb</tt>
</p>
<pre>require 'pickle/world'

Pickle.configure do |config|
 config.adapters = [:machinist, YourOwnAdapterClass]
 config.map 'me', 'myself', 'my', 'I', :to => 'user: "me"'
end</pre>
<p>
Out of the box pickle looks for machinist, then factory-girl, then finally
active-record ‘factories’. If you find that your steps
aren’t working with your factories, it’s probably the case that
your factory setup is not being included in your cucumber environment (see
comments above regarding machinist and factory-girl).
</p>
<h2>API</h2>
<h3>Steps</h3>
<p>
When you run <tt>script/generate pickle</tt> you get the following steps
</p>
<h4>Given steps</h4>
<p>
“Given <b>a model</b> exists”, e.g.
</p>
<pre>Given a user exists
Given a user: "fred" exists
Given the user exists</pre>
<p>
“Given <b>a model</b> exists with <b>fields</b>“, e.g.
</p>
<pre>Given a user exists with name: "Fred"
Given a user exists with name: "Fred", activated: false</pre>
<p>
You can refer to other models in the fields
</p>
<pre>Given a user exists
And a post exists with author: the user

Given a person: "fred" exists
And a person: "ethel" exists
And a fatherhood exists with parent: user "fred", child: user "ethel"</pre>
<p>
“Given <b>n models</b> exist”, e.g.
</p>
<pre>Given 10 users exist</pre>
<p>
“Given <b>n models</b> exist with <b>fields</b>“, examples:
</p>
<pre>Given 10 users exist with activated: false</pre>
<h4>Then steps</h4>
<h5>Asserting existence of models</h5>
<p>
“Then <b>a model</b> should exist”, e.g.
</p>
<pre>Then a user should exist</pre>
<p>
“Then <b>a model</b> should exist with <b>fields</b>“, e.g.
</p>
<pre>Then a user: "fred" should exist with name: "Fred" # we can label the found user for later use</pre>
<p>
You can use other models, booleans, numerics, and strings as fields
</p>
<pre>Then a person should exist with child: person "ethel"
Then a user should exist with activated: false
Then a user should exist with activated: true, email: "fred@gmail.com"</pre>
<p>
“Then <b>n models</b> should exist”, e.g.
</p>
<pre>Then 10 events should exist</pre>
<p>
“Then <b>n models</b> should exist with <b>fields</b>“, e.g.
</p>
<pre>Then 2 people should exist with father: person "fred"</pre>
<p>
“Then the following <b>models</b> exist”. This allows the
creation of multiple models using a table syntax. Using a column with the
singularized name of the model creates a referenceable model. E.g.
</p>
<pre>Then the following users exist:
 | name | activated |
 | Freddy | false |

Then the following users exist:
 | user | name | activated |
 | Fred | Freddy | false |</pre>
<h5>Asserting associations</h5>
<p>
One-to-one assocs: “Then <b>a model</b> should be <b>other
model</b>’s <b>association</b>“, e.g.
</p>
<pre>Then the person: "fred" should be person: "ethel"'s father</pre>
<p>
Many-to-one assocs: “Then <b>a model</b> should be [in|one of]
<b>other model</b>’s <b>association</b>“, e.g.
</p>
<pre>Then the person: "ethel" should be one of person: "fred"'s children
Then the comment should be in the post's comments</pre>
<h5>Asserting predicate methods</h5>
<p>
“Then <b>a model</b> should [be|have] [a|an] <b>predicate</b>“,
e.g.
</p>
<pre>Then the user should have a status # => user.status?.should == true
Then the car: "batmobile" should be fast # => car.fast?.should == true</pre>
<p>
“Then <b>a model</b> should not [be|have] [a|an]
<b>predicate</b>“, e.g.
</p>
<pre>Then person: "fred" should not be childless # => fred.childless?.should == false</pre>
<h3>Regexps for use in your own steps</h3>
<p>
By default you get some regexps available in the main namespace for use in
creating your own steps: `capture_model`, `capture_fields`, and others (see
<a href="lib/pickle_rb.html">lib/pickle.rb</a>)
</p>
<p>
(You can use any of the regexps that <a
href="../classes/Pickle.html">Pickle</a> uses by using the <a
href="../classes/Pickle.html#M000003">Pickle.parser</a> namespace, see <a
href="../classes/Pickle/Parser/Matchers.html">Pickle::Parser::Matchers</a>
for the methods available)
</p>
<p>
<b>capture_model</b>
</p>
<pre>Given /^#{capture_model} exists$/ do |model_name|
 model(model_name).should_not == nil
end

Then /^I should be at the (.*?) page$/ |page|
 if page =~ /#{capture_model}'s/
 url_for(model($1))
 else
 # ...
 end
end

Then /^#{capture_model} should be one of #{capture_model}'s posts$/ do |post, forum|
 post = model!(post)
 forum = model!(forum)
 forum.posts.should include(post)
end</pre>
<p>
<b>capture_fields</b>
</p>
<p>
This is useful for setting attributes, and knows about pickle model names
so that you can build up composite objects with ease
</p>
<pre>Given /^#{capture_model} exists with #{capture_fields}$/ do |model_name, fields|
 create_model(model_name, fields)
end

# example of use
Given a user exists
And a post exists with author: the user # this step will assign the above user as :author on the post</pre>
</div>
<div id='section'>
</div>
</div>
</div>
<div id='footer-push'></div>
</div>
<div id='footer'>
<a href="http://github.com/mislav/hanna/tree/master"><strong>Hanna</strong> RDoc template</a>
</div>
</body>
</html>