Module: WatirRobot::Browser

Included in:
KeywordLibrary
Defined in:
lib/watir_robot/keywords/browser.rb

Overview

Functionality at the browser level, including browser history and cookie handling

Instance Method Summary collapse

Instance Method Details

#close_browser ⇒ Object

Close current browser



116
117
118
 
# File 'lib/watir_robot/keywords/browser.rb', line 116

def close_browser
  @browser.close
end

#close_other_window ⇒ Object

Close “other” window; assumes there are only 2 open



207
208
209
210
211
212
213
214
 
# File 'lib/watir_robot/keywords/browser.rb', line 207

def close_other_window
  @window_id = (@window_id - 1).abs
  if @window_id != 0 and @window_id !=1
    raise(Exception::WindowMatchError, "You cannot use this keyword when more than 2 windows are open; you must use 'Switch To Window', 'Switch to Next Window', or 'Switch to Previous Window'")
  end

  @browser.windows[@window_id].close
end

#close_window(close_loc = :current, active_loc = nil) ⇒ Object

Close a single browser window

If you have multiple windows open and you close a non-active window, the window is simply closed. If you have multiple windows open and you close the active window, by default, the “previous” window will become the active one before closing the specified window (to avoid browser crashes). You can optionally specify which window should be used upon closing the active one. If you have only one window open and you issue this command, it is the same as calling “Close Browser”, and the entire browser instance will be closed.

Parameters:

  • close_loc (String) (defaults to: :current) —

    the identifier for the window you wish to close, either title, url, or integer



229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
 
# File 'lib/watir_robot/keywords/browser.rb', line 229

def close_window(close_loc = :current, active_loc = nil)
  if @browser.windows.count == 1
    # doesn't matter what they enter, bc closing the only window of a browser

    # instance causes the browser to crash

    @browser.close
  end


  if close_loc == :current
    # if the current window is being closed, we have to move to another before closing it

    if active_loc.nil?
      # if new active window is unspecified, make the previous window the new active one

      self.switch_to_previous_window
    else
      self.switch_to_window(active_loc)
    end
  else
    # a specific window to be closed has been specified (though it may still be the active one)

    if close_loc[0..3] == 'url=' or close_loc[0..5] == 'title='
      if @browser.window(parse_location(close_loc)).current?
        # if the current window is being closed, we have to move to another before closing it

        if active_loc.nil?
          # if new active window is unspecified, make the previous window the new active one

          self.switch_to_previous_window
        else
          self.switch_to_window(active_loc)
        end
      end
      @browser.window(parse_location(close_loc)).close
    else
      # assume close_loc is an integer

      # since Robot Framework sends all args as text, the above check for

      # "url=" and "title=" is the best we can do to ensure argument correctness

      close_loc = close_loc.to_i
      # the number of the window

      # user-facing numbers are 1-based, internal we use 0-based because @browser.windows

      # is a Ruby array, so minus 1

      window_id = close_loc - 1
      if window_id == -1
        # either the user has been too smart for his/her own good and thinks the windows are 0-based,

        # or they've entered text that doesn't match 'url=' or 'title=', in which case

        # the above loc.to_i will make loc equal 0

        raise(ArgumentError, "You must provide the url or title of the window in the format 'url=' or 'title=', or you must provide the number of the window, starting with 1 for the first window opened.")
      end
      
      if @browser.windows[window_id].current?
        # if the current window is being closed, we have to move to another before closing it

        if active_loc.nil?
          # if new active window is unspecified, make the previous window the new active one

          self.switch_to_previous_window
        else
          self.switch_to_window(active_loc)
        end
      end
      # this will throw its own error if the index is out of range

      @browser.windows[window_id].close
    end
  end
end

#delete_all_cookies ⇒ Object

Delete all browser cookies



100
101
102
 
# File 'lib/watir_robot/keywords/browser.rb', line 100

def delete_all_cookies
  @browser.clear_cookies
end

#delete_cookie(name) ⇒ Object

Delete individual cookie, identified by name

Parameters:

  • name (String) —

    name of the cookie



109
110
111
 
# File 'lib/watir_robot/keywords/browser.rb', line 109

def delete_cookie(name)
  @driver.manage.delete_cookie(name)
end

#get_all_cookies ⇒ Array<Hash>

Get all cookies defined in the current session

Returns:

  • (Array<Hash>) —

    list of cookies



83
84
85
 
# File 'lib/watir_robot/keywords/browser.rb', line 83

def get_all_cookies
  @driver.manage.all_cookies
end

#get_cookie(name) ⇒ Hash?

Get a cookie by name

Parameters:

  • name (String) —

    name of the cookie

Returns:

  • (Hash, nil) —

    the cookie or nil, if it doesn’t exist



93
94
95
 
# File 'lib/watir_robot/keywords/browser.rb', line 93

def get_cookie(name)
  @driver.manage.cookie_named(name)
end

#get_url ⇒ String

Get current URL

Returns:

  • (String) —

    URL of the current page



44
45
46
 
# File 'lib/watir_robot/keywords/browser.rb', line 44

def get_url
  @browser.url
end

#get_window_count ⇒ Object

Return the number of open windows



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

def get_window_count
  return @browser.windows.count
end

#go_back ⇒ Object

Go back in browsing history



60
61
62
 
# File 'lib/watir_robot/keywords/browser.rb', line 60

def go_back
  @browser.back
end

#go_forward ⇒ Object

Go forward in browsing history



67
68
69
 
# File 'lib/watir_robot/keywords/browser.rb', line 67

def go_forward
  @browser.forward
end

#go_to(url) ⇒ Object

