awetestlib 0.1.13-x86-mingw32 → 0.1.14-x86-mingw32

Sign up to get free protection for your applications and to get access to all the features.
@@ -1,37 +1,37 @@
1
1
  module Awetestlib
2
+ # Awetest DSL for browser based testing.
2
3
  module Regression
4
+ # Methods covering user interactions with the browser.
5
+ #
6
+ #
7
+ # All of the methods in groups other than Core call Core methods.
8
+ # The methods in the other groups, along with aliases, exist for backward compatibility with earlier versions
9
+ # of the Awetest DSL.
3
10
  module UserInput
4
11
 
5
- =begin rdoc
6
- :category: A_rdoc_test
7
- Click a specific DOM element by one of its attributes and that attribute's value.
8
-
9
- _Parameters_::
10
-
11
- *browser* - a reference to the browser window or container element to be tested
12
-
13
- *element* - the kind of element to click. Must be one of the elements recognized by Watir.
14
- Some common values are :link, :button, :image, :div, :span.
15
-
16
- *how* - the element attribute used to identify the specific element. Valid values depend on the kind of element.
17
- Common values: :text, :id, :title, :name, :class, :href (:link only)
18
-
19
- *what* - a string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
20
-
21
- *desc* - a string containing a message or description intended to appear in the log and/or report output
22
-
23
- _Example_
24
-
25
- # html for a link element:
26
- # <a href="http://pragmaticprogrammer.com/titles/ruby/" id="one" name="book">Pickaxe</a>
27
- click(browser, :link, :text, 'Pickaxe')
28
-
29
- =end
30
-
12
+ # @!group Core
13
+
14
+ # Click a specific DOM element identified by one of its attributes and that attribute's value.
15
+ #
16
+ # @example
17
+ # # html for a link element:
18
+ # # <a href="http://pragmaticprogrammer.com/titles/ruby/" id="one" name="book">Pickaxe</a>
19
+ #
20
+ # click(browser, :link, :text, 'Pickaxe')
21
+ #
22
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
23
+ # @param [Symbol] element The kind of element to click. Must be one of the elements recognized by Watir.
24
+ # Some common values are :link, :button, :image, :div, :span.
25
+ # @param [Symbol] how The element attribute used to identify the specific element.
26
+ # Valid values depend on the kind of element.
27
+ # Common values: :text, :id, :title, :name, :class, :href (:link only)
28
+ # @param [String, Regexp] what A string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
29
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
30
+ # @return [Boolean] True if the Watir or Watir-webdriver function does not throw an exception.
31
+ #
31
32
  def click(browser, element, how, what, desc = '')
32
33
  #debug_to_log("#{__method__}: #{element}, #{how}, #{what}")
33
- msg = "Click #{element} :#{how}=>'#{what}'"
34
- msg << ", '#{desc}'" if desc.length > 0
34
+ msg = build_message("Click #{element} :#{how}=>'#{what}'", desc)
35
35
  msg1 = "#{element}(#{how}, '#{what}')"
36
36
  begin
37
37
  case element
@@ -58,46 +58,207 @@ _Example_
58
58
  browser.element(how, what).click
59
59
  end
60
60
  end
61
- if validate(browser, @myName, __LINE__)
62
61
  passed_to_log(msg)
63
62
  true
64
- end
65
63
  rescue
66
64
  failed_to_log("Unable to #{msg}. '#{$!}'")
67
65
  end
68
66
 
69
- =begin rdoc
70
- :category: A_rdoc_test
71
- Click a specific DOM element by one of its attributes and that attribute's value and
72
- do not wait for the browser to finish reloading. Used when a modal popup or alert is expected. Allows the script
73
- to keep running so the popup can be handled.
67
+ # @!endgroup Core
68
+
69
+ # @!group Click
70
+
71
+ # Click a button element identified by the value of its *:id* attribute. A button is an HTML element with tag 'input' and type 'submit' or 'button'.
72
+ # @param [Watir::Browser, Watir::Container] browser A reference to the browser window or container element to be tested.
73
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
74
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
75
+ # @return (see #click)
76
+ def click_button_by_id(browser, what, desc = '')
77
+ click(browser, :button, :id, what, desc)
78
+ end
79
+
80
+ # Click a button element identified by the value of its index within the container referred to by <b>*browser*</b>.
81
+ # @param [Watir::Browser, Watir::Container] browser A reference to the browser window or container element to be tested.
82
+ # @param [Fixnum] what An integer that indicates the index of the element within the container.
83
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
84
+ # @return (see #click)
85
+ def click_link_by_index(browser, what, desc = '')
86
+ click(browser, :link, :index, what, desc)
87
+ end
88
+
89
+ # Click a link element identified by the value of its *:href* attribute. Take care to escape characters in the url that are reserved by Regexp.
90
+ # @param (see #click_button_by_id)
91
+ # @return (see #click)
92
+ def click_link_by_href(browser, what, desc = '')
93
+ click(browser, :link, :href, what, desc)
94
+ end
95
+
96
+ alias click_href click_link_by_href
97
+
98
+ # Click a link element identified by the value of its *:href* attribute and do not wait for the browser to reach ready state.
99
+ # Take care to escape characters in the url that are reserved by Regexp.
100
+ # @param (see #click_button_by_id)
101
+ # @return (see #click)
102
+ def click_link_no_wait_by_href(browser, what, desc = '')
103
+ click_no_wait(browser, :link, :href, what, desc)
104
+ end
105
+
106
+ # Click a button element identified by the value of its index within the container referred to by <b>*browser*</b>.
107
+ # @param (see #click_link_by_index)
108
+ # @return (see #click)
109
+ def click_button_by_index(browser, what, desc = '')
110
+ click(browser, :button, :index, what, desc)
111
+ end
112
+
113
+ # Click a button element identified by the value of its *:name* attribute. A button is an HTML element with tag 'input' and type 'submit' or 'button'.
114
+ # @param (see #click_button_by_id)
115
+ # @return (see #click)
116
+ def click_button_by_name(browser, what, desc = '')
117
+ click(browser, :button, :name, what, desc)
118
+ end
119
+
120
+ # Click a button element identified by the value of its *:text* attribute. A button is an HTML element with tag 'input' and type 'submit' or 'button'.
121
+ # @param (see #click_button_by_id)
122
+ # @return (see #click)
123
+ def click_button_by_text(browser, what, desc = '')
124
+ click(browser, :button, :text, what, desc)
125
+ end
126
+
127
+ # Click a button element identified by the value of its *:class* attribute. A button is an HTML element with tag 'input' and type 'submit' or 'button'.
128
+ # @param (see #click_button_by_id)
129
+ # @return (see #click)
130
+ def click_button_by_class(browser, what, desc = '')
131
+ click(browser, :button, :class, what, desc)
132
+ end
133
+
134
+ # Click a button element identified by the value of its *:value* attribute. A button is an HTML element with tag 'input' and type 'submit' or 'button'.
135
+ # @param (see #click_button_by_id)
136
+ # @return (see #click)
137
+ def click_button_by_value(browser, what, desc = '')
138
+ click(browser, :button, :value, what, desc)
139
+ end
74
140
 
75
- _Parameters_::
141
+ # Click a button element identified by the value of its *:title* attribute. A button is an HTML element with tag 'input' and type 'submit' or 'button'.
142
+ # @param (see #click_button_by_id)
143
+ # @return (see #click)
144
+ def click_button_by_title(browser, what, desc = '')
145
+ click(browser, :button, :title, what, desc)
146
+ end
76
147
 
77
- *browser* - a reference to the browser window to be tested
148
+ # Click a link element identified by the value of its *:id* attribute.
149
+ # @param (see #click_button_by_id)
150
+ # @return (see #click)
151
+ def click_link_by_id(browser, what, desc = '')
152
+ click(browser, :link, :id, what, desc)
153
+ end
78
154
 
79
- *element* - the kind of element to click. Must be one of the elements recognized by Watir.
80
- Some common values are :link, :button, :image, :div, :span.
155
+ alias click_id click_link_by_id
81
156
 
82
- *how* - the element attribute used to identify the specific element. Valid values depend on the kind of element.
83
- Common values: :text, :id, :title, :name, :class, :href (:link only)
157
+ # Click a link element identified by the value of its *:name* attribute.
158
+ # @param (see #click_button_by_id)
159
+ # @return (see #click)
160
+ def click_link_by_name(browser, what, desc = '')
161
+ click(browser, :link, :name, what, desc)
162
+ end
84
163
 
85
- *what* - a string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
164
+ alias click_name click_link_by_name
86
165
 
87
- *desc* - a string containing a message or description intended to appear in the log and/or report output
166
+ # Click a file_field element identified by the value of its *:id* attribute.
167
+ # @param (see #click_button_by_id)
168
+ # @return (see #click)
169
+ def click_file_field_by_id(browser, what, desc = '')
170
+ click(browser, :file_field, :id, what, desc)
171
+ end
172
+
173
+ # Click an image element identified by the value of its *:id* attribute.
174
+ # @param (see #click_button_by_id)
175
+ # @return (see #click)
176
+ def click_img_by_alt(browser, what, desc = '')
177
+ click(browser, :image, :alt, what, desc)
178
+ end
179
+
180
+ # Click an image element identified by the value of its *:title* attribute.
181
+ # @param (see #click_button_by_id)
182
+ # @return (see #click)
183
+ def click_img_by_title(browser, what, desc = '')
184
+ click(browser, :image, :title, what, desc)
185
+ end
186
+
187
+ # Click an image element identified by the value of its *:src* attribute.
188
+ # Take care to escape characters in the source url that are reserved by Regexp.
189
+ # @param (see #click_button_by_id)
190
+ # @return (see #click)
191
+ def click_img_by_src(browser, what, desc = '')
192
+ click(browser, :image, :src, what, desc)
193
+ end
194
+
195
+ # Click a link element identified by the value of its *:value* attribute.
196
+ # @param (see #click_button_by_id)
197
+ # @return (see #click)
198
+ def click_link_by_value(browser, what, desc = '')
199
+ click(browser, :link, :value, what, desc)
200
+ end
201
+
202
+ # Click a link element identified by the value in its text (innerHTML).
203
+ # @param (see #click_button_by_id)
204
+ # @return (see #click)
205
+ def click_link_by_text(browser, what, desc = '')
206
+ click(browser, :link, :text, what, desc)
207
+ end
208
+
209
+ alias click_link click_link_by_text
210
+ alias click_text click_link_by_text
211
+ alias click_js_button click_link_by_text
212
+
213
+ # Click a link element identified by the value of its *:class* attribute.
214
+ # @param (see #click_button_by_id)
215
+ # @return (see #click)
216
+ def click_link_by_class(browser, what, desc = '')
217
+ click(browser, :link, :class, what, desc)
218
+ end
219
+
220
+ alias click_class click_link_by_class
221
+
222
+ # Click a span element identified by the value in its text (innerHTML).
223
+ # @param (see #click_button_by_id)
224
+ # @return (see #click)
225
+ def click_span_by_text(browser, what, desc = '')
226
+ click(browser, :span, :text, what)
227
+ end
88
228
 
89
- _Example_
229
+ alias click_span_with_text click_span_by_text
90
230
 
91
- # html for a link element:
92
- # <a href="http://pragmaticprogrammer.com/titles/ruby/" id="one" name="book">Pickaxe</a>
93
- click_no_wait(browser, :link, :text, 'Pickaxe')
231
+ # Click a link element identified by the value of its *:title* attribute.
232
+ # @param (see #click_button_by_id)
233
+ # @return (see #click)
234
+ def click_link_by_title(browser, what, desc = '')
235
+ click(browser, :link, :title, what, desc)
236
+ end
94
237
 
95
- =end
238
+ alias click_title click_link_by_title
96
239
 
240
+ # @!endgroup Click
241
+
242
+ # @!group Core
243
+
244
+ # Click a specific DOM element by one of its attributes and that attribute's value and
245
+ # do not wait for the browser to finish reloading. Used when a modal popup or alert is expected. Allows the script
246
+ # to keep running so the popup can be handled.
247
+ #
248
+ # @example
249
+ # # html for a link element:
250
+ # # <a href="http://pragmaticprogrammer.com/titles/ruby/" id="one" name="book">Pickaxe</a>
251
+ #
252
+ # click_no_wait(browser, :link, :text, 'Pickaxe')
253
+ #
254
+ # @see #click
255
+ #
256
+ # @param (see #click)
257
+ # @return (see #click)
258
+ #
97
259
  def click_no_wait(browser, element, how, what, desc = '')
