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



113
114
115
 
# File 'lib/watir_robot/keywords/browser.rb', line 113

def close_browser
  @browser.close
end

#close_other_window ⇒ Object

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



204
205
206
207
208
209
210
211
 
# File 'lib/watir_robot/keywords/browser.rb', line 204

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



226
227
228
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
 
# File 'lib/watir_robot/keywords/browser.rb', line 226

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



97
98
99
 
# File 'lib/watir_robot/keywords/browser.rb', line 97

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



106
107
108
 
# File 'lib/watir_robot/keywords/browser.rb', line 106

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



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

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



90
91
92
 
# File 'lib/watir_robot/keywords/browser.rb', line 90

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

#get_url ⇒ String

Get current URL

Returns:

  • (String) —

    URL of the current page



41
42
43
 
# File 'lib/watir_robot/keywords/browser.rb', line 41

def get_url
  @browser.url
end

#get_window_count ⇒ Object

Return the number of open windows



289
290
291
 
# File 'lib/watir_robot/keywords/browser.rb', line 289

def get_window_count
  return @browser.windows.count
end

#go_back ⇒ Object

Go back in browsing history



57
58
59
 
# File 'lib/watir_robot/keywords/browser.rb', line 57

def go_back
  @browser.back
end

#go_forward ⇒ Object

Go forward in browsing history



64
65
66
 
# File 'lib/watir_robot/keywords/browser.rb', line 64

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



50
51
52
 
# File 'lib/watir_robot/keywords/browser.rb', line 50

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

#maximize_browser_window ⇒ Object

Maximize browser window (uses JavaScript)



120
121
122
123
124
125
126
 
# File 'lib/watir_robot/keywords/browser.rb', line 120

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
 
# File 'lib/watir_robot/keywords/browser.rb', line 16

def open_browser(browser = 'firefox')
  @browser = Watir::Browser.new browser.to_sym
  @driver = @browser.driver
  @window_id = 0
  return @browser
end

#refresh ⇒ Object

Refresh the current page



71
72
73
 
# File 'lib/watir_robot/keywords/browser.rb', line 71

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



30
31
32
33
34
 
# File 'lib/watir_robot/keywords/browser.rb', line 30

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)



175
176
177
178
179
180
181
182
183
 
# File 'lib/watir_robot/keywords/browser.rb', line 175

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



131
132
133
134
135
136
137
138
139
 
# File 'lib/watir_robot/keywords/browser.rb', line 131

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)



191
192
193
194
195
196
197
198
199
 
# File 'lib/watir_robot/keywords/browser.rb', line 191

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



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

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:



300
301
302
303
 
# File 'lib/watir_robot/keywords/browser.rb', line 300

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:



310
311
312
313
 
# File 'lib/watir_robot/keywords/browser.rb', line 310

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