Go to specific URL in already-opened browser

Parameters:

  • url (String) —

    the URL to navigate to



53
54
55
 
# File 'lib/watir_robot/keywords/browser.rb', line 53

def go_to(url)
  @browser.goto(url)
end

#maximize_browser_window ⇒ Object

Maximize browser window (uses JavaScript)



123
124
125
126
127
128
129
 
# File 'lib/watir_robot/keywords/browser.rb', line 123

def maximize_browser_window
  @browser.execute_script(
    "if (window.screen) {
       window.moveTo(0, 0);
       window.resizeTo(window.screen.availWidth, window.screen.availHeight);
     };")
end

#open_browser(browser = 'firefox') ⇒ Object

Start browser

Parameters:

  • browser (String) (defaults to: 'firefox') —

    the name of the browser to use, must match a name recognized by WebDriver

Returns:

  • (Object) —

    the browser object with which to drive the browser



16
17
18
19
20
21
22
23
24
 
# File 'lib/watir_robot/keywords/browser.rb', line 16

def open_browser(browser = 'firefox')
  profile = Selenium::WebDriver::Firefox::Profile.new
  profile.native_events = false

  @browser = Watir::Browser.new(browser.to_sym, :profile => profile)
  @driver = @browser.driver
  @window_id = 0
  return @browser
end

#refresh ⇒ Object

Refresh the current page



74
75
76
 
# File 'lib/watir_robot/keywords/browser.rb', line 74

def refresh
  @browser.refresh
end

#start_browser(url, browser = 'firefox') ⇒ Object

Open browser and go to specific URL

Parameters:

  • url (String) —

    the URL to navigate to

  • browser (String) (defaults to: 'firefox') —

    the name of the browser to use, must match a name recognized by WebDriver

Returns:

  • (Object) —

    the browser object with which to drive the browser



33
34
35
36
37
 
# File 'lib/watir_robot/keywords/browser.rb', line 33

def start_browser(url, browser = 'firefox')
  self.open_browser browser
  @browser.goto url
  return @browser
end

#switch_to_next_window ⇒ Object

Switch to “next” window, the order depending on order of original opening.

If the “last” window is active and you ask for the next, you will be taken back to the first window (i.e. it wraps around)



178
179
180
181
182
183
184
185
186
 
# File 'lib/watir_robot/keywords/browser.rb', line 178

def switch_to_next_window
  @window_id += 1
  if @window_id >= @browser.windows.count
    # wrap back to the first

    @window_id = 0
  end

  @browser.windows[@window_id].use
end

#switch_to_other_window ⇒ Object

Switch to “other” window; assumes there are only 2 open



134
135
136
137
138
139
140
141
142
 
# File 'lib/watir_robot/keywords/browser.rb', line 134

def switch_to_other_window
  @window_id = (@window_id - 1).abs
  if @window_id != 0 and @window_id !=1
    puts @window_id
    raise(Exception::WindowMatchError, "You cannot use this keyword when more than 2 windows are open; you must use 'Switch To Window', 'Switch to Next Window', or 'Switch to Previous Window'")
  end

  @browser.windows[@window_id].use
end

#switch_to_previous_window ⇒ Object

Switch to “previous” window, the order depending on order of original opening.

If the “first” window is active and you ask for the previous, you will be taken around to the last window (i.e. it wraps around)



194
195
196
197
198
199
200
201
202
 
# File 'lib/watir_robot/keywords/browser.rb', line 194

def switch_to_previous_window
  @window_id -= 1
  if @window_id < 0
    # wrap back to the last

    @window_id = @browser.windows.count - 1
  end

  @browser.windows[@window_id].use
end

#switch_to_window(loc) ⇒ Object

Switch to a specified opened window

Parameters:

  • loc (String) —

    attribute/value pairs that match an HTML element



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/watir_robot/keywords/browser.rb', line 149

def switch_to_window(loc)
  if loc[0..3] == 'url=' or loc[0..5] == 'title='
    @browser.window(parse_location(loc)).use
  else
    # assume loc is an integer

    # since Robot Framework sends all args as text, the above check for

    # "url=" and "title=" is the best we can do to ensure argument correctness

    loc = loc.to_i
    # the number of the window

    # user-facing numbers are 1-based, internal we use 0-based because @browser.windows

    # is a Ruby array, so minus 1

    @window_id = loc - 1
    if @window_id == -1
      # either the user has been too smart for his/her own good and thinks the windows are 0-based,

      # or they've entered text that doesn't match 'url=' or 'title=', in which case

      # the above loc.to_i will make loc equal 0

      raise(ArgumentError, "You must provide the url or title of the window in the format 'url=' or 'title=', or you must provide the number of the window, starting with 1 for the first window opened.")
    end
    # this will throw its own error if the index is out of range

    @browser.windows[loc].use
  end
end

#url_should_be(url) ⇒ Object

Verify that the current URL matches a given string

Parameters:

  • url (String) —

    the URL to match against

Raises:



303
304
305
306
 
# File 'lib/watir_robot/keywords/browser.rb', line 303

def url_should_be(url)
  raise(Exception::UrlMatchError, "The URL #{@browser.url} is not correct; it should be #{url}") unless
    @browser.url == url
end

#url_should_contain(text) ⇒ Object

Verify that URL contains certain text

Parameters:

  • text (String) —

    the text which should appear in the URL

Raises:



313
314
315
316
 
# File 'lib/watir_robot/keywords/browser.rb', line 313

def url_should_contain(text)
  raise(Exception::UrlMatchError, "The URL #{@browser.url} is not correct; it should contain #{text}") unless
    @browser.url.include?(text)
end