Class: Watir::IE

Inherits:
Object
  • Object
show all
Includes:
Container, Exception, PageContainer, WaitHelper
Defined in:
lib/watir-classic/ie-class.rb,
lib/watir-classic/process.rb,
lib/watir-classic/ie-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) ⇒ IE

Create an IE browser instance.

Parameters:

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

    set to true for not creating a IE window.



232
233
234
 
# File 'lib/watir-classic/ie-class.rb', line 232

def initialize(suppress_new_window=nil)
  _new_window_init unless suppress_new_window
end

Class Attribute Details

.attach_timeout ⇒ Object 



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

def attach_timeout
  @attach_timeout ||= 2
end

.speed ⇒ Object 



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

def speed
  @speed ||= :slow
end

.visible ⇒ Object 



41
42
43
 
# File 'lib/watir-classic/ie-class.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.



218
219
220
 
# File 'lib/watir-classic/ie-class.rb', line 218

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.



304
305
306
307
 
# File 'lib/watir-classic/ie-class.rb', line 304

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

#ie ⇒ Object

The OLE Internet Explorer object.



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

def ie
  @ie
end

#url_list ⇒ Object (readonly)

The list of unique urls that have been visited.



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

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 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/ie-class.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 (IE) —

    instances of IE found.



113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/watir-classic/ie-class.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:



146
147
148
149
 
# File 'lib/watir-classic/ie-class.rb', line 146

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/ie-class.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/ie-class.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 IE. BUG: this interface invites misunderstanding/misuse such as IE.options = :zippy]



19
20
21
 
# File 'lib/watir-classic/ie-class.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 IE.



24
25
26
27
28
 
# File 'lib/watir-classic/ie-class.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/ie-class.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/ie-class.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/ie-class.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
 
# File 'lib/watir-classic/ie-class.rb', line 129

def version
  @ie_version ||= begin
                    require 'win32/registry'
                    ::Win32::Registry::HKEY_LOCAL_MACHINE.open("SOFTWARE\\Microsoft\\Internet Explorer") do |ie_key|
                      ie_key.read('Version').last
                    end
                    # OR: ::WIN32OLE.new("WScript.Shell").RegRead("HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Internet Explorer\\Version")
                  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.



140
141
142
 
# File 'lib/watir-classic/ie-class.rb', line 140

def version_parts
  version.split('.')
end

Instance Method Details

#activate ⇒ Object Also known as: bring_to_front

Make the window come to the front.



417
418
419
 
# File 'lib/watir-classic/ie-class.rb', line 417

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.



424
425
426
 
# File 'lib/watir-classic/ie-class.rb', line 424

def active?
  rautomation.active?
end

#add_checker(checker) ⇒ 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) —

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



512
513
514
 
# File 'lib/watir-classic/ie-class.rb', line 512

def add_checker(checker)
  @error_checkers << checker
end

#autoit ⇒ Object

Deprecated.

use #rautomation instead.



437
438
439
440
 
# File 'lib/watir-classic/ie-class.rb', line 437

def autoit
  Kernel.warn "Deprecated(IE#autoit) - use IE#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.



352
353
354
355
 
# File 'lib/watir-classic/ie-class.rb', line 352

def back
  @ie.GoBack
  wait
end

#clear_url_list ⇒ Object

Clear the list of urls that have been visited.



376
377
378
 
# File 'lib/watir-classic/ie-class.rb', line 376

def clear_url_list
  @url_list.clear
end

#close ⇒ Object

Close the Browser.



381
382
383
384
385
386
387
388
389
390
391
392
393
394
 
# File 'lib/watir-classic/ie-class.rb', line 381

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.



502
503
504
 
# File 'lib/watir-classic/ie-class.rb', line 502

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.



519
520
521
 
# File 'lib/watir-classic/ie-class.rb', line 519

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

#document ⇒ WIN32OLE

Returns current IE document.

Returns:

  • (WIN32OLE) —

    current IE document.



457
458
459
 
# File 'lib/watir-classic/ie-class.rb', line 457

def document
  @ie.document
end

#exists? ⇒ Boolean Also known as: exist?

