Class: Watir::Browser

Inherits:
Object
  • Object
show all
Includes:
Container, Exception, PageContainer, WaitHelper
Defined in:
lib/watir-classic/browser.rb,
lib/watir-classic/process.rb,
lib/watir-classic/browser_process.rb

Overview

Main browser class.

Defined Under Namespace

Classes: Process

Class Attribute Summary collapse

Instance Attribute Summary collapse

Attributes included from Container

#page_container

Class Method Summary collapse

Instance Method Summary collapse

Methods included from PageContainer

#contains_text, #execute_script, #html, #text

Methods included from Exception

message_for_unable_to_locate

Methods included from Container

#a, #abbr, #address, #alert, #area, #article, #aside, #audio, #b, #base, #bdi, #bdo, #blockquote, #body, #br, #button, #canvas, #caption, #checkbox, #cite, #code, #col, #colgroup, #command, #data, #datalist, #dd, #del, #details, #dfn, #div, #dl, #dt, #element, #em, #embed, #fieldset, #figcaption, #figure, #file_field, #font, #footer, #form, #frame, #frameset, #h1, #h2, #h3, #h4, #h5, #h6, #head, #header, #hgroup, #hidden, #hr, #i, #img, #input, #ins, #kbd, #keygen, #label, #legend, #li, #map, #mark, #menu, #meta, #meter, #modal_dialog, #nav, #noscript, #object, #ol, #optgroup, #option, #output, #p, #param, #pre, #progress, #q, #radio, #rp, #rt, #ruby, #s, #samp, #script, #section, #select, #small, #source, #span, #strong, #style, #sub, #summary, #sup, #table, #tbody, #td, #text_field, #textarea, #tfoot, #th, #thead, #time, #tr, #track, #u, #ul, #var, #video, #wbr

Methods included from WaitHelper

#wait_until, #wait_while

Constructor Details

#initialize(suppress_new_window = nil) ⇒ Browser

Create an IE browser instance.

Parameters:

  • suppress_new_window (Boolean) (defaults to: nil) —

    set to true for not creating a IE window.



235
236
237
 
# File 'lib/watir-classic/browser.rb', line 235

def initialize(suppress_new_window=nil)
  _new_window_init unless suppress_new_window == true 
end

Class Attribute Details

.attach_timeout ⇒ Object 



13
14
15
 
# File 'lib/watir-classic/browser.rb', line 13

def attach_timeout
  @attach_timeout ||= 2
end

.speed ⇒ Object 



34
35
36
 
# File 'lib/watir-classic/browser.rb', line 34

def speed
  @speed ||= :slow
end

.visible ⇒ Object 



41
42
43
 
# File 'lib/watir-classic/browser.rb', line 41

def visible
  @visible ||= true
end

Instance Attribute Details

#down_load_time ⇒ Object (readonly)

The time, in seconds, it took for the new page to load after executing the last command.



221
222
223
 
# File 'lib/watir-classic/browser.rb', line 221

def down_load_time
  @down_load_time
end

#hwnd ⇒ Fixnum

Returns current IE window handle.

Returns:

  • (Fixnum) —

    current IE window handle.

Raises:

  • (RuntimeError) —

    when not attached to a browser.



307
308
309
310
 
# File 'lib/watir-classic/browser.rb', line 307

def hwnd
  raise "Not attached to a browser" if @ie.nil?
  @hwnd ||= @ie.hwnd
end

#ie ⇒ Object

The OLE Internet Explorer object.



224
225
226
 
# File 'lib/watir-classic/browser.rb', line 224

def ie
  @ie
end

#url_list ⇒ Object (readonly)

The list of unique urls that have been visited.



227
228
229
 
# File 'lib/watir-classic/browser.rb', line 227

def url_list
  @url_list
end

Class Method Details

.attach(how, what) ⇒ Object

Note:

This method will not work when Watir/Ruby is run under a service (instead of a user).

Attach to an existing IE Watir::Browser.

Examples:

Attach with full title:

Watir::Browser.attach(:title, "Full title of IE")

Attach with part of the title using Regexp:

Watir::Browser.attach(:title, /part of the title of IE/)

Attach with part of the url:

Watir::Browser.attach(:url, /google/)

Attach with window handle:

