Class: Watir::Browser

Inherits:
Object
  • Object
show all
Includes:
Container, Exception, HasWindow, Navigation, Scrolling, Waitable
Defined in:
lib/watir/browser.rb,
lib/watir/extensions/nokogiri.rb

Overview

The main class through which you control the browser.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Scrolling

#scroll

Methods included from Navigation

#back, #forward, #goto, #refresh

Methods included from Waitable

#wait_until, #wait_until_present, #wait_while, #wait_while_present

Methods included from HasWindow

#original_window, #window, #windows

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, #circle, #circles, #cite, #cites, #code, #codes, #col, #colgroup, #colgroups, #cols, #data, #datalist, #datalists, #datas, #date_field, #date_fields, #date_time_field, #date_time_fields, #dd, #dds, #defs, #defss, #del, #dels, #desc, #descs, #details, #detailses, #dfn, #dfns, #dialog, #dialogs, #div, #divs, #dl, #dls, #dt, #dts, #element, #elements, #ellipse, #ellipses, #em, #embed, #embeds, #ems, #extract_selector, #field_set, #field_sets, #fieldset, #fieldsets, #figcaption, #figcaptions, #figure, #figures, #file_field, #file_fields, #font, #fonts, #footer, #footers, #foreign_object, #foreign_objects, #form, #forms, #frame, #frames, #frameset, #framesets, #g, #gs, #h1, #h1s, #h2, #h2s, #h3, #h3s, #h4, #h4s, #h5, #h5s, #h6, #h6s, #head, #header, #headers, #heads, #hidden, #hiddens, #hr, #hrs, #htmls, #i, #iframe, #iframes, #image, #images, #img, #imgs, #input, #inputs, #ins, #inses, #is, #kbd, #kbds, #label, #labels, #legend, #legends, #li, #line, #linear_gradient, #linear_gradients, #lines, #link, #links, #lis, #main, #mains, #map, #maps, #mark, #marker, #markers, #marks, #meta, #metadata, #metadatas, #metas, #meter, #meters, #nav, #navs, #noscript, #noscripts, #object, #objects, #ol, #ols, #optgroup, #optgroups, #option, #options, #output, #outputs, #p, #param, #params, #path, #paths, #pattern, #patterns, #picture, #pictures, #polygon, #polygons, #polyline, #polylines, #pre, #pres, #progress, #progresses, #ps, #q, #qs, #radial_gradient, #radial_gradients, #radio, #radio_set, #radios, #rb, #rbs, #rect, #rects, #rp, #rps, #rt, #rtc, #rtcs, #rts, #rubies, #ruby, #s, #samp, #samps, #script, #scripts, #section, #sections, #select, #select_list, #select_lists, #selects, #small, #smalls, #source, #sources, #span, #spans, #ss, #stop, #stops, #strong, #strongs, #style, #styles, #sub, #subs, #summaries, #summary, #sup, #sups, #svg, #svgs, #switch, #switches, #symbol, #symbols, #table, #tables, #tbody, #tbodys, #td, #tds, #template, #templates, #text_field, #text_fields, #text_path, #text_paths, #textarea, #textareas, #tfoot, #tfoots, #th, #thead, #theads, #ths, #time, #times, #titles, #tr, #track, #tracks, #trs, #tspan, #tspans, #u, #ul, #uls, #us, #use, #uses, #var, #vars, #video, #videos, #view, #views, #wbr, #wbrs

Methods included from JSSnippets

#execute_js

Constructor Details

#initialize(browser = :chrome, *args) ⇒ Browser

Creates a Watir::Browser instance.

Parameters:

  • browser (Symbol, Selenium::WebDriver) (defaults to: :chrome)

    :firefox, :ie, :chrome, :remote or Selenium::WebDriver instance

  • args

    Passed to the underlying driver



42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
# File 'lib/watir/browser.rb', line 42

