Source code for selenium.webdriver.remote.webdriver

# Copyright 2008-2011 WebDriver committers
# Copyright 2008-2011 Google Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""
The WebDriver implementation.
"""
import base64
from command import Command
from webelement import WebElement
from remote_connection import RemoteConnection
from errorhandler import ErrorHandler
from selenium.common.exceptions import WebDriverException
from selenium.common.exceptions import InvalidSelectorException
from selenium.webdriver.common.by import By
from selenium.webdriver.common.alert import Alert
from selenium.webdriver.common.html5.application_cache import ApplicationCache


[docs]class WebDriver(object): """ Controls a browser by sending commands to a remote server. This server is expected to be running the WebDriver wire protocol as defined here: http://code.google.com/p/selenium/wiki/JsonWireProtocol :Attributes: - command_executor - The command.CommandExecutor object used to execute commands. - error_handler - errorhandler.ErrorHandler object used to verify that the server did not return an error. - session_id - The session ID to send with every command. - capabilities - A dictionary of capabilities of the underlying browser for this instance's session. """ def __init__(self, command_executor='http://127.0.0.1:4444/wd/hub', desired_capabilities=None, browser_profile=None): """ Create a new driver that will issue commands using the wire protocol. :Args: - command_executor - Either a command.CommandExecutor object or a string that specifies the URL of a remote server to send commands to. - desired_capabilities - Dictionary holding predefined values for starting a browser - browser_profile - A selenium.webdriver.firefox.firefox_profile.FirefoxProfile object. Only used if Firefox is requested. """ if desired_capabilities is None: raise WebDriverException("Desired Capabilities can't be None") if not isinstance(desired_capabilities, dict): raise WebDriverException("Desired Capabilities must be a dictionary") self.command_executor = command_executor if type(self.command_executor) is str or type(self.command_executor) is unicode: self.command_executor = RemoteConnection(command_executor) self.session_id = None self.capabilities = {} self.error_handler = ErrorHandler() self.start_client() self.start_session(desired_capabilities, browser_profile) @property
[docs] def name(self): """Returns the name of the underlying browser for this instance. :Usage: - driver.name """ if 'browserName' in self.capabilities: return self.capabilities['browserName'] else: raise KeyError('browserName not specified in session capabilities')
[docs] def start_client(self): """ Called before starting a new session. This method may be overridden to define custom startup behavior. """ pass
[docs] def stop_client(self): """ Called after executing a quit command. This method may be overridden to define custom shutdown behavior. """ pass
[docs] def start_session(self, desired_capabilities, browser_profile=None): """ Creates a new session with the desired capabilities. :Args: - browser_name - The name of the browser to request. - version - Which browser version to request. - platform - Which platform to request the browser on. - javascript_enabled - Whether the new session should support JavaScript. - browser_profile - A selenium.webdriver.firefox.firefox_profile.FirefoxProfile object. Only used if Firefox is requested. """ if browser_profile: desired_capabilities['firefox_profile'] = browser_profile.encoded response = self.execute(Command.NEW_SESSION, { 'desiredCapabilities': desired_capabilities, }) self.session_id = response['sessionId'] self.capabilities = response['value']
def _wrap_value(self, value): if isinstance(value, dict): converted = {} for key, val in value.items(): converted[key] = self._wrap_value(val) return converted elif isinstance(value, WebElement): return {'ELEMENT': value.id} elif isinstance(value, list): return list(self._wrap_value(item) for item in value) else: return value
[docs] def create_web_element(self, element_id): """ Creates a web element with the specified element_id. """ return WebElement(self, element_id)
def _unwrap_value(self, value): if isinstance(value, dict) and 'ELEMENT' in value: return self.create_web_element(value['ELEMENT']) elif isinstance(value, list): return list(self._unwrap_value(item) for item in value) else: return value
[docs] def execute(self, driver_command, params=None): """ Sends a command to be executed by a command.CommandExecutor. :Args: - driver_command: The name of the command to execute as a string. - params: A dictionary of named parameters to send with the command. :Returns: The command's JSON response loaded into a dictionary object. """ if not params: params = {'sessionId': self.session_id} elif 'sessionId' not in params: params['sessionId'] = self.session_id params = self._wrap_value(params) response = self.command_executor.execute(driver_command, params) if response: self.error_handler.check_response(response) response['value'] = self._unwrap_value( response.get('value', None)) return response # If the server doesn't send a response, assume the command was # a success return {'success': 0, 'value': None, 'sessionId': self.session_id}
[docs] def get(self, url): """ Loads a web page in the current browser session. """ self.execute(Command.GET, {'url': url})
@property
[docs] def title(self): """Returns the title of the current page. :Usage: driver.title """ resp = self.execute(Command.GET_TITLE) return resp['value'] if resp['value'] is not None else ""
[docs] def find_element_by_id(self, id_): """Finds an element by id. :Args: - id\_ - The id of the element to be found. :Usage: driver.find_element_by_id('foo') """ return self.find_element(by=By.ID, value=id_)
[docs] def find_elements_by_id(self, id_): """ Finds multiple elements by id. :Args: - id\_ - The id of the elements to be found. :Usage: driver.find_element_by_id('foo') """ return self.find_elements(by=By.ID, value=id_)
[docs] def find_element_by_xpath(self, xpath): """ Finds an element by xpath. :Args: - xpath - The xpath locator of the element to find. :Usage: driver.find_element_by_xpath('//div/td[1]') """ return self.find_element(by=By.XPATH, value=xpath)
[docs] def find_elements_by_xpath(self, xpath): """ Finds multiple elements by xpath. :Args: - xpath - The xpath locator of the elements to be found. :Usage: driver.find_elements_by_xpath("//div[contains(@class, 'foo')]") """ return self.find_elements(by=By.XPATH, value=xpath)
[docs] def find_element_by_name(self, name): """ Finds an element by name. :Args: - name: The name of the element to find. :Usage: driver.find_element_by_name('foo') """ return self.find_element(by=By.NAME, value=name)
[docs] def find_elements_by_name(self, name): """ Finds elements by name. :Args: - name: The name of the elements to find. :Usage: driver.find_elements_by_name('foo') """ return self.find_elements(by=By.NAME, value=name)
[docs] def find_element_by_tag_name(self, name): """ Finds an element by tag name. :Args: - name: The tag name of the element to find. :Usage: driver.find_element_by_tag_name('foo') """ return self.find_element(by=By.TAG_NAME, value=name)
[docs] def find_elements_by_tag_name(self, name): """ Finds elements by tag name. :Args: - name: The tag name the use when finding elements. :Usage: driver.find_elements_by_tag_name('foo') """ return self.find_elements(by=By.TAG_NAME, value=name)
[docs] def find_element_by_class_name(self, name): """ Finds an element by class name. :Args: - name: The class name of the element to find. :Usage: driver.find_element_by_class_name('foo') """ return self.find_element(by=By.CLASS_NAME, value=name)
[docs] def find_elements_by_class_name(self, name): """ Finds elements by class name. :Args: - name: The class name of the elements to find. :Usage: driver.find_elements_by_class_name('foo') """ return self.find_elements(by=By.CLASS_NAME, value=name)
[docs] def find_element_by_css_selector(self, css_selector): """ Finds an element by css selector. :Args: - css_selector: The css selector to use when finding elements. :Usage: driver.find_element_by_css_selector('#foo') """ return self.find_element(by=By.CSS_SELECTOR, value=css_selector)
[docs] def find_elements_by_css_selector(self, css_selector): """ Finds elements by css selector. :Args: - css_selector: The css selector to use when finding elements. :Usage: driver.find_element_by_css_selector('#foo') """ return self.find_elements(by=By.CSS_SELECTOR, value=css_selector)
[docs] def execute_script(self, script, *args): """ Synchronously Executes JavaScript in the current window/frame. :Args: - script: The JavaScript to execute. - \*args: Any applicable arguments for your JavaScript. :Usage: driver.execute_script('document.title') """ if len(args) == 1: converted_args = args[0] else: converted_args = list(args) converted_args = list(args) return self.execute(Command.EXECUTE_SCRIPT, {'script': script, 'args':converted_args})['value']
[docs] def execute_async_script(self, script, *args): """ Asynchronously Executes JavaScript in the current window/frame. :Args: - script: The JavaScript to execute. - \*args: Any applicable arguments for your JavaScript. :Usage: driver.execute_async_script('document.title') """ if len(args) == 1: converted_args = args[0] else: converted_args = list(args) converted_args = list(args) return self.execute(Command.EXECUTE_ASYNC_SCRIPT, {'script': script, 'args':converted_args})['value']
@property
[docs] def current_url(self): """ Gets the URL of the current page. :Usage: driver.current_url """ return self.execute(Command.GET_CURRENT_URL)['value']
@property
[docs] def page_source(self): """ Gets the source of the current page. :Usage: driver.page_source """ return self.execute(Command.GET_PAGE_SOURCE)['value']
[docs] def close(self): """ Closes the current window. :Usage: driver.close() """ self.execute(Command.CLOSE)
[docs] def quit(self): """ Quits the driver and closes every associated window. :Usage: driver.quit() """ try: self.execute(Command.QUIT) finally: self.stop_client()
@property
[docs] def current_window_handle(self): """ Returns the handle of the current window. :Usage: driver.current_window_handle """ return self.execute(Command.GET_CURRENT_WINDOW_HANDLE)['value']
@property
[docs] def window_handles(self): """ Returns the handles of all windows within the current session. :Usage: driver.window_handles """ return self.execute(Command.GET_WINDOW_HANDLES)['value']
[docs] def maximize_window(self): """ Maximizes the current window that webdriver is using """ self.execute(Command.MAXIMIZE_WINDOW, {"windowHandle": "current"}) #Target Locators
[docs] def switch_to_active_element(self): """ Returns the element with focus, or BODY if nothing has focus. :Usage: driver.switch_to_active_element() """ return self.execute(Command.GET_ACTIVE_ELEMENT)['value']
[docs] def switch_to_window(self, window_name): """ Switches focus to the specified window. :Args: - window_name: The name or window handle of the window to switch to. :Usage: driver.switch_to_window('main') """ self.execute(Command.SWITCH_TO_WINDOW, {'name': window_name})
[docs] def switch_to_frame(self, frame_reference): """ Switches focus to the specified frame, by index, name, or webelement. :Args: - frame_reference: The name of the window to switch to, an integer representing the index, or a webelement that is an (i)frame to switch to. :Usage: driver.switch_to_frame('frame_name') driver.switch_to_frame(1) driver.switch_to_frame(driver.find_elements_by_tag_name("iframe")[0]) """ self.execute(Command.SWITCH_TO_FRAME, {'id': frame_reference})
[docs] def switch_to_default_content(self): """ Switch focus to the default frame. :Usage: driver.switch_to_default_content() """ self.execute(Command.SWITCH_TO_FRAME, {'id': None})
[docs] def switch_to_alert(self): """ Switches focus to an alert on the page. :Usage: driver.switch_to_alert() """ return Alert(self) #Navigation
[docs] def back(self): """ Goes one step backward in the browser history. :Usage: driver.back() """ self.execute(Command.GO_BACK)
[docs] def forward(self): """ Goes one step forward in the browser history. :Usage: driver.forward() """ self.execute(Command.GO_FORWARD)
[docs] def refresh(self): """ Refreshes the current page. :Usage: driver.refresh() """ self.execute(Command.REFRESH) # Options
[docs] def get_cookies(self): """ Returns a set of dictionaries, corresponding to cookies visible in the current session. :Usage: driver.get_cookies() """ return self.execute(Command.GET_ALL_COOKIES)['value']
[docs] def delete_all_cookies(self): """ Delete all cookies in the scope of the session. :Usage: driver.delete_all_cookies() """ self.execute(Command.DELETE_ALL_COOKIES)
[docs] def implicitly_wait(self, time_to_wait): """ Sets a sticky timeout to implicitly wait for an element to be found, or a command to complete. This method only needs to be called one time per session. To set the timeout for calls to execute_async_script, see set_script_timeout. :Args: - time_to_wait: Amount of time to wait (in seconds) :Usage: driver.implicitly_wait(30) """ self.execute(Command.IMPLICIT_WAIT, {'ms': float(time_to_wait) * 1000})
[docs] def set_script_timeout(self, time_to_wait): """ Set the amount of time that the script should wait during an execute_async_script call before throwing an error. :Args: - time_to_wait: The amount of time to wait :Usage: driver.set_script_timeout(30) """ self.execute(Command.SET_SCRIPT_TIMEOUT, {'ms': float(time_to_wait) * 1000})
[docs] def set_page_load_timeout(self, time_to_wait): """ Set the amount of time to wait for a page load to complete before throwing an error. :Args: - time_to_wait: The amount of time to wait :Usage: driver.set_page_load_timeout(30) """ self.execute(Command.SET_TIMEOUTS, {'ms': float(time_to_wait) * 1000, 'type':'page load'})
[docs] def find_element(self, by=By.ID, value=None): """ 'Private' method used by the find_element_by_* methods. :Usage: Use the corresponding find_element_by_* instead of this. """ if isinstance(by, tuple) or isinstance(value, int) or value==None: raise InvalidSelectorException("Invalid locator values passed in") return self.execute(Command.FIND_ELEMENT, {'using': by, 'value': value})['value']
[docs] def find_elements(self, by=By.ID, value=None): """ 'Private' method used by the find_elements_by_* methods. :Usage: Use the corresponding find_elements_by_* instead of this. """ if isinstance(by, tuple) or isinstance(value, int) or value==None: raise InvalidSelectorException("Invalid locator values passed in") return self.execute(Command.FIND_ELEMENTS, {'using': by, 'value': value})['value']
@property
[docs] def desired_capabilities(self): """ returns the drivers current desired capabilities being used """ return self.capabilities
[docs] def get_screenshot_as_file(self, filename): """ Gets the screenshot of the current window. Returns False if there is any IOError, else returns True. Use full paths in your filename. :Args: - filename: The full path you wish to save your screenshot to. :Usage: driver.get_screenshot_as_file('/Screenshots/foo.png') """ png = self.execute(Command.SCREENSHOT)['value'] try: with open(filename, 'wb') as f: f.write(base64.decodestring(png)) except IOError: return False del png return True
[docs] def get_screenshot_as_base64(self): """ Gets the screenshot of the current window as a base64 encoded string which is useful in embedded images in HTML. :Usage: driver.get_screenshot_as_base64() """ return self.execute(Command.SCREENSHOT)['value']
[docs] def set_window_size(self, width, height, windowHandle='current'): """ Sets the width and height of the current window. (window.resizeTo) :Args: - width: the width in pixels to set the window to - height: the height in pixels to set the window to :Usage: driver.set_window_size(800,600) """ self.execute(Command.SET_WINDOW_SIZE, {'width': width, 'height': height, 'windowHandle': windowHandle})
[docs] def get_window_size(self, windowHandle='current'): """ Gets the width and height of the current window. :Usage: driver.get_window_size() """ return self.execute(Command.GET_WINDOW_SIZE, {'windowHandle': windowHandle})['value']
[docs] def set_window_position(self, x, y, windowHandle='current'): """ Sets the x,y position of the current window. (window.moveTo) :Args: - x: the x-coordinate in pixels to set the window position - y: the y-coordinate in pixels to set the window position :Usage: driver.set_window_position(0,0) """ self.execute(Command.SET_WINDOW_POSITION, {'x': x, 'y': y, 'windowHandle': windowHandle})
[docs] def get_window_position(self, windowHandle='current'): """ Gets the x,y position of the current window. :Usage: driver.get_window_position() """ return self.execute(Command.GET_WINDOW_POSITION, {'windowHandle': windowHandle})['value']
@property def orientation(self): """ Gets the current orientation of the device :Usage: orientation = driver.orientation """ return self.execute(Command.GET_SCREEN_ORIENTATION)['value'] @orientation.setter
[docs] def orientation(self, value): """ Sets the current orientation of the device :Args: - value: orientation to set it to. :Usage: driver.orientation = 'landscape' """ allowed_values = ['LANDSCAPE', 'PORTRAIT'] if value.upper() in allowed_values: self.execute(Command.SET_SCREEN_ORIENTATION, {'orientation': value})['value'] else: raise WebDriverException("You can only set the orientation to 'LANDSCAPE' and 'PORTRAIT'")
[docs] def is_online(self): """ Returns a boolean if the browser is online or offline""" return self.execute(Command.IS_BROWSER_ONLINE)['value']
@property
[docs] def application_cache(self): """ Returns a ApplicationCache Object to interact with the browser app cache""" return ApplicationCache(self)