Watir::Browser.attach(:hwnd, 123456)

Parameters:

  • how (Symbol) —

    type of the locator. Can be :title, :url or :hwnd.

  • what (Symbol) —

    value of the locator. Can be String, Regexp or Fixnum depending of the type parameter.



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

def attach(how, what)
  ie = new true # don't create window
  ie._attach_init(how, what)
  ie
end

.each {|ie| ... } ⇒ Object

Note:

This method will not work when Watir/Ruby is run under a service (instead of a user).

Yields successively to each IE window on the current desktop. Takes a block.

Yield Parameters:

  • ie (Browser) —

    instances of IE found.



113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/watir-classic/browser.rb', line 113

def each
  shell = WIN32OLE.new('Shell.Application')
  ie_browsers = []
  shell.Windows.each do |window|
    next unless (window.path =~ /Internet Explorer/ rescue false)
    next unless (hwnd = window.hwnd rescue false)
    ie = bind(window)
    ie.hwnd = hwnd
    ie_browsers << ie
  end
  ie_browsers.each do |ie|
    yield ie
  end
end

.find(how, what) ⇒ Object

Find existing IE window with locators.

See Also:



149
150
151
152
 
# File 'lib/watir-classic/browser.rb', line 149

def find(how, what)
  ie_ole = _find(how, what)
  bind ie_ole if ie_ole
end

.new_process ⇒ Object

Note:

This method will not work when Watir/Ruby is run under a service (instead of a user).

Create a new IE window in a new process.



69
70
71
72
73
 
# File 'lib/watir-classic/browser.rb', line 69

def new_process
  ie = new true
  ie._new_process_init
  ie
end

.new_window ⇒ Object

Create a new IE window.



46
47
48
49
50
 
# File 'lib/watir-classic/browser.rb', line 46

def new_window
  ie = new true
  ie._new_window_init
  ie
end

.options ⇒ Object

Return the options used when creating new instances of Watir::Browser. BUG: this interface invites misunderstanding/misuse such as Browser.options = :zippy]



19
20
21
 
# File 'lib/watir-classic/browser.rb', line 19

def options
  {:speed => self.speed, :visible => self.visible, :attach_timeout => self.attach_timeout}
end

.process_count ⇒ Fixnum

Returns the number of IEXPLORE processes currently running.

Returns:

  • (Fixnum) —

    number of ie processes.



18
19
20
 
# File 'lib/watir-classic/process.rb', line 18

def self.process_count
  Watir::Process.count 'iexplore.exe'
end

.set_options(options) ⇒ Object

set values for options used when creating new instances of Watir::Browser.



24
25
26
27
28
 
# File 'lib/watir-classic/browser.rb', line 24

def set_options options
  options.each do |name, value|
    send "#{name}=", value
  end
end

.start(url = nil) ⇒ Object

Create a new IE, starting at the specified url.

Parameters:

  • url (String) (defaults to: nil) —

    url to navigate to.



54
55
56
 
# File 'lib/watir-classic/browser.rb', line 54

def start(url=nil)
  start_window url
end

.start_process(url = nil) ⇒ Object

Create a new IE window in a new process, starting at the specified URL.

Parameters:

  • url (String) (defaults to: nil) —

    url to navigate to.



77
78
79
80
81
 
# File 'lib/watir-classic/browser.rb', line 77

def start_process(url=nil)
  ie = new_process
  ie.goto url if url
  ie
end

.start_window(url = nil) ⇒ Object

Create a new IE window, starting at the specified url.

Parameters:

  • url (String) (defaults to: nil) —

    url to navigate to.



60
61
62
63
64
 
# File 'lib/watir-classic/browser.rb', line 60

def start_window(url=nil)
  ie = new_window
  ie.goto url if url
  ie
end

.version ⇒ String

Returns the IE browser version number as a string.

Returns:

  • (String) —

    the IE browser version number as a string.



129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/watir-classic/browser.rb', line 129

def version
  @ie_version ||= begin
                    require 'win32/registry'
                    ::Win32::Registry::HKEY_LOCAL_MACHINE.open("SOFTWARE\\Microsoft\\Internet Explorer") do |ie_key|
                      begin
                        ie_key['svcVersion']
                      rescue ::Win32::Registry::Error
                        ie_key['Version']
                      end
                    end
                  end