def initialize(browser = :chrome, *args)
  case browser
  when ::Symbol, String
    selenium_args = Capabilities.new(browser, *args).to_args
    @driver = Selenium::WebDriver.for(*selenium_args)
  when Selenium::WebDriver::Driver
    @driver = browser
  else
    raise ArgumentError, "expected Symbol or Selenium::WebDriver::Driver, got #{browser.class}"
  end

  @after_hooks = AfterHooks.new(self)
  @closed = false
  @default_context = true
end

Instance Attribute Details

#after_hooksObject (readonly)

Returns the value of attribute after_hooks



15
16
17
# File 'lib/watir/browser.rb', line 15

def after_hooks
  @after_hooks
end

#default_context=(value) ⇒ Object (writeonly)

Sets the attribute default_context

Parameters:

  • value

    the value to set the attribute default_context to.



14
15
16
# File 'lib/watir/browser.rb', line 14

def default_context=(value)
  @default_context = value
end

#driverObject (readonly) Also known as: wd

Returns the value of attribute driver



15
16
17
# File 'lib/watir/browser.rb', line 15

def driver
  @driver
end

#locator_namespaceObject

Whether the locators should be used from a different namespace. Defaults to Watir::Locators.



282
283
284
# File 'lib/watir/browser.rb', line 282

def locator_namespace
  @locator_namespace ||= Locators
end

#original_window=(value) ⇒ Object (writeonly)

Sets the attribute original_window

Parameters:

  • value

    the value to set the attribute original_window to.



14
15
16
# File 'lib/watir/browser.rb', line 14

def original_window=(value)
  @original_window = value
end

Class Method Details

.start(url, browser = :chrome, *args) ⇒ Watir::Browser

Creates a Watir::Browser instance and goes to URL.

Examples:

browser = Watir::Browser.start "www.google.com", :chrome
#=> #<Watir::Browser:0x..fa45a499cb41e1752 url="http://www.google.com" title="Google">

Parameters:

  • url (String)
  • browser (Symbol, Selenium::WebDriver) (defaults to: :chrome)

    :firefox, :ie, :chrome, :remote or Selenium::WebDriver instance

Returns:



30
31
32
# File 'lib/watir/browser.rb', line 30

def start(url, browser = :chrome, *args)
  new(browser, *args).tap { |b| b.goto url }
end

Instance Method Details

#alertWatir::Alert

Handles JavaScript alerts, confirms and prompts.

Returns:



162
163
164
# File 'lib/watir/browser.rb', line 162

def alert
  Alert.new(self)
end

#browserObject



273
274
275
# File 'lib/watir/browser.rb', line 273

def browser
  self
end

#closeObject Also known as: quit

Closes browser.



103
104
105
106
107
108
# File 'lib/watir/browser.rb', line 103

def close
  return if @closed

  @driver.quit
  @closed = true
end

#cookiesWatir::Cookies

Handles cookies.

Returns:



117
118
119
# File 'lib/watir/browser.rb', line 117

def cookies
  @cookies ||= Cookies.new driver.manage
end

#ensure_contextObject



265
266
267
268
269
270
271
# File 'lib/watir/browser.rb', line 265

def ensure_context
  return if @default_context

  driver.switch_to.default_content
  @default_context = true
  after_hooks.run
end

#execute_script(script, *args) ⇒ Object

Executes JavaScript snippet.

If you are going to use the value snippet returns, make sure to use `return` explicitly.

Examples:

Check that Ajax requests are completed with jQuery

browser.execute_script("return jQuery.active") == 0
#=> true

Parameters:

  • script (String)

    JavaScript snippet to execute

  • args

    Arguments will be available in the given script in the 'arguments' pseudo-array



216
217
218
219
220
221
222
# File 'lib/watir/browser.rb', line 216

def execute_script(script, *args)
  args.map! do |e|
    e.is_a?(Element) ? e.wait_until(&:exists?).wd : e
  end

  wrap_elements_in(self, @driver.execute_script(script, *args))
