Class: Watir::Element

Inherits:
Object
  • Object
show all
Extended by:
AttributeHelper
Includes:
Container, EventuallyPresent, Exception
Defined in:
lib/watir-webdriver/elements/element.rb,
lib/watir-webdriver/extensions/select_text.rb

Overview

Base class for HTML elements.

Direct Known Subclasses

HTMLElement

Constant Summary

Constant Summary

Constants included from AttributeHelper

AttributeHelper::IGNORED_ATTRIBUTES

Constants included from Atoms

Atoms::ATOMS

Instance Method Summary (collapse)

Methods included from AttributeHelper

attribute_list, attributes, typed_attributes

Methods included from EventuallyPresent

#wait_until_present, #wait_while_present, #when_present

Methods included from Container

#a, #abbr, #abbrs, #address, #addresses, #area, #areas, #article, #articles, #as, #aside, #asides, #audio, #audios, #b, #base, #bases, #bdi, #bdis, #bdo, #bdos, #blockquote, #blockquotes, #body, #bodys, #br, #brs, #bs, #button, #buttons, #canvas, #canvases, #caption, #captions, #checkbox, #checkboxes, #cite, #cites, #code, #codes, #col, #colgroup, #colgroups, #cols, #command, #commands, #data, #datalist, #datalists, #dd, #dds, #del, #dels, #details, #detailses, #dfn, #dfns, #dialog, #dialogs, #div, #divs, #dl, #dls, #dt, #dts, #element, #elements, #em, #embed, #embeds, #ems, #extract_selector, #field_set, #field_sets, #fieldset, #fieldsets, #figcaption, #figcaptions, #figure, #figures, #file_field, #file_fields, #font, #fonts, #footer, #footers, #form, #forms, #frame, #frames, #frameset, #framesets, #h1, #h1s, #h2, #h2s, #h3, #h3s, #h4, #h4s, #h5, #h5s, #h6, #h6s, #head, #header, #headers, #heads, #hgroup, #hgroups, #hidden, #hiddens, #hr, #hrs, #htmls, #i, #iframe, #iframes, #image, #images, #img, #imgs, #input, #inputs, #ins, #inses, #is, #kbd, #kbds, #keygen, #keygens, #label, #labels, #legend, #legends, #li, #link, #links, #lis, #map, #maps, #mark, #marks, #menu, #menus, #meta, #metas, #meter, #meters, #nav, #navs, #noscript, #noscripts, #object, #objects, #ol, #ols, #optgroup, #optgroups, #option, #options, #output, #outputs, #p, #param, #params, #pre, #pres, #progress, #progresses, #ps, #q, #qs, #radio, #radios, #rp, #rps, #rt, #rts, #rubies, #ruby, #s, #samp, #samps, #script, #scripts, #section, #sections, #select, #select_list, #select_lists, #selects, #small, #smalls, #source, #sources, #span, #spans, #ss, #strong, #strongs, #styles, #sub, #subs, #summaries, #summary, #sup, #sups, #table, #tables, #tbody, #tbodys, #td, #tds, #text_field, #text_fields, #textarea, #textareas, #tfoot, #tfoots, #th, #thead, #theads, #ths, #time, #times, #title, #titles, #tr, #track, #tracks, #trs, #u, #ul, #uls, #us, #var, #vars, #video, #videos, #wbr, #wbrs

Methods included from Atoms

load

Methods included from XpathSupport

escape

Constructor Details

- (Element) initialize(parent, selector)

A new instance of Element



26
27
28
29
30
31
32
33
34
 
# File 'lib/watir-webdriver/elements/element.rb', line 26

def initialize(parent, selector)
  @parent   = parent
  @selector = selector
  @element  = nil

  unless @selector.kind_of? Hash
    raise ArgumentError, "invalid argument: #{selector.inspect}"
  end
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

- (Object) method_missing(meth, *args, &blk) (private) 



423
424
425
426
427
428
429
430
 
# File 'lib/watir-webdriver/elements/element.rb', line 423

def method_missing(meth, *args, &blk)
  method = meth.to_s
  if method =~ /^data_(.+)$/
    attribute_value(method.gsub(/_/, '-'), *args)
  else
    super
  end
end

Instance Method Details

- (Object) ==(other) Also known as: eql? 



52
53
54
55
56
57
 
# File 'lib/watir-webdriver/elements/element.rb', line 52

def ==(other)
  return false unless other.kind_of? self.class

  assert_exists
  @element == other.wd
end

- (Object) attribute_value(attribute_name) 



215
216
217
218
 
# File 'lib/watir-webdriver/elements/element.rb', line 215