end

.version_parts ⇒ Array<String>

Returns the IE browser version numbers split by “.” in an Array.

Returns:

  • (Array<String>) —

    the IE browser version numbers split by “.” in an Array.



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

def version_parts
  version.split('.')
end

Instance Method Details

#activate ⇒ Object Also known as: bring_to_front

Make the window come to the front.



420
421
422
 
# File 'lib/watir-classic/browser.rb', line 420

def activate
  rautomation.activate
end

#active? ⇒ Boolean Also known as: front?

Returns true when window is in front e.g. in focus, false otherwise.

Returns:

  • (Boolean) —

    true when window is in front e.g. in focus, false otherwise.



427
428
429
 
# File 'lib/watir-classic/browser.rb', line 427

def active?
  rautomation.active?
end

#add_checker(checker = nil, &block) ⇒ Object

Add an error checker that gets executed after every page load, click etc.

Examples:

browser.add_checker lambda { |browser| raise "Error!" if browser.text.include? "Error" }

Parameters:

  • checker (Proc) (defaults to: nil) —

    Proc object which gets yielded with Watir::Browser instance.



515
516
517
518
519
520
521
522
523
 
# File 'lib/watir-classic/browser.rb', line 515

def add_checker(checker = nil, &block)
  if block_given?
    @error_checkers << block
  elsif checker.respond_to? :call
    @error_checkers << checker
  else
    raise ArgumentError, "expected block or object responding to #call"
  end
end

#autoit ⇒ Object

Deprecated.

use #rautomation instead.



440
441
442
443
 
# File 'lib/watir-classic/browser.rb', line 440

def autoit
  Kernel.warn "Deprecated(Browser#autoit) - use Browser#rautomation instead. Refer to https://github.com/jarmo/RAutomation for updating your scripts."
  @autoit ||= ::RAutomation::Window.new(:hwnd => hwnd, :adapter => :autoit)
end

#back ⇒ Object

Go to the previous page - the same as clicking the browsers back button.

Raises:

  • (WIN32OLERuntimeError) —

    when the browser can’t go back.



355
356
357
358
 
# File 'lib/watir-classic/browser.rb', line 355

def back
  @ie.GoBack
  wait
end

#clear_url_list ⇒ Object

Clear the list of urls that have been visited.



379
380
381
 
# File 'lib/watir-classic/browser.rb', line 379

def clear_url_list
  @url_list.clear
end

#close ⇒ Object

Close the Watir::Browser.



384
385
386
387
388
389
390
391
392
393
394
395
396
397
 
# File 'lib/watir-classic/browser.rb', line 384

def close
  return unless exists?
  @ie.stop
  wait rescue nil
  chwnd = @ie.hwnd.to_i
  @ie.quit
  t = ::Time.now
  while exists?
    # just in case to avoid possible endless loop if failing to close some
    # window or tab
    break if ::Time.now - t > 10
    sleep 0.3
  end
end

#cookies ⇒ Object

Retrieve Cookies instance.



505
506
507
 
# File 'lib/watir-classic/browser.rb', line 505

def cookies
  Cookies.new(self)
end

#disable_checker(checker) ⇒ Object

Disable an error checker added via #add_checker.

Parameters:

  • checker (Proc) —

    Proc object to be removed from error checkers.



528
529
530
 
# File 'lib/watir-classic/browser.rb', line 528

def disable_checker(checker)
  @error_checkers.delete(checker)
end

#document ⇒ WIN32OLE

Returns current IE document.

Returns:

  • (WIN32OLE) —

    current IE document.



460
461
462
 
# File 'lib/watir-classic/browser.rb', line 460

def document
  @ie.document
end

#exists? ⇒ Boolean Also known as: exist?

Returns true when IE window exists, false otherwise.

Returns:

  • (Boolean) —

    true when IE window exists, false otherwise.



318
319
320
321
322
 
# File 'lib/watir-classic/browser.rb', line 318

def exists?
  !!(@ie.name =~ /Internet Explorer/)
rescue WIN32OLERuntimeError, NoMethodError
  false
end

#focus ⇒ Object

Gives focus to the window frame.