98
260
  debug_to_log("#{__method__}: #{element}, #{how}, #{what}")
99
- msg = "Click no wait #{element} :#{how}=>'#{what}'"
100
- msg << ", '#{desc}'" if desc.length > 0
261
+ msg = build_message("Click no wait #{element} :#{how}=>'#{what}'", desc)
101
262
  msg1 = "#{element}(#{how}, '#{what}'"
102
263
  begin
103
264
  case element
@@ -130,151 +291,53 @@ _Example_
130
291
  raise e
131
292
  end
132
293
  end
133
- if validate(browser, @myName, __LINE__)
134
294
  passed_to_log(msg)
135
295
  true
136
- end
137
296
  rescue
138
297
  failed_to_log("Unable to #{msg} '#{$!}'")
139
298
  sleep_for(1)
140
299
  end
141
300
 
142
- # :category: User Input
143
- def click_button_by_id(browser, strg, desc = '')
144
- click(browser, :button, :id, strg, desc)
145
- end
146
-
147
- # :category: User Input
148
- def click_link_by_index(browser, strg, desc = '')
149
- click(browser, :link, :index, strg, desc)
150
- end
151
-
152
- # :category: User Input
153
- def click_link_by_href(browser, strg, desc = '')
154
- click(browser, :link, :href, strg, desc)
155
- end
156
-
157
- alias click_href click_link_by_href
158
- # :category: User Input
159
- def click_link_no_wait_by_href(browser, strg, desc = '')
160
- click_no_wait(browser, :link, :href, strg, desc)
161
- end
301
+ # @!endgroup Core
162
302
 
163
303
  alias click_href_no_wait click_link_no_wait_by_href
164
- # :category: User Input
165
- def click_button_by_index(browser, index, desc = '')
166
- click(browser, :button, :index, index, desc)
167
- end
168
304
 
169
- # :category: User Input
170
- def click_button_by_name(browser, strg, desc = '')
171
- click(browser, :button, :name, strg, desc)
172
- end
173
-
174
- # :category: User Input
175
- def click_button_by_text(browser, strg, desc = '')
176
- click(browser, :button, :text, strg, desc)
177
- end
305
+ # @!group Click No Wait
178
306
 
179
- # :category: User Input
180
- def click_button_by_class(browser, strg, desc = '')
181
- click(browser, :button, :class, strg, desc)
182
- end
183
-
184
- # :category: User Input
185
- def click_button_no_wait_by_id(browser, strg, desc = '')
186
- click_no_wait(browser, :button, :id, strg, desc)
307
+ # Click a button element identified by the value of its *:id* attribute
308
+ # and do not wait for the browser to reach ready state.
309
+ # @param (see #click_button_by_id)
310
+ # @return (see #click)
311
+ def click_button_no_wait_by_id(browser, what, desc = '')
312
+ click_no_wait(browser, :button, :id, what, desc)
187
313
  end
188
314
 
189
315
  alias click_button_by_id_no_wait click_button_no_wait_by_id
190
- # :category: User Input
191
- def click_button_no_wait_by_name(browser, strg, desc = '')
192
- click_no_wait(browser, :button, :name, strg, desc)
193
- end
194
-
195
- # :category: User Input
196
- def click_button_no_wait_by_class(browser, strg, desc = '')
197
- click_no_wait(browser, :button, :class, strg, desc)
198
- end
199
-
200
- alias click_button_by_class_no_wait click_button_no_wait_by_class
201
- # :category: User Input
202
- def click_button_by_value(browser, strg, desc = '')
203
- click(browser, :button, :value, strg, desc)
204
- end
205
-
206
- # :category: User Input
207
- def click_button_by_title(browser, strg, desc = '')
208
- click(browser, :button, :title, strg, desc)
209
- end
210
-
211
- # :category: User Input
212
- def click_button_by_xpath_and_id(browser, strg, desc = '')
213
- msg = "Click button by xpath and id '#{strg}' #{desc}"
214
- if browser.button(:xpath, "//a[@id = '#{strg}']").click
215
- passed_to_log(msg)
216
- true
217
- else
218
- failed_to_log(msg)
219
- end
220
- rescue
221
- failed_to_log("Unable to click button by xpath and id '#{strg}' #{desc} '#{$!}' (#{__LINE__})")
222
- end
223
-
224
- alias click_button_by_xpath click_button_by_xpath_and_id
225
-
226
- =begin rdoc
227
- :category: A_rdoc_test
228
- Click a link identified by the value in its id attribute. Calls click()
229
-
230
- _Parameters_::
231
-
232
- *browser* - a reference to the browser window to be tested
233
316
 
234
- *strg* - a string or a regular expression to be found in the id attribute that uniquely identifies the element.
235
-
236
- *desc* - a string containing a message or description intended to appear in the log and/or report output
237
-
238
-
239
- _Example_
240
-
241
- # html for a link element:
242
- # <a href="http://pragmaticprogrammer.com/titles/ruby/" id="one" name="book">Pickaxe</a>
243
- click_link_by_text(browser, 'Pickaxe', 'Open the page for the Pickaxe book')
244
-
245
- =end
246
-
247
- def click_link_by_id(browser, strg, desc = '')
248
- click(browser, :link, :id, strg, desc)
317
+ # Click a button element identified by the value of its *:name* attribute
318
+ # and do not wait for the browser to reach ready state.
319
+ # @param (see #click_button_by_id)
320
+ # @return (see #click)
321
+ def click_button_no_wait_by_name(browser, what, desc = '')
322
+ click_no_wait(browser, :button, :name, what, desc)
249
323
  end
250
324
 
251
- # :category: A_rdoc_test
252
- alias click_id click_link_by_id
253
-
254
- # :category: User Input
255
- def click_link_by_name(browser, strg, desc = '')
256
- click(browser, :link, :name, strg, desc)
257
- end
258
-
259
- alias click_name click_link_by_name
260
- # :category: User Input
261
- def click_link_by_xpath_and_id(browser, strg, desc = '')
262
- msg = "Click link by xpath and id '#{strg}' #{desc}"
263
- if browser.link(:xpath, "//a[@id = '#{strg}']").click
264
- passed_to_log(msg)
265
- true
266
- else
267
- failed_to_log(msg)
268
- end
269
- rescue
270
- failed_to_log("Unable click on link by xpath and id '#{strg}' #{desc} '#{$!}' (#{__LINE__})")
325
+ # Click a button element identified by the value of its *:class* attribute
326
+ # and do not wait for the browser to reach ready state.
327
+ # @param (see #click_button_by_id)
328
+ # @return (see #click)
329
+ def click_button_no_wait_by_class(browser, what, desc = '')
330
+ click_no_wait(browser, :button, :class, what, desc)
271
331
  end
272
332
 
273
- alias click_link_by_xpath click_link_by_xpath_and_id
333
+ alias click_button_by_class_no_wait click_button_no_wait_by_class
274
334
 
275
- # :category: User Input
276
- def click_link_no_wait_by_id(browser, strg, desc = '')
277
- click_no_wait(browser, :link, :id, strg, desc)
335
+ # Click a link element identified by the value of its *:id* attribute
336
+ # and do not wait for the browser to reach ready state.
337
+ # @param (see #click_button_by_id)
338
+ # @return (see #click)
339
+ def click_link_no_wait_by_id(browser, what, desc = '')
340
+ click_no_wait(browser, :link, :id, what, desc)
278
341
  end
279
342
 
280
343
  alias click_no_wait_id click_link_no_wait_by_id
@@ -282,266 +345,241 @@ _Example_
282
345
  alias click_id_no_wait click_link_no_wait_by_id
283
346
  alias click_no_wait_link_by_id click_link_no_wait_by_id
284
347
 
285
- # :category: User Input
286
- def click_file_field_by_id(browser, strg, desc = '')
287
- click(browser, :file_field, :id, strg, desc)
288
- end
289
-
290
- # :category: User Input
291
- def click_img_by_alt(browser, strg, desc = '')
292
- click(browser, :image, :alt, strg, desc)
293
- end
294
-
295
- # :category: User Input
296
- def click_img_by_title(browser, strg, desc = '')
297
- click(browser, :image, :title, strg, desc)
298
- end
299
-
300
- # :category: User Input
301
- def click_img_by_xpath_and_name(browser, strg, desc = '')
302
- msg = "Click image by xpath where name='#{strg}' #{desc}"
303
- if browser.link(:xpath, "//input[@name = '#{strg}']").click
304
- passed_to_log(msg)
305
- true
306
- else
307
- failed_to_log(msg)
308
- end
309
- rescue
310
- failed_to_log("Unable to click image by xpath where name='#{strg}' #{desc} '#{$!}'")
311
- end
312
-
313
- alias click_img_by_xpath click_img_by_xpath_and_name
314
- alias click_image_by_xpath click_img_by_xpath_and_name
315
- alias click_image_by_xpath_and_name click_img_by_xpath_and_name
316
-
317
- # :category: User Input
318
- def click_img_no_wait_by_alt(browser, strg, desc = '')
319
- click_no_wait(browser, :image, :alt, strg, desc)
348
+ # Click an image element identified by the value of its *:alt* attribute
349
+ # and do not wait for the browser to reach ready state.
350
+ # @param (see #click_button_by_id)
351
+ # @return (see #click)
352
+ def click_img_no_wait_by_alt(browser, what, desc = '')
353
+ click_no_wait(browser, :image, :alt, what, desc)
320
354
  end
321
355
 
322
356
  alias click_img_by_alt_no_wait click_img_no_wait_by_alt
323
- # :category: User Input
324
- def click_img_by_src(browser, strg, desc = '')
325
- click(browser, :image, :src, strg, desc)
326
- end
327
357
 
328
- # :category: User Input
329
- def click_img_by_src_and_index(browser, strg, index, desc = '')
330
- msg = "Click image by src='#{strg}' and index=#{index}"
331
- msg << " #{desc}" if desc.length > 0
332
- browser.image(:src => strg, :index => index).click
333
- if validate(browser, @myName, __LINE__)
334
- passed_to_log(msg)
335
- true
336
- end
337
- rescue
338
- failed_to_log("Unable to #{msg} '#{$!}'")
358
+ # Click a button element identified by the value in its text (innerHTML)
359
+ # and do not wait for the browser to reach ready state.
360
+ # @param (see #click_button_by_id)
361
+ # @return (see #click)
362
+ def click_button_no_wait_by_text(browser, what, desc = '')
363
+ click_no_wait(browser, :button, :text, what, desc)
339
364
  end
340
365
 
341
- # :category: User Input
342
- def click_link_by_value(browser, strg, desc = '')
343
- click(browser, :link, :value, strg, desc)
366
+ # Click a button element identified by the value of its *:value* attribute
367
+ # and do not wait for the browser to reach ready state.
368
+ # @param (see #click_button_by_id)
369
+ # @return (see #click)
370
+ def click_button_no_wait_by_value(browser, what, desc = '')
371
+ click_no_wait(browser, :button, :value, what, desc)
344
372
  end
345
373
 
346
- =begin rdoc
347
- :category: A_rdoc_test
348
- Click a link identified by the value in its text attribute. Calls click()
349
-
350
- _Parameters_::
351
-
352
- *browser* - a reference to the browser window to be tested
353
-
354
- *strg* - a string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
355
-
356
- *desc* - a string containing a message or description intended to appear in the log and/or report output
357
-
358
-
359
- _Example_
360
-
361
- # html for a link element:
362
- # <a href="http://pragmaticprogrammer.com/titles/ruby/" id="one" name="book">Pickaxe</a>
363
- click_link_by_text(browser, 'Pickaxe', 'Open the page for the Pickaxe book')
364
-
365
- =end
366
-
367
- def click_link_by_text(browser, strg, desc = '')
368
- click(browser, :link, :text, strg, desc)
374
+ # Click a button element identified by the value of its *:name* attribute
375
+ # and do not wait for the browser to reach ready state.
376
+ # @param (see #click_button_by_id)
377
+ # @return (see #click)
378
+ def click_link_by_name_no_wait(browser, what, desc = '')
379
+ click_no_wait(browser, :link, :name, what, desc)
369
380
  end