def attribute_value(attribute_name)
  assert_exists
  @element.attribute attribute_name
end

- (Object) browser 



350
351
352
 
# File 'lib/watir-webdriver/elements/element.rb', line 350

def browser
  @parent.browser
end

- (Object) click(*modifiers)

Clicks the element, optionally while pressing the given mofifier keys. Note that support for holding a modifier key is currently experimental, and may not work at all.

Examples:

Click an element

element.click

Click an element with shift key pressed

element.click(:shift)

Click an element with several modifier keys pressed

element.click(:shift, :control)

Parameters:

  • Modifier (:shift, :alt, :control, :command, :meta) —

    key(s) to press while clicking.



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/watir-webdriver/elements/element.rb', line 94

def click(*modifiers)
  assert_exists
  assert_enabled

  if modifiers.any?
    assert_has_input_devices_for "click(#{modifiers.join ', '})"

    action = driver.action
    modifiers.each { |mod| action.key_down mod }
    action.click @element
    modifiers.each { |mod| action.key_up mod }

    action.perform
  else
    @element.click
  end

  run_checkers
end

- (Object) double_click 



121
122
123
124
125
126
127
 
# File 'lib/watir-webdriver/elements/element.rb', line 121

def double_click
  assert_exists
  assert_has_input_devices_for :double_click

  driver.action.double_click(@element).perform
  run_checkers
end

- (Object) drag_and_drop_by(right_by, down_by)

Drag and drop this element by the given offsets.

Example:

a = browser.div(:id => "draggable")

a.drag_and_drop_by 100, -200


187
188
189
190
191
192
193
194
 
# File 'lib/watir-webdriver/elements/element.rb', line 187

def drag_and_drop_by(right_by, down_by)
  assert_exists
  assert_has_input_devices_for :drag_and_drop_by

  driver.action.
         drag_and_drop_by(@element, right_by, down_by).
         perform
end

- (Object) drag_and_drop_on(other)

Drag and drop this element on to another element instance.

Example:

a = browser.div(:id => "draggable")
b = browser.div(:id => "droppable")

a.drag_and_drop_on b


167
168
169
170
171
172
173
174
175
 
# File 'lib/watir-webdriver/elements/element.rb', line 167

def drag_and_drop_on(other)
  assert_is_element other
  assert_exists
  assert_has_input_devices_for :drag_and_drop_on

  driver.action.
         drag_and_drop(@element, other.wd).
         perform
end

- (Object) driver

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



267
268
269
 
# File 'lib/watir-webdriver/elements/element.rb', line 267

def driver
  @parent.driver
end

- (Boolean) exists? Also known as: exist?

Returns:

  • (Boolean) 


36
37
38
39
40
41
 
# File 'lib/watir-webdriver/elements/element.rb', line 36

def exists?
  assert_exists
  true
rescue UnknownObjectException, UnknownFrameException
  false
end

- (Object) fire_event(event_name) 



246
247
248
249
250
251
 
# File 'lib/watir-webdriver/elements/element.rb', line 246

def fire_event(event_name)
  assert_exists
  event_name = event_name.to_s.sub(/^on/, '').downcase

  execute_atom :fireEvent, @element, event_name
end

- (Object) flash 



196
197
198
199
200
201
202
203
 
# File 'lib/watir-webdriver/elements/element.rb', line 196

def flash
  original_color = style("backgroundColor")

  10.times do |n|
    color = (n % 2 == 0) ? "red" : original_color
    driver.execute_script("arguments[0].style.backgroundColor = '#{color}'", @element)
  end
end

- (Object) focus

Note: Firefox queues focus events until the window actually has focus.

See code.google.com/p/selenium/issues/detail?id=157



236
237
238
239
 
# File 'lib/watir-webdriver/elements/element.rb', line 236

def focus
  assert_exists
  driver.execute_script "return arguments[0].focus()", @element
end

- (Boolean) focused?

Returns:

  • (Boolean) 


241
242
243
244
 
# File 'lib/watir-webdriver/elements/element.rb', line 241

def focused?
  assert_exists
  @element == driver.switch_to.active_element
end

- (Object) hash 



60
61
62
 
# File 'lib/watir-webdriver/elements/element.rb', line 60

def hash
  @element ? @element.hash : super
end

- (Object) hover

Moves the mouse to the middle of this element.

Note that browser/platform support may vary.



149
150
151
152
153
154
 
# File 'lib/watir-webdriver/elements/element.rb', line 149

def hover
  assert_exists
  assert_has_input_devices_for :hover

  driver.action.move_to(@element).perform
end

- (Object) html 



220
221
222
223
 