533
534
535
536
537
 
# File 'lib/watir-classic/browser.rb', line 533

def focus
  active_element = document.activeElement
  active_element.blur if active_element && active_element.tagName != "BODY"
  document.focus
end

#forward ⇒ Object

Go to the next page - the same as clicking the browsers forward button.

Raises:

  • (WIN32OLERuntimeError) —

    when the browser can’t go forward.



362
363
364
365
 
# File 'lib/watir-classic/browser.rb', line 362

def forward
  @ie.GoForward
  wait
end

#goto(url) ⇒ Fixnum

Navigate to the specified URL.

Parameters:

  • url (String) —

    url to navigate to.

Returns:

  • (Fixnum) —

    time in seconds the page took to load.



346
347
348
349
350
351
 
# File 'lib/watir-classic/browser.rb', line 346

def goto(url)
  url = "http://" + url unless url =~ %r{://} || url == "about:blank"
  @ie.navigate(url)
  wait
  return @down_load_time
end

#inspect ⇒ Object 



374
375
376
 
# File 'lib/watir-classic/browser.rb', line 374

def inspect
  '#<%s:0x%x url=%s title=%s>' % [self.class, hash*2, url.inspect, title.inspect]
end

#maximize ⇒ Object

Maximize the window (expands to fill the screen).



400
401
402
 
# File 'lib/watir-classic/browser.rb', line 400

def maximize
  rautomation.maximize
end

#minimize ⇒ Object

Minimize the window (appears as icon on taskbar).



405
406
407
 
# File 'lib/watir-classic/browser.rb', line 405

def minimize
  rautomation.minimize
end

#minimized? ⇒ Boolean

Returns true when window is minimized, false otherwise.

Returns:

  • (Boolean) —

    true when window is minimized, false otherwise.



410
411
412
 
# File 'lib/watir-classic/browser.rb', line 410

def minimized?
  rautomation.minimized?
end

#name ⇒ Symbol

Returns the name of the browser. Is always :internet_explorer.

Returns:

  • (Symbol) —

    the name of the browser. Is always :internet_explorer.



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

def name
  :internet_explorer
end

#rautomation ⇒ RAutomation::Window

Returns the RAutomation instance for this IE window.

Returns:

  • (RAutomation::Window) —

    the RAutomation instance for this IE window.

See Also:



435
436
437
 
# File 'lib/watir-classic/browser.rb', line 435

def rautomation
  @rautomation ||= ::RAutomation::Window.new(:hwnd => hwnd)
end

#refresh ⇒ Object

Refresh the current page - the same as clicking the browsers refresh button.

Raises:

  • (WIN32OLERuntimeError) —

    when the browser can’t refresh.



369
370
371
372
 
# File 'lib/watir-classic/browser.rb', line 369

def refresh
  @ie.refresh2(3)
  wait
end

#restore ⇒ Object

Restore the window (after minimizing or maximizing).



415
416
417
 
# File 'lib/watir-classic/browser.rb', line 415

def restore
  rautomation.restore
end

#screenshot ⇒ Object

Create a Screenshot instance.



470
471
472
 
# File 'lib/watir-classic/browser.rb', line 470

def screenshot
  Screenshot.new(hwnd)
end

#send_keys(*keys) ⇒ Object

Activates the window and sends keys to it.

Examples:

browser.send_keys("Hello World", :enter)

See Also:



451
452
453
 
# File 'lib/watir-classic/browser.rb', line 451

def send_keys(*keys)
  rautomation.send_keys *keys
end

#set_fast_speed ⇒ Object

Deprecated.

Use #speed= with :fast argument instead.



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

def set_fast_speed
  Kernel.warn "Deprecated(Browser.set_fast_speed) - use Browser#speed = :fast instead."
  self.speed = :fast
end

#set_slow_speed ⇒ Object

Deprecated.

Use #speed= with :slow argument instead.



288
289
290
291
 
# File 'lib/watir-classic/browser.rb', line 288

def set_slow_speed
  Kernel.warn "Deprecated(Browser.set_slow_speed) - use Browser#speed = :slow instead."
  self.speed = :slow
end

#speed ⇒ Symbol

Returns current speed setting. May be :slow, :fast or :zippy.

Returns:

  • (Symbol) —

    current speed setting. May be :slow, :fast or :zippy.



276
277
278
279
 
# File 'lib/watir-classic/browser.rb', line 276

def speed
  return @speed if @speed == :slow
  return @type_keys ? :fast : :zippy
end

#speed=(how_fast) ⇒ Object

Note:

:zippy speed does not trigger JavaScript events like onChange etc.

Specifies the speed that commands will be executed at. Possible choices are:

  • :slow (default)

  • :fast

  • :zippy

With :zippy, text fields will be entered at once, instead of character by character.

Parameters:

  • how_fast (Symbol) —

    possible choices are :slow (default), :fast and :zippy

Raises:

  • (ArgumentError) —

    when invalid speed is specified.



253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/watir-classic/browser.rb', line 253

def speed=(how_fast)
  case how_fast
  when :zippy
    @typingspeed = 0
    @pause_after_wait = 0.01
    @type_keys = false
    @speed = :fast
  when :fast
    @typingspeed = 0
    @pause_after_wait = 0.01
    @type_keys = true
    @speed = :fast
  when :slow
    @typingspeed = 0.08
    @pause_after_wait = 0.1
    @type_keys = true
    @speed = :slow
  else
    raise ArgumentError, "Invalid speed: #{how_fast}. Possible choices are :slow, :fast and :zippy."
  end
end

#status ⇒ String

Returns the status text of the window, typically from the status bar at the bottom. Will be empty if there’s no status or when there are problems accessing status text.

Returns:

  • (String) —

    the status text of the window, typically from the status bar at the bottom. Will be empty if there’s no status or when there are problems accessing status text.



333
334
335
336
337
 
# File 'lib/watir-classic/browser.rb', line 333

def status
  @ie.statusText
rescue WIN32OLERuntimeError
  ""
end

#title ⇒ String

Returns the title of the document.

Returns:

  • (String) —

    the title of the document.



327
328
329
 
# File 'lib/watir-classic/browser.rb', line 327

def title
  @ie.document.title
end

#url ⇒ String

Returns current url, as displayed in the address bar of the browser.

Returns:

  • (String) —

    current url, as displayed in the address bar of the browser.



465
466
467
 
# File 'lib/watir-classic/browser.rb', line 465

def url
  @ie.LocationURL
end

#visible ⇒ Boolean

Returns true when window is visible, false otherwise.

Returns:

  • (Boolean) —

    true when window is visible, false otherwise.



294
295
296
 
# File 'lib/watir-classic/browser.rb', line 294

def visible
  @ie.visible
end

#visible=(boolean) ⇒ Object

Set the visibility of IE window.

Parameters:

  • boolean (Boolean) —

    set to true if IE window should be visible, false otherwise.



301
302
303
 
# File 'lib/watir-classic/browser.rb', line 301

def visible=(boolean)
  @ie.visible = boolean if boolean != @ie.visible
end

#window(specifiers = {}) { ... } ⇒ Window

Retrieve a Window instance.

Examples:

Retrieve a different window without block.

browser.window(:title => /other window title/).use
browser.title # => "other window title"

Use different window with block.

browser.window(:title => /other window title/) do
  browser.title # => "other window title"
end
browser.title # => "current window title"

Parameters:

  • specifiers (Hash) (defaults to: {}) —

    options for finding window.

Options Hash (specifiers):

  • :title (String, Regexp) —

    Title of the window.

  • :url (String, Regexp) —

    Url of the window.

  • :index (Fixnum) —

    The index of the window.

Yields:

  • yield optionally to the found window.

Returns:

  • (Window) —

    found window instance.



492
493
494
495
496
 
# File 'lib/watir-classic/browser.rb', line 492

def window(specifiers={}, &blk)
  win = Window.new(self, specifiers, &blk)
  win.use &blk if blk
  win
end

#windows(specifiers = {}) ⇒ Array<Window>

Returns array of found windows.

Returns:

  • (Array<Window>) —

    array of found windows.

See Also:



500
501
502
 
# File 'lib/watir-classic/browser.rb', line 500

def windows(specifiers={})
  self.class._find_all(specifiers.keys.first, specifiers.values.first).map {|ie| Window.new(self, specifiers, self.class.bind(ie))}
end