Returns true when IE is window exists, false otherwise.

Returns:

  • (Boolean) —

    true when IE is window exists, false otherwise.



315
316
317
318
319
 
# File 'lib/watir-classic/ie-class.rb', line 315

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

#focus ⇒ Object

Gives focus to the window frame.



524
525
526
527
528
 
# File 'lib/watir-classic/ie-class.rb', line 524

def focus
  active_element = document.activeElement
  active_element.blur unless 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.



359
360
361
362
 
# File 'lib/watir-classic/ie-class.rb', line 359

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.



343
344
345
346
347
348
 
# File 'lib/watir-classic/ie-class.rb', line 343

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

#inspect ⇒ Object 



371
372
373
 
# File 'lib/watir-classic/ie-class.rb', line 371

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).



397
398
399
 
# File 'lib/watir-classic/ie-class.rb', line 397

def maximize
  rautomation.maximize
end

#minimize ⇒ Object

Minimize the window (appears as icon on taskbar).



402
403
404
 
# File 'lib/watir-classic/ie-class.rb', line 402

def minimize
  rautomation.minimize
end

#minimized? ⇒ Boolean

Returns true when window is minimized, false otherwise.

Returns:

  • (Boolean) —

    true when window is minimized, false otherwise.



407
408
409
 
# File 'lib/watir-classic/ie-class.rb', line 407

def minimized?
  rautomation.minimized?
end

#name ⇒ Symbol

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

Returns:

  • (Symbol) —

    the name of the browser. Is always :ie.



310
311
312
 
# File 'lib/watir-classic/ie-class.rb', line 310

def name
  :ie
end

#rautomation ⇒ RAutomation::Window

Returns the RAutomation instance for this IE window.

Returns:

  • (RAutomation::Window) —

    the RAutomation instance for this IE window.

See Also:



432
433
434
 
# File 'lib/watir-classic/ie-class.rb', line 432

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.



366
367
368
369
 
# File 'lib/watir-classic/ie-class.rb', line 366

def refresh
  @ie.refresh2(3)
  wait
end

#restore ⇒ Object

Restore the window (after minimizing or maximizing).



412
413
414
 
# File 'lib/watir-classic/ie-class.rb', line 412

def restore
  rautomation.restore
end

#screenshot ⇒ Object

Create a Screenshot instance.



467
468
469
 
# File 'lib/watir-classic/ie-class.rb', line 467

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:



448
449
450
 
# File 'lib/watir-classic/ie-class.rb', line 448

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

#set_fast_speed ⇒ Object

Deprecated.

Use #speed= with :fast argument instead.



279
280
281
282
 
# File 'lib/watir-classic/ie-class.rb', line 279

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

#set_slow_speed ⇒ Object

Deprecated.

Use #speed= with :slow argument instead.



285
286
287
288
 
# File 'lib/watir-classic/ie-class.rb', line 285

def set_slow_speed
  Kernel.warn "Deprecated(IE.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.



273
274
275
276
 
# File 'lib/watir-classic/ie-class.rb', line 273

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.



250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/watir-classic/ie-class.rb', line 250

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.



330
331
332
333
334
 
# File 'lib/watir-classic/ie-class.rb', line 330

def status
  @ie.statusText
rescue WIN32OLERuntimeError
  ""
end

#title ⇒ String

Returns the title of the document.

Returns:

  • (String) —

    the title of the document.



324
325
326
 
# File 'lib/watir-classic/ie-class.rb', line 324

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.



462
463
464
 
# File 'lib/watir-classic/ie-class.rb', line 462

def url
  @ie.LocationURL
end

#visible ⇒ Boolean

Returns true when window is visible, false otherwise.

Returns:

  • (Boolean) —

    true when window is visible, false otherwise.



291
292
293
 
# File 'lib/watir-classic/ie-class.rb', line 291

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.



298
299
300
 
# File 'lib/watir-classic/ie-class.rb', line 298

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.



489
490
491
492
493
 
# File 'lib/watir-classic/ie-class.rb', line 489

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:



497
498
499
 
# File 'lib/watir-classic/ie-class.rb', line 497

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