370
381
 
371
- alias click_link click_link_by_text
372
- # :category: A_rdoc_test
373
- alias click_text click_link_by_text
374
- alias click_js_button click_link_by_text
382
+ alias click_no_wait_name click_link_by_name_no_wait
383
+ alias click_name_no_wait click_link_by_name_no_wait
375
384
 
376
- # :category: User Input
377
- def click_link_by_class(browser, strg, desc = '')
378
- click(browser, :link, :class, strg, desc)
385
+ # Click a link element identified by the value in its text (innerHTML)
386
+ # and do not wait for the browser to reach ready state.
387
+ # @param (see #click_button_by_id)
388
+ # @return (see #click)
389
+ def click_link_by_text_no_wait(browser, what, desc = '')
390
+ click_no_wait(browser, :link, :text, what, desc)
379
391
  end
380
392
 
381
- alias click_class click_link_by_class
393
+ alias click_no_wait_text click_link_by_text_no_wait
394
+ alias click_text_no_wait click_link_by_text_no_wait
382
395
 
383
- # :category: User Input
384
- def click_button_no_wait_by_text(browser, strg, desc = '')
385
- click_no_wait(browser, :button, :text, strg, desc)
396
+ # Click a link element identified by the value of its *:title* attribute
397
+ # and do not wait for the browser to reach ready state.
398
+ # @param (see #click_button_by_id)
399
+ # @return (see #click)
400
+ def click_title_no_wait(browser, what, desc = '')
401
+ click_no_wait(browser, :link, :title, what, desc)
386
402
  end
387
403
 
388
- # :category: User Input
389
- def click_button_no_wait_by_value(browser, strg, desc = '')
390
- click_no_wait(browser, :button, :value, strg, desc)
391
- end
404
+ # @!endgroup Click No Wait
392
405
 
393
- # :category: User Input
394
- def click_link_by_name_no_wait(browser, strg, desc = '')
395
- click_no_wait(browser, :link, :name, strg, desc)
406
+ # @!group Xpath
407
+
408
+ # Click a button element identified by the value of its *:id* attribute using the xpath functionality in Watir.
409
+ # A button is an HTML element with tag 'input' and type 'submit' or 'button'.
410
+ # @note Normally used only when the element is not located by other methods.
411
+ # @param (see #click_button_by_id)
412
+ # @return (see #click)
413
+ def click_button_by_xpath_and_id(browser, what, desc = '')
414
+ click(browser, :button, :xpath, "//a[@id = '#{what}']", desc)
396
415
  end
397
416
 
398
- alias click_no_wait_name click_link_by_name_no_wait
399
- alias click_name_no_wait click_link_by_name_no_wait
417
+ alias click_button_by_xpath click_button_by_xpath_and_id
400
418
 
401
- # :category: User Input
402
- def click_link_by_text_no_wait(browser, strg, desc = '')
403
- click_no_wait(browser, :link, :text, strg, desc)
419
+ # Click a link element identified by the value of its *:id* attribute using the xpath functionality in Watir.
420
+ # @note Normally used only when the element is not located by other methods.
421
+ # @param (see #click_button_by_id)
422
+ # @return (see #click)
423
+ def click_link_by_xpath_and_id(browser, what, desc = '')
424
+ click(browser, :link, :xpath, "//a[@id = '#{what}']", desc)
404
425
  end
405
426
 
406
- alias click_no_wait_text click_link_by_text_no_wait
407
- alias click_text_no_wait click_link_by_text_no_wait
427
+ alias click_link_by_xpath click_link_by_xpath_and_id
408
428
 
409
- # :category: User Input
410
- def click_span_by_text(browser, strg, desc = '')
411
- if not desc and not strg.match(/Save|Open|Close|Submit|Cancel/)
412
- desc = 'to navigate to selection'
413
- end
414
- msg = "Click span containing text '#{strg}'."
415
- msg << " #{desc}" if desc.length > 0
416
- if validate(browser, @myName, __LINE__)
417
- passed_to_log("#{msg}")
418
- end
419
- rescue
420
- failed_to_log("Unable to #{msg}: '#{$!}'")
429
+ # Click an image element identified by the value of its *:name* attribute using the xpath functionality in Watir.
430
+ # @note Normally used only when the element is not located by other methods.
431
+ # @param (see #click_button_by_id)
432
+ # @return (see #click)
433
+ def click_img_by_xpath_and_name(browser, what, desc = '')
434
+ click(browser, :image, :xpath, "//a[@id = '#{what}']", desc)
421
435
  end
422
436
 
423
- # TODO no logging yet. slow.# :category: User Input
424
- def click_span_with_text(browser, trgt, desc = '')
425
- msg = "Find and click span containing text '#{trgt}'."
426
- msg << " #{desc}" if desc.length > 0
427
- spans = browser.spans
428
- x = 0
429
- spans.each do |span|
430
- x += 1
431
- debug_to_log("Span #{x}: #{span.text}")
432
- aText = span.text
433
- if aText and aText.size > 0
434
- if aText =~ /#{trgt}/
435
- break
436
- end
437
- end
438
- end
439
- spans[x].click
440
- end
437
+ alias click_img_by_xpath click_img_by_xpath_and_name
438
+ alias click_image_by_xpath click_img_by_xpath_and_name
439
+ alias click_image_by_xpath_and_name click_img_by_xpath_and_name
441
440
 
442
- # :category: User Input
443
- def click_link_by_title(browser, strg, desc = '')
444
- click(browser, :link, :title, strg, desc)
445
- end
441
+ # @!endgroup Xpath
446
442
 
447
- alias click_title click_link_by_title
448
- # :category: User Input
449
- def click_title_no_wait(browser, strg, desc = '')
450
- click_no_wait(browser, :link, :title, strg, desc)
451
- end
443
+ # @!group Core
452
444
 