end

#exist?Boolean Also known as: exists?

Returns true if browser is not closed and false otherwise.

Returns:

  • (Boolean)


254
255
256
# File 'lib/watir/browser.rb', line 254

def exist?
  !@closed && window.present?
end

#htmlString

Returns HTML code of current page.

Returns:

  • (String)


152
153
154
# File 'lib/watir/browser.rb', line 152

def html
  @driver.page_source
end

#inspectObject Also known as: selector_string



58
59
60
61
62
63
64
65
66
# File 'lib/watir/browser.rb', line 58

def inspect
  if alert.exists?
    format('#<%s:0x%x alert=true>', self.class, hash * 2)
  else
    format('#<%s:0x%x url=%s title=%s>', self.class, hash * 2, url.inspect, title.inspect)
  end
rescue Errno::ECONNREFUSED
  format('#<%s:0x%x closed=true>', self.class, hash * 2)
end

#locateObject

Raises:



259
260
261
262
263
# File 'lib/watir/browser.rb', line 259

def locate
  raise Error, 'browser was closed' if @closed

  ensure_context
end

#nameSymbol

Returns browser name.

Examples:

browser = Watir::Browser.new :chrome
browser.name
#=> :chrome

Returns:



132
133
134
# File 'lib/watir/browser.rb', line 132

def name
  @driver.browser
end

#ready_stateString

Returns readyState of document.

Returns:

  • (String)


188
189
190
# File 'lib/watir/browser.rb', line 188

def ready_state
  execute_script 'return document.readyState'
end

#screenshotWatir::Screenshot

Handles screenshots of current pages.

Returns:



244
245
246
# File 'lib/watir/browser.rb', line 244

def screenshot
  Screenshot.new self
end

#send_keys(*args) ⇒ Object

Sends sequence of keystrokes to currently active element.

Examples:

browser.goto "www.google.com"
browser.send_keys "Watir", :return

Parameters:



234
235
236
# File 'lib/watir/browser.rb', line 234

def send_keys(*args)
  @driver.switch_to.active_element.send_keys(*args)
end

#statusString

Returns the text of status bar.

Returns:

  • (String)


198
199
200
# File 'lib/watir/browser.rb', line 198

def status
  execute_script 'return window.status;'
end

#textString

Returns text of page body.

Returns:

  • (String)


142
143
144
# File 'lib/watir/browser.rb', line 142

def text
  body.text
end

#titleString

Returns title of current page.

Examples:

browser.goto "watir.github.io"
browser.title
#=> "Watir Project"

Returns:

  • (String)


95
96
97
# File 'lib/watir/browser.rb', line 95

def title
  @driver.title
end

#urlString

Returns URL of current page.

Examples:

browser.goto "watir.com"
browser.url
#=> "http://watir.com/"

Returns:

  • (String)


80
81
82
# File 'lib/watir/browser.rb', line 80

def url
  @driver.current_url
end

#wait(timeout = 5) ⇒ Object

Waits until readyState of document is complete.

Examples:

browser.wait

Parameters:

  • timeout (Integer) (defaults to: 5)

Raises:



176
177
178
179
180
# File 'lib/watir/browser.rb', line 176

def wait(timeout = 5)
  wait_until(timeout: timeout, message: "waiting for document.readyState == 'complete'") do
    ready_state == 'complete'
  end
end

#wrap_elements_in(scope, obj) ⇒ Object

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.



290
291
292
293
294
295
296
297
298
299
300
301
# File 'lib/watir/browser.rb', line 290

def wrap_elements_in(scope, obj)
  case obj
  when Selenium::WebDriver::Element
    wrap_element(scope, obj)
  when Array
    obj.map { |e| wrap_elements_in(scope, e) }
  when Hash
    obj.each { |k, v| obj[k] = wrap_elements_in(scope, v) }
  else
    obj
  end
end