# File 'lib/watir-webdriver/elements/element.rb', line 220

def html
  assert_exists
  execute_atom(:getOuterHtml, @element).strip
end

- (Object) id

need to add :id manually since it's not specified in the HTML spec.

TODO: use IDL from DOM core?

See Also:



24
 
# File 'lib/watir-webdriver/elements/element.rb', line 24

attributes :string => [:id]

- (Object) inspect 



44
45
46
47
48
49
50
 
# File 'lib/watir-webdriver/elements/element.rb', line 44

def inspect
  if @selector.has_key?(:element)
    '#<%s:0x%x located=%s selector=%s>' % [self.class, hash*2, !!@element, '{:element=>(webdriver element)}']
  else
    '#<%s:0x%x located=%s selector=%s>' % [self.class, hash*2, !!@element, selector_string]
  end
end

- (Object) parent 



253
254
255
256
257
258
259
260
261
 
# File 'lib/watir-webdriver/elements/element.rb', line 253

def parent
  assert_exists

  e = execute_atom :getParentElement, @element

  if e.kind_of?(Selenium::WebDriver::Element)
    Watir.element_class_for(e.tag_name.downcase).new(@parent, :element => e)
  end
end

- (Boolean) present?

Returns true if the element exists and is visible on the page

Returns:

  • (Boolean)

See Also:



295
296
297
298
299
300
301
 
# File 'lib/watir-webdriver/elements/element.rb', line 295

def present?
  exists? && visible?
rescue Selenium::WebDriver::Error::ObsoleteElementError, UnknownObjectException
  # if the element disappears between the exists? and visible? calls,
  # consider it not present.
  false
end

- (Object) right_click

Right clicks the element.

Note that browser support may vary.



135
136
137
138
139
140
141
 
# File 'lib/watir-webdriver/elements/element.rb', line 135

def right_click
  assert_exists
  assert_has_input_devices_for :right_click

  driver.action.context_click(@element).perform
  run_checkers
end

- (Object) run_checkers 



312
313
314
 
# File 'lib/watir-webdriver/elements/element.rb', line 312

def run_checkers
  @parent.run_checkers
end

- (Object) select_text(str) 



5
6
7
8
 
# File 'lib/watir-webdriver/extensions/select_text.rb', line 5

def select_text(str)
  assert_exists
  execute_atom :selectText, @element, str
end

- (Object) send_keys(*args) 



225
226
227
228
 
# File 'lib/watir-webdriver/elements/element.rb', line 225

def send_keys(*args)
  assert_exists
  @element.send_keys(*args)
end

- (Object) style(property = nil) 



303
304
305
306
307
308
309
310
 
# File 'lib/watir-webdriver/elements/element.rb', line 303

def style(property = nil)
  if property
    assert_exists
    @element.style property
  else
    attribute_value("style").to_s.strip
  end
end

- (Object) tag_name 



69
70
71
72
 
# File 'lib/watir-webdriver/elements/element.rb', line 69

def tag_name
  assert_exists
  @element.tag_name.downcase
end

- (Object) text 



64
65
66
67
 
# File 'lib/watir-webdriver/elements/element.rb', line 64

def text
  assert_exists
  @element.text
end

- (Object) to_subtype

Cast this Element instance to a more specific subtype.

Example:

browser.element(:xpath => "//input[@type='submit']").to_subtype #=> #<Watir::Button>


324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
 
# File 'lib/watir-webdriver/elements/element.rb', line 324

def to_subtype
  elem = wd()
  tag_name = elem.tag_name.downcase

  klass = nil

  if tag_name == "input"
    klass = case elem.attribute(:type)
      when *Button::VALID_TYPES
        Button
      when 'checkbox'
        CheckBox
      when 'radio'
        Radio
      when 'file'
        FileField
      else
        TextField
      end
  else
    klass = Watir.element_class_for(tag_name)
  end

  klass.new(@parent, :element => elem)
end

- (Object) value 



205
206
207
208
209
210
211
212
213
 
# File 'lib/watir-webdriver/elements/element.rb', line 205

def value
  assert_exists

  begin
    @element.attribute('value') || ''
  rescue Selenium::WebDriver::Error::InvalidElementStateError
    ""
  end
end

- (Boolean) visible?

Returns true if this element is visible on the page

Returns:

  • (Boolean) 


284
285
286
287
 
# File 'lib/watir-webdriver/elements/element.rb', line 284

def visible?
  assert_exists
  @element.displayed?
end

- (Object) wd

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



275
276
277
278
 
# File 'lib/watir-webdriver/elements/element.rb', line 275

def wd
  assert_exists
  @element
end