453
- # :category: User Input
454
- def click_table_row_with_text_by_id(browser, ptrn, strg, column = nil)
455
- msg = "id=#{ptrn} row with text='#{strg}"
456
- table = get_table_by_id(browser, /#{ptrn}/)
457
- if table
458
- index = get_index_of_row_with_text(table, strg, column)
459
- if index
460
- table[index].click
461
- if validate(browser, @myName, __LINE__)
462
- passed_to_log("Click #{msg} row index=#{index}.")
463
- index
464
- end
465
- else
466
- failed_to_log("Table #{msg} not found to click.")
467
- end
468
- else
469
- failed_to_log("Table id=#{ptrn} not found.")
470
- end
445
+ # Click an image element identified by the value of its *:src* attribute and its index
446
+ # within the array of image elements with src containing <b>*what*</b> and
447
+ # within the container referred to by <b>*browser*</b>.
448
+ # @param [Watir::Browser, Watir::Container] browser A reference to the browser window or container element to be tested.
449
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
450
+ # @param [Fixnum] index An integer that indicates the index of the element within the array of image elements with src containing <b>*what*</b>.
451
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
452
+ # @return (see #click)
453
+ def click_img_by_src_and_index(browser, what, index, desc = '')
454
+ msg = "Click image by src='#{what}' and index=#{index}"
455
+ msg << " #{desc}" if desc.length > 0
456
+ browser.image(:src => what, :index => index).click
457
+ passed_to_log(msg)
458
+ true
471
459
  rescue
472
- failed_to_log("Unable to click table #{msg}: '#{$!}' (#{__LINE__}) ")
460
+ failed_to_log("Unable to #{msg} '#{$!}'")
473
461
  end
474
462
 
475
- # :category: User Input
476
- def click_table_row_with_text_by_index(browser, idx, strg, column = nil)
477
- msg = "index=#{idx} row with text='#{strg}"
478
- table = get_table_by_index(browser, idx)
463
+ # Click the first row which contains a particular string in a table identified by attribute and value.
464
+ # A specific column in the table can also be specified.
465
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
466
+ # @param [Symbol] how The element attribute used to identify the specific element.
467
+ # Valid values depend on the kind of element.
468
+ # Common values: :text, :id, :title, :name, :class, :href (:link only)
469
+ # @param [String, Regexp] what A string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
470
+ # @param [String] text Full text string to be found in the table row.
471
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
472
+ # @param [Fixnum] column Integer indicating the column to search for the text string.
473
+ # If not supplied all columns will be checked.
474
+ # @return (see #click)
475
+ #
476
+ def click_table_row_with_text(browser, how, what, text, desc = '', column = nil)
477
+ msg = build_message("Click row with text #{text} in table :#{how}=>'#{what}.", desc)
478
+ table = get_table(browser, how, what, desc)
479
479
  if table
480
- index = get_index_of_row_with_text(table, strg, column)
480
+ index = get_index_of_row_with_text(table, text, column)
481
481
  if index
482
482
  table[index].click
483
- if validate(browser, @myName, __LINE__)
484
- passed_to_log("Click #{msg} row index=#{index}.")
483
+ passed_to_log(msg)
485
484
  index
486
- end
487
485
  else
488
- failed_to_log("Table #{msg} not found to click.")
486
+ failed_to_log("#{msg} Row not found.")
489
487
  end
490
488
  else
491
- failed_to_log("Table id=#{ptrn} not found.")
489
+ failed_to_log("#{msg} Table not found.")
492
490
  end
493
491
  rescue
494
- failed_to_log("Unable to click table #{msg}: '#{$!}' (#{__LINE__}) ")
495
- end
496
-
497
- def double_click_table_row_with_text_by_id(browser, ptrn, strg, column = nil)
498
- msg = "id=#{ptrn} row with text='#{strg}"
499
- table = get_table_by_id(browser, /#{ptrn}/)
500
- if table
501
- index = get_index_of_row_with_text(table, strg, column)
502
- if index
503
- table[index].fire_event('ondblclick')
504
- if validate(browser, @myName, __LINE__)
505
- passed_to_log("Double click #{msg} row index=#{index}.")
506
- index
507
- end
508
- else
509
- failed_to_log("Table #{msg} not found to double click.")
510
- end
511
- else
512
- failed_to_log("Table id=#{ptrn} not found.")
513
- end
514
- rescue
515
- failed_to_log("Unable to double click table #{msg}: '#{$!}' (#{__LINE__}) ")
492
+ failed_to_log("Unable to #{msg}: '#{$!}'")
516
493
  end
517
494
 
518
- def double_click_table_row_with_text_by_index(browser, idx, strg, column = nil)
519
- msg = "index=#{idx} row with text='#{strg}"
520
- table = get_table_by_index(browser, idx)
495
+ # Double click the first row which contains a particular string in a table identified by attribute and value.
496
+ # A specific column in the table can also be specified.
497
+ # Uses fire_event method in Watir to send 'onDblClick' event.
498
+ # @param (see #click_table_row_with_text)
499
+ # @return (see #click)
500
+ #
501
+ def double_click_table_row_with_text(browser, how, what, text, desc = '', column = nil)
502
+ msg = build_message("Double click row with text #{text} in table :#{how}=>'#{what}.", desc)
503
+ table = get_table(browser, how, what, desc)
521
504
  if table
522
- index = get_index_of_row_with_text(table, strg, column)
505
+ index = get_index_of_row_with_text(table, text, column)
523
506
  if index
524
- row = table[index]
525
507
  table[index].fire_event('ondblclick')
526
- row.fire_event('ondblclick')
527
- if validate(browser, @myName, __LINE__)
528
- passed_to_log("Double click #{msg} row index=#{index}.")
508
+ passed_to_log(msg)
529
509
  index
530
- end
531
510
  else
532
- failed_to_log("Table #{msg} not found to double click.")
511
+ failed_to_log("#{msg} Row not found.")
533
512
  end
534
513
  else
535
- failed_to_log("Table id=#{ptrn} not found.")
514
+ failed_to_log("#{msg} Table not found.")
536
515
  end
537
516
  rescue
538
- failed_to_log("Unable to double click table #{msg}: '#{$!}' (#{__LINE__}) ")
517
+ failed_to_log("Unable to #{msg}: '#{$!}'")
539
518
  end
540
519
 
541
- def click_popup_button(title, button, waitTime= 9, user_input=nil)
520
+ # @!endgroup Core
521
+
522
+ # @!group Tables
523
+
524
+ # Click the first row which contains a particular string in a table identified by the value in its *:id* attribute.
525
+ #
526
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
527
+ # @param [String, Regexp] what A string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
528
+ # @param [String] text Full text string to be found in the table row.
529
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
530
+ # @param [Fixnum] column Integer indicating the column to search for the text string.
531
+ # If not supplied all columns will be checked.
532
+ # @return (see #click)
533
+ #
534
+ def click_table_row_with_text_by_id(browser, what, text, desc = '', column = nil)
535
+ click_table_row_with_text(browser, :id, what, text, desc, column)
536
+ end
537
+
538
+ # Click the first row which contains a particular string in a table identified by its index
539
+ # in the array of tables contained in <b>*browser*</b>.
540
+ # A specific column in the table can also be specified.
541
+ #
542
+ # @param (see #click_table_row_with_text_by_id)
543
+ # @return (see #click)
544
+ #
545
+ def click_table_row_with_text_by_index(browser, what, text, desc = '', column = nil)
546
+ click_table_row_with_text(browser, :id, what, text, desc, column)
547
+ end
548
+
549
+ # Double click the first row which contains a particular string in a table identified by the value in its *:id* attribute.
550
+ # A specific column in the table can also be specified.
551
+ #
552
+ # @param (see #click_table_row_with_text_by_id)
553
+ # @return (see #click)
554
+ #
555
+ def double_click_table_row_with_text_by_id(browser, what, text, desc = '', column = nil)
556
+ double_click_table_row_with_text(browser, :id, what, text, desc, column)
557
+ end
558
+
559
+ # Double click the first row which contains a particular string in a table identified by its index
560
+ # in the array of tables contained in <b>*browser*</b>.
561
+ # A specific column in the table can also be specified.
562
+ # @param (see #click_table_row_with_text_by_id)
563
+ # @return (see #click)
564
+ #
565
+ def double_click_table_row_with_text_by_index(browser, idx, what, column = nil)
566
+ double_click_table_row_with_text(browser, :index, what, text, desc, column)
567
+ end
568
+
569
+ # @!endgroup Tables
570
+
571
+ # @!group Core
572
+
573
+ # Click a specifific button on a popup window.
574
+ # (Windows only)
575
+ # @param [String] title A string starting at the beginning of the title which uniquely identifies the popup window.
576
+ # @param [String] button The value displayed for the button (e.g. OK, Yes, Cancel, etc)
577
+ # @param [Fixnum] wait Integer indicating the number of seconds to wait for the popup window to appear.
578
+ # @return (see #click)
579
+ def click_popup_button(title, button, wait= 9, user_input=nil)
542
580
  #TODO: is winclicker still viable/available?
543
581
  wc = WinClicker.new
544
- if wc.clickWindowsButton(title, button, waitTime)
582
+ if wc.clickWindowsButton(title, button, wait)
545
583
  passed_to_log("Window '#{title}' button '#{button}' found and clicked.")
546
584
  true
547
585
  else
@@ -549,7 +587,7 @@ _Example_
549
587
  end
550
588
  wc = nil
551
589
  # get a handle if one exists
552
- # hwnd = $ie.enabled_popup(waitTime)
590
+ # hwnd = $ie.enabled_popup(wait)
553
591
  # if (hwnd) # yes there is a popup
554
592
  # w = WinClicker.new
555
593
  # if ( user_input )
@@ -565,240 +603,160 @@ _Example_
565
603
  # end
566
604
  end
567
605
 
568
- def select_option(browser, how, what, which, value, desc = '')
569
- msg = "Select option #{which}='#{value}' from list #{how}=#{what}. #{desc}"
570
- list = browser.select_list(how, what)
571
- case which
572
- when :text
573
- list.select(value)
574
- when :value
575
- list.select_value(value)
576
- when :index
577
- all = list.getAllContents
578
- txt = all[value]
579
- list.select(txt)
580
- else
581
- na = "#{__method__} cannot support select by '#{which}'. (#{msg})"
582
- debug_to_log(na, __LINE__, true)
583
- raise na
584
- end
585
- passed_to_log(msg)
586
- rescue
587
- failed_to_log("#Unable to #{msg}': '#{$!}'")
588
- end
589
-
590
- def select_option_from_list(list, what, what_strg, desc = '')
606
+ # Select option from select list (dropdown) already identified and passed to the method. Selection can be by *:text* or *:value*.
607
+ # @param [Watir::SelectList] list A reference to the specific select list object.
608
+ # @param [Symbol] how Either :text or :value.
609
+ # @param [String/Rexexp] what A string or regular expression that will uniquely identify the option to select.
610
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
611
+ # @param [Boolean] nofail If true do not log a failed message if the option is not found in the select list.
612
+ # @return (see #click)
613
+ def select_option_from_list(list, how, what, desc = '', nofail = false)
614
+ msg = build_message("Select :#{how}=>'#{what}", desc)
591
615
  ok = true
592
- msg = "#{__method__.to_s.titleize} "
593
616
  if list
594
- msg << "list id=#{list.id}: "
595
- case what
617
+ case which
596
618
  when :text
597
- list.select(what_strg) #TODO: regex?
619
+ list.select(what) #TODO: regex?
598
620
  when :value
599
- list.select_value(what_strg) #TODO: regex?
621
+ list.select_value(what) #TODO: regex?
600
622
  when :index
601
- list.select(list.getAllContents[what_strg.to_i])
623
+ list.select(list.getAllContents[what.to_i])
602
624
  else
603
- msg << "select by #{what} not supported. #{desc} (#{__LINE__})"
604
- failed_to_log(msg)
625
+ failed_to_log("#{msg} Select by #{how} not supported.")
605
626
  ok = false
606
627
  end
607
628
  if ok
608
- msg << "#{what}='#{what_strg}' selected. #{desc}"
609
629
  passed_to_log(msg)
610
630
  true
631
+ else
632
+ if nofail
633
+ passed_to_log("#{msg} Option not found. No Fail specified.")
634
+ true
635
+ else
636
+ failed_to_log("#{msg} Option not found.")
637
+ end
611
638
  end
612
639
  else
613
- failed_to_log("#{__method__.to_s.titleize} list not found. #{desc} (#{__LINE__})")
640
+ failed_to_log("#{msg} Select list not found.")
614
641
  end
615
642
  rescue
616
- failed_to_log("#{__method__.to_s.titleize}: #{what}='#{what_strg}' could not be selected: '#{$!}'. #{desc} (#{__LINE__})")
643
+ failed_to_log("Unable to #{msg} '#{$!}'")
617
644
  end
618
645
 
619
- =begin rdoc
620
- :category: A_rdoc_test
621
- Select an option from a specific drop down list. The drop down (select list) is id
622
-
623
- _Parameters_::
624
-
625
- *browser* - a reference to the browser window to be tested
626
-
627
- *how* - the element attribute used to identify the specific element. Valid values depend on the kind of element.
628
- Common values: :text, :id, :title, :name, :class, :href (:link only)
629
-
630
- *what* - a string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
631
-
632
- *desc* - a string containing a message or description intended to appear in the log and/or report output
633
-
634
- _Example_
646
+ # Select option from select list identified by *how* and *what*. Option is identified by *which* and *value*
647
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
648
+ # @param [Symbol] how The element attribute used to identify the specific element.
649
+ # Valid values depend on the kind of element.
650
+ # Common values: :text, :id, :title, :name, :class, :href (:link only)
651
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
652
+ # @param [Symbol] which Either :text or :value.
653
+ # @param [String/Rexexp] option A string or regular expression that will uniquely identify the option to select.
654
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
655
+ # @param [Boolean] nofail If true do not log a failed message if the option is not found in the select list.
656
+ # @return (see #click)
657
+ def select_option(browser, how, what, which, option, desc = '', nofail = false)
658
+ list = browser.select_list(how, what)
659
+ msg = build_message(" from list with :#{how}=>'#{what}", desc)
660
+ select_option_from_list(list, which, option, msg, nofail)
661
+ end
635
662
 
636
- # html for a link element:
637
- # <a href="http://pragmaticprogrammer.com/titles/ruby/" id="one" name="book">Pickaxe</a>
638
- click_no_wait(browser, :link, :text, 'Pickaxe')
663
+ # @!endgroup Core
639
664
 
640
- =end
665
+ # @!group Select
641
666
 
642
- def select_option_by_id_and_option_text(browser, strg, option, nofail=false, desc = '')
643
- msg = "Select list id=#{strg} option text='#{option}' selected."
644
- msg << " #{desc}" if desc.length > 0
645
- list = browser.select_list(:id, strg)
646
- list.select(option)
647
- # browser.select_list(:id, strg).select(option) #(browser.select_list(:id, strg).getAllContents[option])
648
- if validate(browser, @myName, __LINE__)
649
- passed_to_log(msg)
650
- true
651
- end
652
- rescue
653
- if !nofail
654
- failed_to_log("#{msg} '#{$!}'")
655
- end
667
+ # Select option from select list (dropdown) identified by the value in its *:id* attribute. Option is identified by *which* and *value*
668
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
669
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
670
+ # @param [String/Rexexp] option A string or regular expression that will uniquely identify the option to select.
671
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
672
+ # @param [Boolean] nofail If true do not log a failed message if the option is not found in the select list.
673
+ # @return (see #click)
674
+ def select_option_by_id_and_option_text(browser, what, option, nofail = false, desc = '')
675
+ select_option(browser, :id, what, :text, option, desc, nofail)
656
676
  end
657
677
 
658
678
  alias select_option_by_id select_option_by_id_and_option_text
659
679
  alias select_option_by_id_and_text select_option_by_id_and_option_text
660
680
 
661
- def select_option_by_name_and_option_text(browser, strg, option, desc = '')
662
- msg = "Select list name=#{strg} option text='#{option}' selected."
663
- msg << " #{desc}" if desc.length > 0
664
- begin
665
- list = browser.select_list(:name, strg)
666
- rescue => e
667
- if not rescue_me(e, __method__, "#{__LINE__}: select_list(:name,'#{strg}')", "#{browser.class}")
668
- raise e
669
- end
670
- end
671
- begin
672
- list.select(option)
673
- rescue => e
674
- if not rescue_me(e, __method__, "#{__LINE__}: select_list#select('#{option}')", "#{browser.class}")
675
- raise e
676
- end
677
- end
678
- if validate(browser, @myName, __LINE__)
679
- passed_to_log(msg)
680
- true
681
- end
682
- rescue
683
- failed_to_log("#{msg} '#{$!}'")
681
+ # Select option from select list (dropdown) identified by the value in its *:name* attribute. Option is selected by its *:text* attribute.
682
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
683
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
684
+ # @param [String/Rexexp] option A string or regular expression that will uniquely identify the option to select.
685
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
686
+ # @return (see #click)
687
+ def select_option_by_name_and_option_text(browser, what, option, desc = '')
688
+ select_option(browser, :name, what, :text, option, desc)
684
689
  end
685
690
 
686
691
  alias select_option_by_name select_option_by_name_and_option_text
687
692
 
688
- def select_option_by_title_and_option_text(browser, strg, option, desc = '')
689
- msg = "Select list name=#{strg} option text='#{option}' selected."
690
- msg << " #{desc}" if desc.length > 0
691
- browser.select_list(:title, strg).select(option)
692
- if validate(browser, @myName, __LINE__)
693
- passed_to_log(msg)
694
- end
695
- rescue
696
- failed_to_log("#{msg} '#{$!}'")
693
+ # Select option from select list (dropdown) identified by the value in its *:name* attribute. Option is selected by its *:text* attribute.
694
+ # @param (see #select_option_by_name_and_option_text)
695
+ # @return (see #click)
696
+ def select_option_by_title_and_option_text(browser, what, option, desc = '')
697
+ select_option(browser, :title, what, :text, option, desc)
697
698
  end
698
699
 
699
- def select_option_by_class_and_option_text(browser, strg, option, desc = '')
700
- msg = "Select list class=#{strg} option text='#{option}' selected."
701
- msg << " #{desc}" if desc.length > 0
702
- browser.select_list(:class, strg).select(option)
703
- if validate(browser, @myName, __LINE__)
704
- passed_to_log(msg)
705
- true
706
- end
707
- rescue
708
- failed_to_log("#{msg} '#{$!}'")
700
+ # Select option from select list (dropdown) identified by the value in its *:class* attribute. Option is selected by its *:text* attribute.
701
+ # @param (see #select_option_by_name_and_option_text)
702
+ # @return (see #click)
703
+ def select_option_by_class_and_option_text(browser, what, option, desc = '')
704
+ select_option(browser, :class, what, :text, option, desc)
709
705
  end
710
706
 
711
- def select_option_by_name_and_option_value(browser, strg, option, desc = '')
712
- msg = "Select list name=#{strg} option value='#{option}' selected."
713
- msg << " #{desc}" if desc.length > 0
714
- begin
715
- list = browser.select_list(:name, strg)
716
- rescue => e
717
- if not rescue_me(e, __method__, "#{__LINE__}: select_list(:name,'#{strg}')", "#{browser.class}")
718
- raise e
719
- end
720
- end
721
- begin
722
- list.select_value(option)
723
- rescue => e
724
- if not rescue_me(e, __method__, "#{__LINE__}: select_list#select_value('#{option}')", "#{browser.class}")
725
- raise e
726
- end
727
- end
728
- if validate(browser, @myName, __LINE__)
729
- passed_to_log(msg)
730
- true
731
- end
732
- rescue
733
- failed_to_log("#{msg} '#{$!}'")
707
+ # Select option from select list (dropdown) identified by the value in its *:name* attribute. Option is selected by its *:value* attribute.
708
+ # @param (see #select_option_by_name_and_option_text)
709
+ # @return (see #click)
710
+ def select_option_by_name_and_option_value(browser, what, option, desc = '')
711
+ select_option(browser, :name, what, :value, option, desc)
734
712
  end
735
713
 
736
- def select_option_by_id_and_option_value(browser, strg, option, desc = '')
737
- msg = "Select list name=#{strg} option value='#{option}' selected."
738
- msg << " #{desc}" if desc.length > 0
739
- begin
740
- list = browser.select_list(:id, strg)
741
- rescue => e
742
- if not rescue_me(e, __method__, "#{__LINE__}: select_list(:text,'#{strg}')", "#{browser.class}")
743
- raise e
744
- end
745
- end
746
- sleep(0.5) unless @targetBrowser.abbrev == 'IE'
747
- begin
748
- list.select_value(option)
749
- rescue => e
750
- if not rescue_me(e, __method__, "#{__LINE__}: select_list#select_value('#{option}')", "#{browser.class}")
751
- raise e
752
- end
753
- end
754
- if validate(browser, @myName, __LINE__)
755
- passed_to_log(msg)
756
- true
757
- end
758
- rescue
759
- failed_to_log("#{msg} '#{$!}'")
714
+ # Select option from select list (dropdown) identified by the value in its *:id* attribute. Option is selected by its *:value* attribute.
715
+ # @param (see #select_option_by_name_and_option_text)
716
+ # @return (see #click)
717
+ def select_option_by_id_and_option_value(browser, what, option, desc = '')
718
+ select_option(browser, :id, what, :value, option, desc)
760
719
  end
761
720
 
762
- def select_option_by_id_and_index(browser, strg, idx, desc = '')
763
- msg = "Select list id=#{strg} index='#{idx}' selected."
764
- msg << " #{desc}" if desc.length > 0
765
- list = browser.select_list(:id, strg)
766
- all = list.getAllContents
767
- txt = all[idx]
768
- browser.select_list(:id, strg).set(browser.select_list(:id, strg).getAllContents[idx])
769
- if validate(browser, @myName, __LINE__)
770
- passed_to_log(msg)
771
- true
772
- end
773
- rescue
774
- failed_to_log("#{msg} '#{$!}'")
721
+ # Select option from select list (dropdown) identified by the value in its *:id* attribute.
722
+ # Option is selected by its index withing the select list's array of options.
723
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
724
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
725
+ # @param [Fixnum] index An integer that indicates the index of the element within the array of options.
726
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
727
+ # @return (see #click)
728
+ def select_option_by_id_and_index(browser, what, index, desc = '')
729
+ select_option(browser, :id, what, :index, index, desc)
775
730
  end
776
731
 
777
- def select_option_by_name_and_index(browser, strg, idx)
778
- # TODO add check that both list and option exist
779
- msg = "Select list name=#{strg} index='#{idx}' selected."
780
- msg << " #{desc}" if desc.length > 0
781
- browser.select_list(:name, strg).set(browser.select_list(:name, strg).getAllContents[idx])
782
- if validate(browser, @myName, __LINE__)
783
- passed_to_log(msg)
784
- true
785
- end
786
- rescue
787
- failed_to_log("#{msg} '#{$!}'")
732
+ # Select option from select list (dropdown) identified by the value in its *:name* attribute. Option is selected by its *:index* attribute.
733
+ # @param (see #select_option_by_id_and_index)
734
+ # @return (see #click)
735
+ def select_option_by_name_and_index(browser, what, option, desc = '')
736
+ select_option(browser, :name, what, :index, option, desc)
788
737
  end
789
738
 
790
- def select_option_by_xpath_and_index(browser, strg, idx)
791
- msg = "Select list xpath=#{strg} index='#{idx}' selected."
792
- msg << " #{desc}" if desc.length > 0
793
- browser.select_list(:xpath, strg).set(browser.select_list(:xpath, strg).getAllContents[idx])
794
- if validate(browser, nil, __LINE__)
795
- passed_to_log(msg)
796
- true
797
- end
798
- rescue
799
- failed_to_log("#{msg} '#{$!}'")
739
+ # Select option from select list (dropdown) identified by the xpath command supplied in *what*. Option is selected by its *:index* attribute.
740
+ # @param (see #select_option_by_id_and_index)
741
+ # @return (see #click)
742
+ def select_option_by_xpath_and_index(browser, what, option, desc = '')
743
+ select_option(browser, :xpath, what, :index, option, desc)
800
744
  end
801
745
 
746
+ # @!endgroup Select
747
+
748
+ # @!group Core
749
+
750
+ # Set radio button or checkbox to selected.
751
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
752
+ # @param [Symbol] element The kind of element to click. Must be either :radio or :checkbox.
753
+ # @param [Symbol] how The element attribute used to identify the specific element.
754
+ # Valid values depend on the kind of element.
755
+ # Common values: :text, :id, :title, :name, :class, :href (:link only)
756
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
757
+ # @param [String, Regexp] value A string or a regular expression to be found in the *:value* attribute of the radio or checkbox.
758
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
759
+ # @return (see #click)
802
760
  def set(browser, element, how, what, value = nil, desc = '')
803
761
  msg = "Set #{element} #{how}=>'#{what}' "
804
762
  msg << ", :value=>#{value} " if value
@@ -811,112 +769,265 @@ _Example_
811
769
  else
812
770
  failed_to_log("#{__method__}: #{element} not supported")
813
771
  end
814
- if validate(browser, @myName, __LINE__)
815
772
  passed_to_log(msg)
816
773
  true
817
- end
818
774
  rescue
819
- failed_to_log("#{msg} '#{$!}'")
820
- end
821
-
822
- def set_checkbox(browser, how, what, value, desc = '')
823
- set(browser, :checkbox, how, what, value, desc)
824
- end
825
-
826
- def set_checkbox_by_class(browser, strg, value = nil, desc = '')
827
- set(browser, :checkbox, :class, strg, value, desc)
828
- end
829
-
830
- def set_checkbox_by_id(browser, strg, value = nil, desc = '')
831
- set(browser, :checkbox, :id, strg, value, desc)
832
- end
833
-
834
- def set_checkbox_by_name(browser, strg, value = nil, desc = '')
835
- set(browser, :checkbox, :name, strg, value, desc)
836
- end
837
-
838
- def set_checkbox_by_title(browser, strg, value = nil, desc = '')
839
- set(browser, :checkbox, :title, strg, value, desc)
840
- end
841
-
842
- def set_checkbox_by_value(browser, strg, desc = '')
843
- set(browser, :checkbox, :value, strg, nil, desc)
844
- end
775
+ failed_to_log("#{msg} '#{$!}'")
776
+ end
845
777
 
846
- def set_radio(browser, how, what, value = nil, desc = '')
847
- set(browser, :radio, how, what, value, desc)
778
+ # Set file field element, identified by *how* and +what, to a specified file path and name.
779
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
780
+ # @param [Symbol] how The element attribute used to identify the specific element.
781
+ # Valid values depend on the kind of element.
782
+ # Common values: :text, :id, :title, :name, :class, :href (:link only)
783
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
784
+ # @param [String] filespec The full path and name of the target file.
785
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
786
+ # @return (see #click)
787
+ def set_file_field(browser, how, what, filespec, desc = '')
788
+ msg = build_message("Set file field #{how}=>#{what} to '#{filespec}.", desc)
789
+ ff = browser.file_field(how, what)
790
+ if ff
791
+ ff.set filespec
792
+ sleep_for(8)
793
+ passed_to_log(msg)
794
+ true
795
+ else
796
+ failed_to_log("#{msg} File field not found.")
797
+ end
798
+ rescue
799
+ failed_to_log("Unable to #{msg} '#{$!}'")
848
800
  end
849
801
 
802
+ # Set radio button as selected using two element attributes.
803
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
804
+ # @param [Symbol] how1 The first element attribute used to identify the specific element.
805
+ # Valid values depend on the kind of element.
806
+ # Common values: :text, :id, :title, :name, :class, :href (:link only)
807
+ # @param [String, Regexp] what1 A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
808
+ # @param [Symbol] how2 The second element attribute used to identify the specific element.
809
+ # @param [String, Regexp] what2 A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
810
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
811
+ # @return (see #click)
850
812
  def set_radio_two_attributes(browser, how1, what1, how2, what2, desc = '')
851
- msg = "Set radio #{how1}='#{what1}', #{how2}= #{what2}"
852
- msg << " '#{desc}' " if desc.length > 0
813
+ msg = build_message("Set radio #{how1}='#{what1}', #{how2}= #{what2}", desc)
853
814
  browser.radio(how1 => what1, how2 => what2).set
854
- if validate(browser, @myName, __LINE__)
855
815
  passed_to_log(msg)
856
816
  true
857
- end
858
817
  rescue
859
818
  failed_to_log("#{msg} '#{$!}'")
860
819
  end
861
820
 
862
- def set_radio_by_class(browser, strg, value = nil, desc = '')
863
- set(browser, :radio, :class, strg, value, desc)
821
+ #def set_radio_no_wait_by_index(browser, index, desc = '')
822
+ # #TODO: Not supported by Watir 1.8.x
823
+ # msg = "Radio :index=#{index} "
824
+ # radios = browser.radios
825
+ # debug_to_log("\n#{radios}")
826
+ # radio = radios[index]
827
+ # debug_to_log("\n#{radio}")
828
+ # radio.click_no_wait
829
+ # msg << 'set ' + desc
830
+ # passed_to_log(msg)
831
+ # true
832
+ #rescue
833
+ # msg << 'not found ' + desc
834
+ # failed_to_log("#{msg} (#{__LINE__})")
835
+ #end
836
+
837
+ # @!endgroup Core
838
+
839
+ # @!group Set
840
+
841
+ # Set checkbox as checked. Checkbox is identified by the attribute specified in *how* with value *what*. It's *:value* attribute can also be used
842
+ # when needed by specifying *value*.
843
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
844
+ # @param [Symbol] how The element attribute used to identify the specific checkbox.
845
+ # Valid values depend on the kind of element.
846
+ # Common values: :text, :id, :title, :name, :class, :href (:link only)
847
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the checkbox.
848
+ # @param [String, Regexp] value A string or a regular expression to be found in the *:value* attribute of the checkbox.
849
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
850
+ # @return (see #click)
851
+ def set_checkbox(browser, how, what, value = nil, desc = '')
852
+ set(browser, :checkbox, how, what, value, desc)
864
853
  end
865
854
 
866
- def set_radio_by_id(browser, strg, value = nil, desc = '')
867
- set(browser, :radio, :id, strg, value, desc)
855
+ # Set checkbox as checked identified by its *:class* attribute with the value in *what*. It's *:value* attribute can also be used
856
+ # when needed by specifying *value*.
857
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
858
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the checkbox.
859
+ # @param [String, Regexp] value A string or a regular expression to be found in the *:value* attribute of the checkbox.
860
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
861
+ # @return (see #click)
862
+ def set_checkbox_by_class(browser, what, value = nil, desc = '')
863
+ set(browser, :checkbox, :class, what, value, desc)
868
864
  end
869
865
 
870
- def set_radio_by_index(browser, index, desc = '')
871
- set(browser, :radio, :index, index, value, desc)
866
+ # Set checkbox as checked identified by its *:class* attribute with the value in *what*. It's *:value* attribute can also be used
867
+ # when needed by specifying *value*.
868
+ # @param (see #set_checkbox_by_class)
869
+ # @return (see #click)
870
+ def set_checkbox_by_id(browser, what, value = nil, desc = '')
871
+ set(browser, :checkbox, :id, what, value, desc)
872
872
  end
873
873
 
874
- def set_radio_by_name(browser, strg, value = nil, desc = '')
875
- set(browser, :radio, :name, strg, value, desc)
874
+ # Set checkbox as checked identified by its *:name* attribute with the value in *what*. It's *:value* attribute can also be used
875
+ # when needed by specifying *value*.
876
+ # @param (see #set_checkbox_by_class)
877
+ # @return (see #click)
878
+ def set_checkbox_by_name(browser, what, value = nil, desc = '')
879
+ set(browser, :checkbox, :name, what, value, desc)
876
880
  end
877
881
 
878
- def set_radio_by_title(browser, strg, value = nil, desc = '')
879
- set(browser, :radio, :title, strg, value, desc)
882
+ # Set checkbox as checked identified by its *:title* attribute with the value in *what*. It's *:value* attribute can also be used
883
+ # when needed by specifying *value*.
884
+ # @param (see #set_checkbox_by_class)
885
+ # @return (see #click)
886
+ def set_checkbox_by_title(browser, what, value = nil, desc = '')
887
+ set(browser, :checkbox, :title, what, value, desc)
880
888
  end
881
889
 
882
- def set_radio_by_value(browser, strg, desc = '')
883
- set(browser, :radio, :value, strg, nil, desc)
890
+ # Set checkbox as checked identified by its *:value* attribute with the value in *what*.
891
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
892
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the checkbox.
893
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
894
+ # @return (see #click)
895
+ def set_checkbox_by_value(browser, what, desc = '')
896
+ set(browser, :checkbox, :value, what, nil, desc)
884
897
  end
885
898
 
886
- def set_radio_no_wait_by_index(browser, index, desc = '')
887
- #TODO: Not supported by Watir 1.8.x
888
- msg = "Radio :index=#{index} "
889
- radios = browser.radios
890
- debug_to_log("\n#{radios}")
891
- radio = radios[index]
892
- debug_to_log("\n#{radio}")
893
- radio.click_no_wait
894
- if validate(browser)
895
- msg << 'set ' + desc
896
- passed_to_log(msg)
897
- true
898
- end
899
- rescue
900
- msg << 'not found ' + desc
901
- failed_to_log("#{msg} (#{__LINE__})")
899
+ # Set radio button as set. Radio is identified by the attribute specified in *how* with value *what*. It's *:value* attribute can also be used
900
+ # when needed by specifying *value*.
901
+ # @param (see #set_checkbox)
902
+ # @return (see #click)
903
+ def set_radio(browser, how, what, value = nil, desc = '')
904
+ set(browser, :radio, how, what, value, desc)
902
905
  end
903
906
 
904
- def set_radio_by_name_and_index(browser, name, index, desc = '')
905
- set_radio_two_attributes(browser, :name, name, :index, index, desc)
907
+ # Set radio button as set identified by its *:class* attribute with the value in *what*. It's *:value* attribute can also be used
908
+ # when needed by specifying *value*.
909
+ # @param (see #set_checkbox_by_class)
910
+ def set_radio_by_class(browser, what, value = nil, desc = '')
911
+ set(browser, :radio, :class, what, value, desc)
906
912
  end
907
913
 
908
- def set_radio_by_name_and_text(browser, name, text, desc = '')
909
- set_radio_two_attributes(browser, :name, name, :text, text, desc)
910
- end
914
+ # Set radio button as set identified by its *:id* attribute with the value in *what*. It's *:value* attribute can also be used
915
+ # when needed by specifying *value*.
916
+ # @param (see #set_checkbox_by_class)
917
+ # @return (see #click)
918
+ def set_radio_by_id(browser, what, value = nil, desc = '')
919
+ set(browser, :radio, :id, what, value, desc)
920
+ end
911
921
 
922
+ # Set radio button as set identified by its index within the array of radio buttons found in the container specified by *browser*.
923
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
924
+ # @param [Fixnum] index An integer that indicates the index of the element within *browser*.
925
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
926
+ # @return (see #click)
927
+ def set_radio_by_index(browser, index, desc = '')
928
+ set(browser, :radio, :index, index, nil, desc)
929
+ end
930
+
931
+ # Set radio button as set identified by its *:name* attribute with the value in *what*. It's *:value* attribute can also be used
932
+ # when needed by specifying *value*.
933
+ # @param (see #set_checkbox_by_class)
934
+ # @return (see #click)
935
+ def set_radio_by_name(browser, what, value = nil, desc = '')
936
+ set(browser, :radio, :name, what, value, desc)
937
+ end
938
+
939
+ # Set radio button as set identified by its *:title* attribute with the value in *what*. It's *:value* attribute can also be used
940
+ # when needed by specifying *value*.
941
+ # @param (see #set_checkbox_by_class)
942
+ # @return (see #click)
943
+ def set_radio_by_title(browser, what, value = nil, desc = '')
944
+ set(browser, :radio, :title, what, value, desc)
945
+ end
946
+
947
+ # Set radio button as set identified by its *:value* attribute with the value in *what*.
948
+ # @param (see #set_checkbox_by_value)
949
+ # @return (see #click)
950
+ def set_radio_by_value(browser, what, desc = '')
951
+ set(browser, :radio, :value, what, nil, desc)
952
+ end
953
+
954
+ # Set radio button as set identified by its *:name* attribute with the value in *what*
955
+ # and its index within the array of radio buttons with that :name
956
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
957
+ # @param [String, Regexp] what A string or a regular expression to be found in the *:name* attribute that identifies the group of radio buttons.
958
+ # @param [Fixnum] index An integer that indicates the index of the radio button to be set.
959
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
960
+ # @return (see #click)
961
+ def set_radio_by_name_and_index(browser, what, index, desc = '')
962
+ set_radio_two_attributes(browser, :name, what, :index, index, desc)
963
+ end
964
+
965
+ # Set radio button as set identified by its *:name* attribute with the value in *what*
966
+ # and its index within the array of radio buttons with that :name
967
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
968
+ # @param [String, Regexp] what A string or a regular expression to be found in the *:name* attribute that identifies the group of radio buttons.
969
+ # @param [String, Regexp] text A string or a regular expression to be found in the *:text* attribute that uniquely identifies the the radio button to be set.
970
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
971
+ # @return (see #click)
972
+ def set_radio_by_name_and_text(browser, what, text, desc = '')
973
+ set_radio_two_attributes(browser, :name, what, :text, text, desc)
974
+ end
975
+
976
+ # Set radio button as set identified by its *:value* attribute with the value in *what*
977
+ # and its index within the array of radio buttons with that :name
978
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
979
+ # @param [String, Regexp] value A string or a regular expression to be found in the *:value* attribute that identifies the group of radio buttons.
980
+ # @param [Fixnum] index An integer that indicates the index of the radio button to be set.
981
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
982
+ # @return (see #click)
912
983
  def set_radio_by_value_and_index(browser, value, index, desc = '')
913
984
  set_radio_two_attributes(browser, :value, value, :index, index, desc)
914
985
  end
915
986
 
916
- def set_radio_by_name_and_value(browser, strg, value, desc = '')
917
- set_radio(browser, :name, strg, value, desc)
918
- end
919
-
987
+ # Set radio button as set identified by its *:name* attribute with the value in *what*
988
+ # and the *:value* attribute with the value in *value*.
989
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
990
+ # @param [String, Regexp] what A string or a regular expression to be found in the *:name* attribute that identifies the group of radio buttons.
991
+ # @param [String, Regexp] value A string or a regular expression to be found in the *:value* attribute that uniquely identifies the the radio button to be set.
992
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
993
+ # @return (see #click)
994
+ def set_radio_by_name_and_value(browser, what, value, desc = '')
995
+ set_radio(browser, :name, what, value, desc)
996
+ end
997
+
998
+ # Set file field element, identified by its *:name* attribute with the value in *what*.
999
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
1000
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
1001
+ # @param [String] filespec The full path and name of the target file.
1002
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
1003
+ # @return (see #click)
1004
+ def set_file_field_by_name(browser, what, filespec, desc = '')
1005
+ set_file_field(browser, :name, what, filespec, desc)
1006
+ end
1007
+
1008
+ # Set file field element, identified by its *:id* attribute with the value in *what*.
1009
+ # @param (see #set_file_field_by_name)
1010
+ # @return (see #click)
1011
+ def set_file_field_by_id(browser, what, filespec, desc = '')
1012
+ set_file_field(browser, :id, what, filespec, desc)
1013
+ end
1014
+
1015
+ # @!endgroup Set
1016
+
1017
+ # @!group Core
1018
+
1019
+ # Clear (unset) radio, checkbox or text field as identified by the attribute specified in *how* with value *what*.
1020
+ # It's *:value* attribute can also be used when needed by specifying *value* (Ignored for text_field).
1021
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
1022
+ # @param [Symbol] element The kind of element to clear. Must be :radio, :checkbox or :text_field.
1023
+ # @param [Symbol] how The element attribute used to identify the specific checkbox.
1024
+ # Valid values depend on the kind of element.
1025
+ # Common values: :text, :id, :title, :name, :class.
1026
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
1027
+ # @param [String, Regexp] value A string or a regular expression to be found in the *:value* attribute of the element.
1028
+ # In the case of text_field this is the string to be entered in the field.
1029
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
1030
+ # @return (see #click)
920
1031
  def clear(browser, element, how, what, value = nil, desc = '')
921
1032
  msg = "Clear #{element} #{how}=>'#{what}' "
922
1033
  msg << ", value=>#{value} " if value
@@ -931,122 +1042,89 @@ _Example_
931
1042
  else
932
1043
  failed_to_log("#{__method__}: #{element} not supported")
933
1044
  end
934
- if validate(browser, @myName, __LINE__)
935
1045
  passed_to_log(msg)
936
1046
  true
937
- end
938
1047
  rescue
939
1048
  failed_to_log("#{msg} '#{$!}'")
940
1049
  end
941
1050
 
942
- def clear_checkbox(browser, how, what, value = nil, desc = '')
943
- clear(browser, :checkbox, how, what, value, desc)
944
- end
1051
+ # @!endgroup Core
945
1052
 
946
- def clear_checkbox_by_name(browser, strg, value = nil, desc = '')
947
- clear(browser, :checkbox, :name, strg, value, desc)
948
- end
1053
+ # @!group Clear
949
1054
 
950
- def clear_checkbox_by_id(browser, strg, value = nil, desc = '')
951
- clear(browser, :checkbox, :id, strg, value, desc)
1055
+ # Clear (uncheck) checkbox identified by the attribute specified in *how* with value *what*.
1056
+ # It's *:value* attribute can also be used when needed by specifying *value*.
1057
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
1058
+ # @param [Symbol] how The element attribute used to identify the specific checkbox.
1059
+ # Valid values depend on the kind of element.
1060
+ # Common values: :text, :id, :title, :name, :class.
1061
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
1062
+ # @param [String, Regexp] value A string or a regular expression to be found in the *:value* attribute of the element.
1063
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
1064
+ # @return (see #click)
1065
+ def clear_checkbox(browser, how, what, value = nil, desc = '')
1066
+ clear(browser, :checkbox, how, what, value, desc)
952
1067
  end
953
1068
 
1069
+ # Clear (uncheck) checkbox identified by its *:name* attribute with value *what*.
1070
+ # It's *:value* attribute can also be used when needed by specifying *value*.
1071
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
1072
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
1073
+ # @param [String, Regexp] value A string or a regular expression to be found in the *:value* attribute of the element.
1074
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
1075
+ # @return (see #click)
1076
+ def clear_checkbox_by_name(browser, what, value = nil, desc = '')
1077
+ clear(browser, :checkbox, :name, what, value, desc)
1078
+ end
1079
+
1080
+ # Clear (uncheck) checkbox identified by its *:id* attribute with value *what*.
1081
+ # It's *:value* attribute can also be used when needed by specifying *value*.
1082
+ # @param (see #set_file_field_by_name)
1083
+ # @return (see #click)
1084
+ def clear_checkbox_by_name(browser, what, value = nil, desc = '')
1085
+ clear(browser, :checkbox, :id, what, value, desc)
1086
+ end
1087
+
1088
+ # Clear (unset) radio button identified by the attribute specified in *how* with value *what*.
1089
+ # It's *:value* attribute can also be used when needed by specifying *value*.
1090
+ # This clears the specified radio without setting any other radio buttons on.
1091
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
1092
+ # @param [Symbol] how The element attribute used to identify the specific checkbox.
1093
+ # Valid values depend on the kind of element.
1094
+ # Common values: :text, :id, :title, :name, :class.
1095
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
1096
+ # @param [String, Regexp] value A string or a regular expression to be found in the *:value* attribute of the element.
1097
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
1098
+ # @return (see #click)
954
1099
  def clear_radio(browser, how, what, value = nil, desc = '')
955
1100
  clear(browser, :radio, how, what, value, desc)
956
1101
  end
957
1102
 
958
- # Set skip_value_check = true when string is altered by application and/or
959
- # this method will be followed by validate_text
960
- def clear_textfield(browser, how, which, skip_value_check = false)
961
- if browser.text_field(how, which).exists?
962
- tf = browser.text_field(how, which)
963
- if validate(browser, @myName, __LINE__)
964
- tf.clear
965
- if validate(browser, @myName, __LINE__)
966
- if tf.value == ''
967
- passed_to_log("Textfield #{how}='#{which}' cleared.")
968
- true
969
- elsif skip_value_check
970
- passed_to_log("Textfield #{how}='#{which}' cleared. (skip value check)")
971
- true
972
- else
973
- failed_to_log("Textfield #{how}='#{which}' not cleared: Found:'#{tf.value}'. (#{__LINE__})")
974
- end
975
- end
976
- end
977
- else
978
- failed_to_log("Textfield id='#{id}' to clear. (#{__LINE__})")
979
- end
980
- rescue
981
- failed_to_log("Textfield id='#{id}' could not be cleared: '#{$!}'. (#{__LINE__})")
982
- end
983
-
984
- def set_file_field(browser, how, what, filespec, desc = '')
985
- msg = "Set file field #{how}=>#{what} to '#{filespec}."
986
- msg << " #{desc}" if desc.length > 0
987
- ff = browser.file_field(how, what)
988
- if ff
989
- ff.set filespec
990
- sleep_for(8)
991
- if validate(browser, @myName, __LINE__)
992
- passed_to_log(msg)
993
- true
994
- end
995
- else
996
- failed_to_log("#{msg} File field not found.")
997
- end
998
- rescue
999
- failed_to_log("Unable to #{msg} '#{$!}'")
1000
- end
1001
-
1002
- def set_file_field_by_name(browser, strg, path, desc = '')
1003
- set_file_field(browser, :name, strg, path, desc)
1004
- end
1005
-
1006
- def set_file_field_by_id(browser, strg, path, desc = '')
1007
- set_file_field(browser, :id, strg, path, desc)
1008
- end
1009
-
1010
- =begin rdoc
1011
- :category: A_rdoc_test
1012
- Enter a string into a text field element identified by an attribute type and a value.
1013
- After the entry the value in the text field is validated against the input value unless the *skip_value_check*
1014
- parameter is set to true
1015
-
1016
- _Parameters_::
1017
-
1018
- *browser* - a reference to the browser window to be tested
1019
-
1020
- *how* - the element attribute used to identify the specific element. Valid values depend on the kind of element.
1021
- Common values: :text, :id, :title, :name, :class, :href (:link only)
1022
-
1023
- *what* - a string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
1103
+ # @!endgroup Clear
1024
1104
 
1025
- *value* - a string to be entered in the text field
1026
-
1027
- *desc* - a string containing a message or description intended to appear in the log and/or report output
1028
-
1029
- *skip_value_check* (Optional, default is false). Set to true to prevent the built-in verification
1030
- that the text field actually contains the value entered. Useful when application reformats
1031
- or otherwise edits the input string.
1032
-
1033
- _Example_
1034
-
1035
- set_text_field(browser, :name, /thisTextfield/, 'The text to enter')
1036
-
1037
- =end
1105
+ # @!group Core
1038
1106
 
1107
+ # Set text field as identified by the attribute specified in *how* with value in *what* to the string specified in *value*.
1108
+ # This method differs from set() in that it validates that the text field has been set to the specified value.
1109
+ # The value verification can be turned off by setting *skip_value_check* to true.
1110
+ # This is useful when the text_field performs formatting on the entered string. See set_text_field_and_validate()
1111
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
1112
+ # @param [Symbol] how The element attribute used to identify the specific checkbox.
1113
+ # Valid values depend on the kind of element.
1114
+ # Common values: :text, :id, :title, :name, :class.
1115
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
1116
+ # @param [String] value A string to enter into the text field.
1117
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
1118
+ # @param [Boolean] skip_value_check Forces verification of value in text field to pass.
1119
+ # @return (see #click)
1039
1120
  def set_text_field(browser, how, what, value, desc = '', skip_value_check = false)
1040
1121
  #TODO: fix this to handle Safari password field
1041
- msg = "Set textfield #{how}='#{what}' to '#{value}'"
1042
- msg << " #{desc}" if desc.length > 0
1122
+ msg = build_message("Set textfield #{how}='#{what}' to '#{value}'", desc)
1043
1123
  msg << " (Skip value check)" if skip_value_check
1044
1124
  if browser.text_field(how, what).exists?
1045
1125
  tf = browser.text_field(how, what)
1046
- debug_to_log("#{tf.inspect}")
1047
- if validate(browser, @myName, __LINE__)
1126
+ #debug_to_log("#{tf.inspect}")
1048
1127
  tf.set(value)
1049
- if validate(browser, @myName, __LINE__)
1050
1128
  if tf.value == value
1051
1129
  passed_to_log(msg)
1052
1130
  true
@@ -1056,10 +1134,8 @@ _Example_
1056
1134
  else
1057
1135
  failed_to_log("#{msg}: Found:'#{tf.value}'.")
1058
1136
  end
1059
- end
1060
- end
1061
1137
  else
1062
- failed_to_log("Textfield #{how}='#{what}' not found to set to '#{value}''")
1138
+ failed_to_log("#{msg}: Textfield #{how}='#{what}' not found")
1063
1139
  end
1064
1140
  rescue
1065
1141
  failed_to_log("Unable to '#{msg}': '#{$!}'")
@@ -1067,99 +1143,58 @@ _Example_
1067
1143
 
1068
1144
  alias set_textfield set_text_field
1069
1145
 
1070
- def set_textfield_by_name(browser, name, value, desc = '', skip_value_check = false)
1071
- if browser.text_field(:name, name).exists?
1072
- tf = browser.text_field(:name, name)
1073
- # Workaround because browser.text_field doesn't work for password fields in Safari
1074
- elsif @browserAbbrev.eql?("S")
1075
- tf = browser.password(:name, name)
1076
- end
1077
- if tf.exists?
1078
- if validate(browser, @myName, __LINE__)
1079
- tf.set(value)
1080
- if validate(browser, @myName, __LINE__)
1081
- if tf.value == value
1082
- passed_to_log("Set textfield name='#{name}' to '#{value}' #{desc}")
1146
+ # Clear text field as identified by the attribute specified in *how* with value in *what* to the string specified in *value*.
1147
+ # This method differs from set() in that 1( it uses the Watir #clear method, 2( it validates that the text field has been
1148
+ # set to the specified value.
1149
+ # The value verification can be turned off by setting *skip_value_check* to true.
1150
+ # This is useful when the text_field performs formatting on the entered string. See set_text_field_and_validate()
1151
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
1152
+ # @param [Symbol] how The element attribute used to identify the specific checkbox.
1153
+ # Valid values depend on the kind of element.
1154
+ # Common values: :text, :id, :title, :name, :class.
1155
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
1156
+ # @param [Boolean] skip_value_check Forces verification of value in text field to pass.
1157
+ # @return (see #click)
1158
+ def clear_textfield(browser, how, what, skip_value_check = false)
1159
+ if browser.text_field(how, what).exists?
1160
+ tf = browser.text_field(how, what)
1161
+ tf.clear
1162
+ if tf.value == ''
1163
+ passed_to_log("Textfield #{how}='#{what}' cleared.")
1083
1164
  true
1084
1165
  elsif skip_value_check
1085
- passed_to_log("Set textfield name='#{name}' to '#{value}' #{desc} (skip value check)")
1166
+ passed_to_log("Textfield #{how}='#{what}' cleared. (skip value check)")
1086
1167
  true
1087
1168
  else
1088
- failed_to_log("Set textfield name='#{name}' to '#{value}': Found:'#{tf.value}'. #{desc} (#{__LINE__})")
1169
+ failed_to_log("Textfield #{how}='#{what}' not cleared: Found:'#{tf.value}'. (#{__LINE__})")
1089
1170
  end
1090
- end
1091
- end
1092
1171
  else
1093
- failed_to_log("Textfield name='#{name}' not found to set to '#{value}'. #{desc} (#{__LINE__})")
1172
+ failed_to_log("Textfield id='#{id}' to clear. (#{__LINE__})")
1094
1173
  end
1095
1174
  rescue
1096
- failed_to_log("Textfield name='#{name}' could not be set to '#{value}': '#{$!}'. #{desc} (#{__LINE__})")
1097
- end
1098
-
1099
- =begin rdoc
1100
- :category: A_rdoc_test
1101
- Enter a string into a text field element identified by the value in its id attribute.
1102
-
1103
- _Parameters_::
1104
-
1105
- *browser* - a reference to the browser window to be tested
1106
-
1107
- *id* - a string or a regular expression to be found in the id attribute that uniquely identifies the element.
1108
-
1109
- *value* - a string to be entered in the text field
1110
-
1111
- *desc* - a string containing a message or description intended to appear in the log and/or report output
1112
-
1113
- *skip_value_check* (Optional, default is false). Set to true to prevent the built-in verification
1114
- that the text field actually contains the value entered. Useful when application reformats
1115
- or otherwise edits the input string.
1116
-
1117
- _Example_
1118
-
1119
- set_text_field_by_id(browser, /thisTextfield/, 'The text to enter')
1120
-
1121
- =end
1122
-
1123
- def set_textfield_by_id(browser, id, value, desc = '', skip_value_check = false)
1124
- set_text_field(browser, :id, id, value, desc, skip_value_check)
1125
- end
1126
-
1127
- def set_textfield_by_title(browser, title, value, desc = '', skip_value_check = false)
1128
- set_text_field(browser, :title, title, value, desc, skip_value_check)
1129
- end
1130
-
1131
- def set_textfield_by_class(browser, strg, value, desc = '', skip_value_check = false)
1132
- set_text_field(browser, :class, strg, value, desc, skip_value_check)
1175
+ failed_to_log("Textfield id='#{id}' could not be cleared: '#{$!}'. (#{__LINE__})")
1133
1176
  end
1134
1177
 
1135
- =begin rdoc
1136
- :category: A_rdoc_test
1137
- Enter a string into a text field element identified by an attribute type and a value.
1138
- After the entry the value in the text field is validated against the *valid_value*. Use when the application reformats
1139
- or performs edits on the input value.
1140
-
1141
- _Parameters_::
1142
-
1143
- *browser* - a reference to the browser window to be tested
1144
-
1145
- *how* - the element attribute used to identify the specific element. Valid values depend on the kind of element.
1146
- Common values: :text, :id, :title, :name, :class, :href (:link only)
1147
-
1148
- *what* - a string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
1149
-
1150
- *value* - a string to be entered in the text field
1151
-
1152
- *desc* - a string containing a message or description intended to appear in the log and/or report output
1153
-
1154
- *valid_value* (Optional, default is nil). Set to the expected value
1155
-
1156
- _Example_
1157
-
1158
- set_text_field_and_validate(browser, :id, /AmountTendered/, '7500', 'Dollar formatting', '$7,500.00')
1159
-
1160
- =end
1161
-
1162
- def set_text_field_and_validate(browser, how, what, value, desc = '', valid_value = nil)
1178
+ #Enter a string into a text field element identified by an attribute type and a value.
1179
+ #After the entry the value in the text field is validated against the *valid_value*. Use when the application reformats
1180
+ #or performs edits on the input value.
1181
+
1182
+ # Set text field as identified by the attribute specified in *how* with value in *what* to the string specified in *value*.
1183
+ # and verify that the text field is set to the string in *valid_value*.
1184
+ #
1185
+ # @example
1186
+ # set_text_field_and_validate(browser, :id, 'text field id', '99999', 'Dollar format', '$99,999.00')
1187
+ #
1188
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
1189
+ # @param [Symbol] how The element attribute used to identify the specific checkbox.
1190
+ # Valid values depend on the kind of element.
1191
+ # Common values: :text, :id, :title, :name, :class.
1192
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
1193
+ # @param [String] value A string to enter into the text field.
1194
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output. Required in this method.
1195
+ # @param [String] valid_value The expected value of the text field, e.g., following reformatting.
1196
+ # @return (see #click)
1197
+ def set_text_field_and_validate(browser, how, what, value, desc, valid_value = nil)
1163
1198
  #NOTE: use when value and valid_value differ as with dollar reformatting
1164
1199
  if set_text_field(browser, how, what, value, desc, true)
1165
1200
  expected = valid_value ? valid_value : value
@@ -1169,34 +1204,98 @@ _Example_
1169
1204
  failed_to_log("Unable to '#{msg}': '#{$!}'")
1170
1205
  end
1171
1206
 
1172
- =begin rdoc
1173
- :category: A_rdoc_test
1174
- Allows a generic way to fire browser or javascript events on page elements.
1175
- Raises UnknownObjectException if the object is not found or ObjectDisabledException if the object is currently disabled.
1176
- _Parameters_::
1177
-
1178
- *browser* - a reference to the browser window to be tested
1179
-
1180
- *element* - the kind of element to click. Must be one of the elements recognized by Watir.
1181
- Some common values are :link, :button, :image, :div, :span.
1182
-
1183
- *how* - the element attribute used to identify the specific element. Valid values depend on the kind of element.
1184
- Common values: :text, :id, :title, :name, :class, :href (:link only)
1185
-
1186
- *what* - a string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
1187
-
1188
- *event* - a string indicating the event to be triggered, e.g., 'onMouseOver', 'onClick', and etc.
1189
-
1190
- *desc* - a string containing a message or description intended to appear in the log and/or report output
1191
-
1192
- _Example_
1193
-
1194
- # html for a link element:
1195
- # <a href="http://pragmaticprogrammer.com/titles/ruby/" id="one" name="book">Pickaxe</a>
1196
- fire_event(browser, :link, :text, 'Pickaxe', 'onMouseOver')
1197
-
1198
- =end
1199
-
1207
+ #def set_password_by_name(browser, name, value, desc = '', skip_value_check = false)
1208
+ # set_text_field(browser, how, what, value, desc, skip_value_check)
1209
+ # if browser.text_field(:name, name).exists?
1210
+ # tf = browser.text_field(:name, name)
1211
+ # # Workaround because browser.text_field doesn't work for password fields in Safari
1212
+ # elsif @browserAbbrev.eql?("S")
1213
+ # tf = browser.password(:name, name)
1214
+ # end
1215
+ # if tf.exists?
1216
+ # tf.set(value)
1217
+ # if tf.value == value
1218
+ # passed_to_log("Set textfield name='#{name}' to '#{value}' #{desc}")
1219
+ # true
1220
+ # elsif skip_value_check
1221
+ # passed_to_log("Set textfield name='#{name}' to '#{value}' #{desc} (skip value check)")
1222
+ # true
1223
+ # else
1224
+ # failed_to_log("Set textfield name='#{name}' to '#{value}': Found:'#{tf.value}'. #{desc} (#{__LINE__})")
1225
+ # end
1226
+ # else
1227
+ # failed_to_log("Textfield name='#{name}' not found to set to '#{value}'. #{desc} (#{__LINE__})")
1228
+ # end
1229
+ #rescue
1230
+ # failed_to_log("Textfield name='#{name}' could not be set to '#{value}': '#{$!}'. #{desc} (#{__LINE__})")
1231
+ #end
1232
+
1233
+ # @!endgroup Core
1234
+
1235
+ # @!group Set
1236
+
1237
+ # Set text field as identified by its *:name* attribute with value in *what* to the string specified in *value*.
1238
+ # This method validates that the text field has been set to the specified value.
1239
+ # The value verification can be turned off by setting *skip_value_check* to true.
1240
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
1241
+ # @param [String, Regexp] what A string or a regular expression to be found in the specified attribute that uniquely identifies the element.
1242
+ # @param [String] value A string to enter into the text field.
1243
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output.
1244
+ # Required if *skip_value_check* is set to true.
1245
+ # @param [Boolean] skip_value_check Forces verification of value in text field to pass.
1246
+ # @return (see #click)
1247
+ def set_textfield_by_name(browser, what, value, desc = '', skip_value_check = false)
1248
+ set_text_field(browser, :name, what, value, desc, skip_value_check)
1249
+ end
1250
+
1251
+ # Set text field as identified by its *:id* attribute with value in *what* to the string specified in *value*.
1252
+ # This method validates that the text field has been set to the specified value.
1253
+ # The value verification can be turned off by setting *skip_value_check* to true.
1254
+ # @param (see #set_textfield_by_name)
1255
+ # @return (see #click)
1256
+ def set_textfield_by_id(browser, what, value, desc = '', skip_value_check = false)
1257
+ set_text_field(browser, :id, what, value, desc, skip_value_check)
1258
+ end
1259
+
1260
+ # Set text field as identified by its *:class* attribute with value in *what* to the string specified in *value*.
1261
+ # This method validates that the text field has been set to the specified value.
1262
+ # The value verification can be turned off by setting *skip_value_check* to true.
1263
+ # @param (see #set_textfield_by_name)
1264
+ # @return (see #click)
1265
+ def set_textfield_by_title(browser, what, value, desc = '', skip_value_check = false)
1266
+ set_text_field(browser, :title, what, value, desc, skip_value_check)
1267
+ end
1268
+
1269
+ # Set text field as identified by its *:class* attribute with value in *what* to the string specified in *value*.
1270
+ # This method validates that the text field has been set to the specified value.
1271
+ # The value verification can be turned off by setting *skip_value_check* to true.
1272
+ # @param (see #set_textfield_by_name)
1273
+ def set_textfield_by_class(browser, what, value, desc = '', skip_value_check = false)
1274
+ set_text_field(browser, :class, what, value, desc, skip_value_check)
1275
+ end
1276
+
1277
+ # @!endgroup Set
1278
+ # @!group Core
1279
+
1280
+ # Fire an event on a specific DOM element identified by one of its attributes and that attribute's value.
1281
+ #
1282
+ # @example
1283
+ # # html for a link element:
1284
+ # # <a href="http://pragmaticprogrammer.com/titles/ruby/" id="one" name="book">Pickaxe</a>
1285
+ #
1286
+ # fire_event(browser, :link, :text, 'Pickaxe', 'onMouseOver')
1287
+ #
1288
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
1289
+ # @param [Symbol] element The kind of element to click. Must be one of the elements recognized by Watir.
1290
+ # Some common values are :link, :button, :image, :div, :span.
1291
+ # @param [Symbol] how The element attribute used to identify the specific element.
1292
+ # Valid values depend on the kind of element.
1293
+ # Common values: :text, :id, :title, :name, :class, :href (:link only)
1294
+ # @param [String, Regexp] what A string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
1295
+ # @param [String] event A string identifying the event to be fired.
1296
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
1297
+ # @return (see #click)
1298
+ #
1200
1299
  def fire_event(browser, element, how, what, event, desc = '')
1201
1300
  msg = "#{element.to_s.titlecase}: #{how}=>'#{what}' event:'#{event}'"
1202
1301
  msg1 = "#{element.to_s.titlecase}(#{how}, '#{what}')"
@@ -1220,35 +1319,68 @@ _Example_
1220
1319
  raise e
1221
1320
  end
1222
1321
  end
1223
- if validate(browser, @myName, __LINE__)
1224
1322
  passed_to_log("Fire event: #{msg}. #{desc}")
1225
1323
  true
1226
- end
1227
1324
  rescue
1228
1325
  failed_to_log("Unable to fire event: #{msg}. '#{$!}' #{desc}")
1229
1326
  end
1230
1327
 
1231
- def fire_event_on_link_by_text(browser, strg, event = 'onclick', desc = '')
1232
- fire_event(browser, :link, :text, strg, event, desc)
1328
+ # @!endgroup Core
1329
+
1330
+ # @!group Fire Event
1331
+
1332
+ # Fire an event on a link element identified by the value in its text (innerHTML)
1333
+ #
1334
+ # @example
1335
+ # # html for a link element:
1336
+ # # <a href="http://pragmaticprogrammer.com/titles/ruby/" id="one" name="book">Pickaxe</a>
1337
+ #
1338
+ # fire_event_on_link_by_text(browser, 'Pickaxe', 'onMouseOver')
1339
+ #
1340
+ # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
1341
+ # @param [String, Regexp] what A string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
1342
+ # @param [String] event A string identifying the event to be fired.
1343
+ # @param [String] desc Contains a message or description intended to appear in the log and/or report output
1344
+ # @return (see #click)
1345
+ #
1346
+ def fire_event_on_link_by_text(browser, what, event, desc = '')
1347
+ fire_event(browser, :link, :text, what, event, desc)
1233
1348
  end
1234
1349
 
1235
1350
  alias fire_event_text fire_event_on_link_by_text
1236
1351
  alias fire_event_by_text fire_event_on_link_by_text
1237
1352
 
1238
- def fire_event_on_link_by_id(browser, strg, event = 'onclick', desc = '')
1239
- fire_event(browser, :link, :id, strg, event, desc)
1353
+ # Fire an event on a link element identified by the value in its *:id* attribute.
1354
+ #
1355
+ # @example
1356
+ # # html for a link element:
1357
+ # # <a href="http://pragmaticprogrammer.com/titles/ruby/" id="one" name="book">Pickaxe</a>
1358
+ #
1359
+ # fire_event_on_link_by_id(browser, 'one', 'onMouseOver')
1360
+ #
1361
+ # @param (see #fire_event_on_link_by_text)
1362
+ # @return (see #click)
1363
+ #
1364
+ def fire_event_on_link_by_id(browser, what, event, desc = '')
1365
+ fire_event(browser, :link, :id, what, event, desc)
1240
1366
  end
1241
1367
 
1242
1368
  alias fire_event_id fire_event_on_link_by_id
1243
1369
  alias fire_event_by_id fire_event_on_link_by_id
1244
1370
 
1245
- def fire_event_on_image_by_src(browser, strg, event = 'onclick', desc = '')
1246
- fire_event(browser, :img, :src, strg, event, desc)
1371
+ # Fire an event on a image element identified by the value in its *:src* attribute.
1372
+ # Take care to escape characters in the source url that are reserved by Regexp.
1373
+ # @param (see #fire_event_on_link_by_text)
1374
+ # @return (see #click)
1375
+ #
1376
+ def fire_event_on_image_by_src(browser, what, event, desc = '')
1377
+ fire_event(browser, :img, :src, what, event, desc)
1247
1378
  end
1248
1379
 
1249
1380
  alias fire_event_src fire_event_on_image_by_src
1250
1381
  alias fire_event_image_by_src fire_event_on_image_by_src
1251
1382
 
1383
+ # @!endgroup Fire Event
1252
1384
 
1253
1385
  end
1254
1386
  end