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
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
|
@wire
Feature: Wire Protocol
In order to be allow Cucumber to touch my app in intimate places
As a developer on platform which doesn't support Ruby
I want a low-level protocol which Cucumber can use to run steps within my app
#
# Cucumber's wire protocol is an implementation of Cucumber's internal
# 'programming language' abstraction, and allows step definitions to be
# implemented and invoked on any platform.
#
# Communication is over a TCP socket, which Cucumber connects to when it finds
# a definition file with the .wire extension in the step_definitions folder
# (or other load path). Note that these files are rendered with ERB when loaded.
#
# Cucumber sends the following request messages out over the wire:
#
# * step_matches : this is used to find out whether the wire server has a
# definition for a given step
# * invoke : this is used to ask for a step definition to be invoked
# * begin_scenario : signals that cucumber is about to execute a scenario
# * end_scenario : signals that cucumber has finished executing a scenario
# * snippet_text : requests a snippet for an undefined step
#
# Every message supports two standard responses:
# * success : which expects different arguments (sometimes none at
# all) depending on the request.
# * fail : causes a Cucumber::WireSupport::WireException to be
# raised.
#
# Some messages support more responses - see below for details.
#
# A WirePacket flowing in either direction is formatted as a JSON-encoded
# string, with a newline character signaling the end of a packet. See the
# specs for Cucumber::WireSupport::WirePacket for more details.
#
# These messages are described in detail below, with examples.
#
Background:
Given a standard Cucumber project directory structure
And a file named "features/wired.feature" with:
"""
Feature: High strung
Scenario: Wired
Given we're all wired
"""
And a file named "features/step_definitions/some_remote_place.wire" with:
"""
host: localhost
port: 54321
"""
#
# # Request: 'step_matches'
#
# When the features have been parsed, Cucumber will send a step_matches
# message to ask the wire server if it can match a step name. This happens for
# each of the steps in each of the features.
#
# The wire server replies with an array of StepMatch objects.
Scenario: Dry run finds no step match
Given there is a wire server running on port 54321 which understands the following protocol:
| request | response |
| ["step_matches",{"name_to_match":"we're all wired"}] | ["success",[]] |
When I run cucumber --dry-run --no-snippets -f progress
And it should pass with
"""
U
1 scenario (1 undefined)
1 step (1 undefined)
"""
# When each StepMatch is returned, it contains the following data:
# * id - identifier for the step definition to be used later when if it
# needs to be invoked. The identifier can be any string value and
# is simply used for the wire server's own reference.
# * args - any argument values as captured by the wire end's own regular
# expression (or other argument matching) process.
Scenario: Dry run finds a step match
Given there is a wire server running on port 54321 which understands the following protocol:
| request | response |
| ["step_matches",{"name_to_match":"we're all wired"}] | ["success",[{"id":"1", "args":[]}]] |
When I run cucumber --dry-run -f progress
And it should pass with
"""
-
1 scenario (1 skipped)
1 step (1 skipped)
"""
# Optionally, the StepMatch can also contain a source reference, and a native
# regexp string which will be used by some formatters.
Scenario: Step matches returns details about the remote step definition
Given there is a wire server running on port 54321 which understands the following protocol:
| request | response |
| ["step_matches",{"name_to_match":"we're all wired"}] | ["success",[{"id":"1", "args":[], "source":"MyApp.MyClass:123", "regexp":"we.*"}]] |
When I run cucumber -f stepdefs --dry-run
Then STDERR should be empty
And it should pass with
"""
-
we.* # MyApp.MyClass:123
1 scenario (1 skipped)
1 step (1 skipped)
"""
#
# # Request: 'invoke'
#
# Assuming a StepMatch was returned for a given step name, when it's time to
# invoke that step definition, Cucumber will send an invoke message.
#
# The invoke message contains the ID of the step definition, as returned by
# the wire server in response to the the step_matches call, along with the
# arguments that were parsed from the step name during the same step_matches
# call.
#
# The wire server will normally[1] reply one of the following:
# * success
# * fail
# * pending : optionally takes a message argument
#
# [1] This isn't the whole story: see also wire_protocol_table_diffing.feature
#
# ## Pending Steps
#
Scenario: Invoke a step definition which is pending
Given there is a wire server running on port 54321 which understands the following protocol:
| request | response |
| ["step_matches",{"name_to_match":"we're all wired"}] | ["success",[{"id":"1", "args":[]}]] |
| ["begin_scenario"] | ["success"] |
| ["invoke",{"id":"1","args":[]}] | ["pending", "I'll do it later"] |
| ["end_scenario"] | ["success"] |
When I run cucumber -f pretty -q
And it should pass with
"""
Feature: High strung
Scenario: Wired
Given we're all wired
I'll do it later (Cucumber::Pending)
features/wired.feature:3:in `Given we're all wired'
1 scenario (1 pending)
1 step (1 pending)
"""
# ## Passing Steps
#
Scenario: Invoke a step definition which passes
Given there is a wire server running on port 54321 which understands the following protocol:
| request | response |
| ["step_matches",{"name_to_match":"we're all wired"}] | ["success",[{"id":"1", "args":[]}]] |
| ["begin_scenario"] | ["success"] |
| ["invoke",{"id":"1","args":[]}] | ["success"] |
| ["end_scenario"] | ["success"] |
When I run cucumber -f progress
And it should pass with
"""
.
1 scenario (1 passed)
1 step (1 passed)
"""
# ## Failing Steps
#
# When an invoked step definition fails, it can return details of the exception
# in the reply to invoke. This causes a Cucumber::WireSupport::WireException to be
# raised.
#
# Valid arguments are:
# * message (mandatory)
# * exception
# * backtrace
#
# See the specs for Cucumber::WireSupport::WireException for more details
#
Scenario: Invoke a step definition which fails
Given there is a wire server running on port 54321 which understands the following protocol:
| request | response |
| ["step_matches",{"name_to_match":"we're all wired"}] | ["success",[{"id":"1", "args":[]}]] |
| ["begin_scenario"] | ["success"] |
| ["invoke",{"id":"1","args":[]}] | ["fail",{"message":"The wires are down", "exception":"Some.Foreign.ExceptionType"}] |
| ["end_scenario"] | ["success"] |
When I run cucumber -f progress
Then STDERR should be empty
And it should fail with
"""
F
(::) failed steps (::)
The wires are down (Some.Foreign.ExceptionType from localhost:54321)
features/wired.feature:3:in `Given we're all wired'
Failing Scenarios:
cucumber features/wired.feature:2 # Scenario: Wired
1 scenario (1 failed)
1 step (1 failed)
"""
# ## Step Arguments
#
# Imagine we have a step definition like:
#
# Given /we're all (.*)/ do | what_we_are |
# end
#
# When this step definition matches the step name in our feature, the word
# 'wired' will be captured as an argument.
#
# Cucumber expects this StepArgument to be returned in the StepMatch. The keys
# have the following meanings:
# * val : the value of the string captured for that argument from the step
# name passed in step_matches
# * pos : the position within the step name that the argument was matched
# (used for formatter highlighting)
#
Scenario: Invoke a step definition which takes string arguments (and passes)
Given there is a wire server running on port 54321 which understands the following protocol:
| request | response |
| ["step_matches",{"name_to_match":"we're all wired"}] | ["success",[{"id":"1", "args":[{"val":"wired", "pos":10}]}]] |
| ["begin_scenario"] | ["success"] |
| ["invoke",{"id":"1","args":["wired"]}] | ["success"] |
| ["end_scenario"] | ["success"] |
When I run cucumber -f progress
Then STDERR should be empty
And it should pass with
"""
.
1 scenario (1 passed)
1 step (1 passed)
"""
# ## Multiline Table Arguments
#
# When the step has a multiline table argument, it will be passed with the
# invoke message as a string - a serialized JSON array of array of strings.
# In the following scenario our step definition takes two arguments - one
# captures the "we're" and the other takes the table.
Scenario: Invoke a step definition which takes table arguments (and passes)
Given a file named "features/wired_on_tables.feature" with:
"""
Feature: High strung
Scenario: Wired and more
Given we're all:
| wired |
| high |
| happy |
"""
And there is a wire server running on port 54321 which understands the following protocol:
| request | response |
| ["step_matches",{"name_to_match":"we're all:"}] | ["success",[{"id":"1", "args":[{"val":"we're", "pos":0}]}]] |
| ["begin_scenario"] | ["success"] |
| ["invoke",{"id":"1","args":["we're",[["wired"],["high"],["happy"]]]}] | ["success"] |
| ["end_scenario"] | ["success"] |
When I run cucumber -f progress features/wired_on_tables.feature
Then STDERR should be empty
And it should pass with
"""
.
1 scenario (1 passed)
1 step (1 passed)
"""
#
# # Request: 'snippets'
#
Scenario: Wire server returns snippets for a step that didn't match
Given there is a wire server running on port 54321 which understands the following protocol:
| request | response |
| ["step_matches",{"name_to_match":"we're all wired"}] | ["success",[]] |
| ["snippet_text",{"step_keyword":"Given","multiline_arg_class":"","step_name":"we're all wired"}] | ["success","foo()\n bar;\nbaz"] |
| ["begin_scenario"] | ["success"] |
| ["end_scenario"] | ["success"] |
When I run cucumber -f pretty
Then STDERR should be empty
And it should pass with
"""
Feature: High strung
Scenario: Wired # features/wired.feature:2
Given we're all wired # features/wired.feature:3
1 scenario (1 undefined)
1 step (1 undefined)
You can implement step definitions for undefined steps with these snippets:
foo()
bar;
baz
"""
#
# # Bad Response
#
Scenario: Unexpected response
Given there is a wire server running on port 54321 which understands the following protocol:
| request | response |
| ["begin_scenario"] | ["yikes"] |
When I run cucumber -f progress
Then STDERR should match
"""
undefined method `handle_yikes'
"""
|
