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

Attributes included from HasWindow

#original_window

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_while

Methods included from HasWindow

#switch_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, #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



44
45
46
47
48
49
50
51
 
# File 'lib/watir/browser.rb', line 44

def initialize(browser = :chrome, *args)
  @capabilities = browser.is_a?(Capabilities) ? browser : Capabilities.new(browser, *args)
  @driver = browser.is_a?(Selenium::WebDriver::Driver) ? browser : Selenium::WebDriver.for(*@capabilities.to_args)

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

Instance Attribute Details

#after_hooks ⇒ Object (readonly)

Returns the value of attribute after_hooks.



17
18
19
 
# File 'lib/watir/browser.rb', line 17

def after_hooks
  @after_hooks
end

#capabilities ⇒ Object (readonly)

Returns the value of attribute capabilities.



17
18
19
 
# File 'lib/watir/browser.rb', line 17

def capabilities
  @capabilities
end

#default_context=(value) ⇒ Object (writeonly)

Sets the attribute default_context

Parameters:

  • value —

    the value to set the attribute default_context to.



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

def default_context=(value)
  @default_context = value
end

#driver ⇒ Object (readonly) Also known as: wd

Returns the value of attribute driver.



17
18
19
 
# File 'lib/watir/browser.rb', line 17

def driver
  @driver
end

#locator_namespace ⇒ Object

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



292
293
294
 
# File 'lib/watir/browser.rb', line 292

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.



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

def original_window=(value)
  @original_window = value
end

#timer ⇒ Object 



313
314
315
 
# File 'lib/watir/browser.rb', line 313

def timer
  @timer ||= Wait::Timer.new
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:



32
33
34
 
# File 'lib/watir/browser.rb', line 32

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

Instance Method Details

#alert ⇒ Watir::Alert

Handles JavaScript alerts, confirms and prompts.

Returns:



173
174
175
 
# File 'lib/watir/browser.rb', line 173

def alert
  Alert.new(self)
end

#browser ⇒ Object 



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

def browser
  self
end

#close ⇒ Object Also known as: quit

Closes browser.



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

def close
  return if closed?

  @driver.quit
  @closed = true
end

#closed? ⇒ Boolean

Returns true if browser is closed and false otherwise.

Returns:

  • (Boolean) 


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

def closed?
  @closed
end

#cookies ⇒ Watir::Cookies

Handles cookies.

Returns:



128
129
130
 
# File 'lib/watir/browser.rb', line 128

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

#ensure_context ⇒ Object 



276
277
278
279
280
281
 
# File 'lib/watir/browser.rb', line 276

def ensure_context
  return if @default_context

  driver.switch_to.default_content
  @default_context = true
end

#execute_script(script, *args, function_name: nil) ⇒ 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



227
228
229
230
231
232
233
 
# File 'lib/watir/browser.rb', line 227

def execute_script(script, *args, function_name: nil)
  args.map! do |e|
    e.is_a?(Element) ? e.wait_until(&:exists?).wd : e
  end
  Watir.logger.info "Executing Script on Browser: #{function_name}" if function_name
  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) 


265
266
267
 
# File 'lib/watir/browser.rb', line 265

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

#html ⇒ String

Returns HTML code of current page.

Returns:

  • (String) 


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

def html
  @driver.page_source
end

#inspect ⇒ Object Also known as: selector_string

rubocop:disable Metrics/AbcSize



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

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

#locate ⇒ Object

Raises:



270
271
272
273
274
 
# File 'lib/watir/browser.rb', line 270

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

  ensure_context
end

#name ⇒ Symbol

Returns browser name.

Examples:

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

Returns:



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

def name
  @driver.browser
end

#ready_state ⇒ String

Returns readyState of document.

Returns:

  • (String) 


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

def ready_state
  execute_script 'return document.readyState'
end

#screenshot ⇒ Watir::Screenshot

Handles screenshots of current pages.

Returns:



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

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:



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

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

#status ⇒ String

Returns the text of status bar.

Returns:

  • (String) 


209
210
211
 
# File 'lib/watir/browser.rb', line 209

def status
  execute_script 'return window.status;'
end

#text ⇒ String

Returns text of page body.

Returns:

  • (String) 


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

def text
  body.text
end

#title ⇒ String

Returns title of current page.

Examples:

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

Returns:

  • (String) 


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

def title
  @driver.title
end

#url ⇒ String

Returns URL of current page.

Examples:

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

Returns:

  • (String) 


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

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:



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

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. 



300
301
302
303
304
305
306
307
308
309
310
311
 
# File 'lib/watir/browser.rb', line 300

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