Merge pull request #247 from seleniumbase/remote-desired-capabilities

Remote desired capabilities

Author: mdmintz

examples/capabilities/ReadMe.md

@@ -0,0 +1,16 @@
+### Using Desired Capabilities
+
+You can specify browser desired capabilities for webdriver when running SeleniumBase tests on a remote SeleniumGrid server such as [BrowserStack](https://www.browserstack.com/automate/capabilities), [Sauce Labs](https://wiki.saucelabs.com/display/DOCS/Platform+Configurator#/), or [TestingBot](https://testingbot.com/support/other/test-options).
+
+A sample run command may look like this: (When run from the ``SeleniumBase/examples/`` folder):
+
+```bash
+pytest my_first_test.py --browser=remote --server=username:[email protected] --port=80 --cap_file=capabilities/sample_cap_file_BS.py
+```
+
+A regex parser was built into SeleniumBase to capture all lines from the specified desired capabilities file in the following formats:
+``'KEY': 'VALUE'``
+``caps['KEY'] = "VALUE"``
+(Each pair must be on a separate line. You can interchange single and double quotes.)
+
+You can also swap ``--browser=remote`` with an actual browser, eg ``--browser=chrome``, which will combine the default SeleniumBase desired capabilities with those that were specified in the capabilities file when using ``--cap_file=FILE.py``. (For example, you'll need default SeleniumBase desired capabilities when using a proxy server, which is not the same as the Selenium Grid server.)

examples/capabilities/sample_cap_file_BS.py

@@ -0,0 +1,11 @@
+# Desired capabilities example file for BrowserStack
+# Generate from https://www.browserstack.com/automate/capabilities
+desired_cap = {
+    'os': 'OS X',
+    'os_version': 'Sierra',
+    'browser': 'Chrome',
+    'browser_version': '70.0',
+    'browserstack.local': 'false',
+    'browserstack.selenium_version': '3.14.0',
+    'browserstack.chrome.driver': '2.43'
+}

examples/capabilities/sample_cap_file_SL.py

@@ -0,0 +1,6 @@
+# Desired capabilities example file for Sauce Labs
+# Generate from https://wiki.saucelabs.com/display/DOCS/Platform+Configurator#/
+caps = {}
+caps['browserName'] = "chrome"
+caps['platform'] = "macOS 10.12"
+caps['version'] = "70.0"

requirements.txt

@@ -7,7 +7,7 @@ ipdb
 chardet
 unittest2
 selenium==3.141.0
-requests==2.20.0
+requests==2.20.1
 urllib3==1.24.1
 pytest>=4.0.0
 pytest-cov>=2.6.0

seleniumbase/core/browser_launcher.py

@@ -11,6 +11,7 @@
 from seleniumbase.config import proxy_list
 from seleniumbase.core import download_helper
 from seleniumbase.core import proxy_helper
+from seleniumbase.core import capabilities_parser
 from seleniumbase.fixtures import constants
 from seleniumbase.fixtures import page_utils
 from seleniumbase import drivers  # webdriver storage folder for SeleniumBase
@@ -187,7 +188,8 @@ def validate_proxy_string(proxy_string):
 
 
 def get_driver(browser_name, headless=False, use_grid=False,
-               servername='localhost', port=4444, proxy_string=None):
+               servername='localhost', port=4444, proxy_string=None,
+               cap_file=None):
     proxy_auth = False
     proxy_user = None
     proxy_pass = None
@@ -216,7 +218,7 @@ def get_driver(browser_name, headless=False, use_grid=False,
     if use_grid:
         return get_remote_driver(
             browser_name, headless, servername, port, proxy_string, proxy_auth,
-            proxy_user, proxy_pass)
+            proxy_user, proxy_pass, cap_file)
     else:
         return get_local_driver(
             browser_name, headless, proxy_string, proxy_auth,
@@ -225,20 +227,31 @@ def get_driver(browser_name, headless=False, use_grid=False,
 
 def get_remote_driver(
         browser_name, headless, servername, port, proxy_string, proxy_auth,
-        proxy_user, proxy_pass):
+        proxy_user, proxy_pass, cap_file):
     downloads_path = download_helper.get_downloads_folder()
     download_helper.reset_downloads_folder()
     address = "http://%s:%s/wd/hub" % (servername, port)
+    desired_caps = {}
+    if cap_file:
+        desired_caps = capabilities_parser.get_desired_capabilities(cap_file)
 
     if browser_name == constants.Browser.GOOGLE_CHROME:
         chrome_options = _set_chrome_options(
             downloads_path, proxy_string, proxy_auth,
             proxy_user, proxy_pass)
         if headless:
-            chrome_options.add_argument("--headless")
+            if not proxy_auth:
+                # Headless Chrome doesn't support extensions, which are
+                # required when using a proxy server that has authentication.
+                # Instead, base_case.py will use PyVirtualDisplay when not
+                # using Chrome's built-in headless mode. See link for details:
+                # https://bugs.chromium.org/p/chromium/issues/detail?id=706008
+                chrome_options.add_argument("--headless")
             chrome_options.add_argument("--disable-gpu")
             chrome_options.add_argument("--no-sandbox")
         capabilities = chrome_options.to_capabilities()
+        for key in desired_caps.keys():
+            capabilities[key] = desired_caps[key]
         return webdriver.Remote(
             command_executor=address,
             desired_capabilities=capabilities)
@@ -251,6 +264,8 @@ def get_remote_driver(
             if headless:
                 firefox_capabilities['moz:firefoxOptions'] = (
                     {'args': ['-headless']})
+            for key in desired_caps.keys():
+                firefox_capabilities[key] = desired_caps[key]
             capabilities = firefox_capabilities
             address = "http://%s:%s/wd/hub" % (servername, port)
             return webdriver.Remote(
@@ -265,39 +280,76 @@ def get_remote_driver(
             if headless:
                 firefox_capabilities['moz:firefoxOptions'] = (
                     {'args': ['-headless']})
+            for key in desired_caps.keys():
+                firefox_capabilities[key] = desired_caps[key]
             capabilities = firefox_capabilities
             return webdriver.Remote(
                 command_executor=address,
                 desired_capabilities=capabilities,
                 browser_profile=profile)
     elif browser_name == constants.Browser.INTERNET_EXPLORER:
+        capabilities = webdriver.DesiredCapabilities.INTERNETEXPLORER
+        for key in desired_caps.keys():
+            capabilities[key] = desired_caps[key]
         return webdriver.Remote(
             command_executor=address,
-            desired_capabilities=(
-                webdriver.DesiredCapabilities.INTERNETEXPLORER))
+            desired_capabilities=capabilities)
     elif browser_name == constants.Browser.EDGE:
+        capabilities = webdriver.DesiredCapabilities.EDGE
+        for key in desired_caps.keys():
+            capabilities[key] = desired_caps[key]
         return webdriver.Remote(
             command_executor=address,
-            desired_capabilities=(
-                webdriver.DesiredCapabilities.EDGE))
+            desired_capabilities=capabilities)
     elif browser_name == constants.Browser.SAFARI:
+        capabilities = webdriver.DesiredCapabilities.SAFARI
+        for key in desired_caps.keys():
+            capabilities[key] = desired_caps[key]
         return webdriver.Remote(
             command_executor=address,
-            desired_capabilities=(
-                webdriver.DesiredCapabilities.SAFARI))
+            desired_capabilities=capabilities)
     elif browser_name == constants.Browser.OPERA:
+        capabilities = webdriver.DesiredCapabilities.OPERA
+        for key in desired_caps.keys():
+            capabilities[key] = desired_caps[key]
         return webdriver.Remote(
             command_executor=address,
-            desired_capabilities=(
-                webdriver.DesiredCapabilities.OPERA))
+            desired_capabilities=capabilities)
     elif browser_name == constants.Browser.PHANTOM_JS:
+        capabilities = webdriver.DesiredCapabilities.PHANTOMJS
+        for key in desired_caps.keys():
+            capabilities[key] = desired_caps[key]
         with warnings.catch_warnings():
             # Ignore "PhantomJS has been deprecated" UserWarning
             warnings.simplefilter("ignore", category=UserWarning)
             return webdriver.Remote(
                 command_executor=address,
-                desired_capabilities=(
-                    webdriver.DesiredCapabilities.PHANTOMJS))
+                desired_capabilities=capabilities)
+    elif browser_name == constants.Browser.ANDROID:
+        capabilities = webdriver.DesiredCapabilities.ANDROID
+        for key in desired_caps.keys():
+            capabilities[key] = desired_caps[key]
+        return webdriver.Remote(
+            command_executor=address,
+            desired_capabilities=capabilities)
+    elif browser_name == constants.Browser.IPHONE:
+        capabilities = webdriver.DesiredCapabilities.IPHONE
+        for key in desired_caps.keys():
+            capabilities[key] = desired_caps[key]
+        return webdriver.Remote(
+            command_executor=address,
+            desired_capabilities=capabilities)
+    elif browser_name == constants.Browser.IPAD:
+        capabilities = webdriver.DesiredCapabilities.IPAD
+        for key in desired_caps.keys():
+            capabilities[key] = desired_caps[key]
+        return webdriver.Remote(
+            command_executor=address,
+            desired_capabilities=capabilities)
+    elif browser_name == constants.Browser.REMOTE:
+        return webdriver.Remote(
+            command_executor=address,
+            desired_capabilities=desired_caps)
 
 
 def get_local_driver(
@@ -418,3 +470,6 @@ def get_local_driver(
                 return webdriver.Chrome(executable_path=LOCAL_CHROMEDRIVER)
             else:
                 return webdriver.Chrome()
+    else:
+        raise Exception(
+            "%s is not a valid browser option for this system!" % browser_name)

seleniumbase/core/capabilities_parser.py

@@ -0,0 +1,99 @@
+import re
+
+
+def get_desired_capabilities(cap_file):
+    if not cap_file.endswith('.py'):
+        raise Exception("\n\n`%s` is not a Python file!\n\n" % cap_file)
+
+    f = open(cap_file, 'r')
+    all_code = f.read()
+    f.close()
+
+    desired_capabilities = {}
+    num_capabilities = 0
+
+    code_lines = all_code.split('\n')
+    for line in code_lines:
+        if "desired_cap = {" in line:
+            line = line.split("desired_cap = {")[1]
+
+        # 'KEY' : 'VALUE'
+        data = re.match(r"^\s*'([\S\s]+)'\s*:\s*'([\S\s]+)'\s*[,}]?\s*$", line)
+        if data:
+            key = data.group(1)
+            value = data.group(2)
+            desired_capabilities[key] = value
+            num_capabilities += 1
+            continue
+
+        # "KEY" : "VALUE"
+        data = re.match(r'^\s*"([\S\s]+)"\s*:\s*"([\S\s]+)"\s*[,}]?\s*$', line)
+        if data:
+            key = data.group(1)
+            value = data.group(2)
+            desired_capabilities[key] = value
+            num_capabilities += 1
+            continue
+
+        # 'KEY' : "VALUE"
+        data = re.match(
+            r'''^\s*'([\S\s]+)'\s*:\s*"([\S\s]+)"\s*[,}]?\s*$''', line)
+        if data:
+            key = data.group(1)
+            value = data.group(2)
+            desired_capabilities[key] = value
+            num_capabilities += 1
+            continue
+
+        # "KEY" : 'VALUE'
+        data = re.match(
+            r'''^\s*"([\S\s]+)"\s*:\s*'([\S\s]+)'\s*[,}]?\s*$''', line)
+        if data:
+            key = data.group(1)
+            value = data.group(2)
+            desired_capabilities[key] = value
+            num_capabilities += 1
+            continue
+
+        # caps['KEY'] = 'VALUE'
+        data = re.match(r"^\s*caps\['([\S\s]+)'\]\s*=\s*'([\S\s]+)'\s*$", line)
+        if data:
+            key = data.group(1)
+            value = data.group(2)
+            desired_capabilities[key] = value
+            num_capabilities += 1
+            continue
+
+        # caps["KEY"] = "VALUE"
+        data = re.match(r'^\s*caps\["([\S\s]+)"\]\s*=\s*"([\S\s]+)"\s*$', line)
+        if data:
+            key = data.group(1)
+            value = data.group(2)
+            desired_capabilities[key] = value
+            num_capabilities += 1
+            continue
+
+        # caps['KEY'] = "VALUE"
+        data = re.match(
+            r'''^\s*caps\['([\S\s]+)'\]\s*=\s*"([\S\s]+)"\s*$''', line)
+        if data:
+            key = data.group(1)
+            value = data.group(2)
+            desired_capabilities[key] = value
+            num_capabilities += 1
+            continue
+
+        # caps["KEY"] = 'VALUE'
+        data = re.match(
+            r'''^\s*caps\["([\S\s]+)"\]\s*=\s*'([\S\s]+)'\s*$''', line)
+        if data:
+            key = data.group(1)
+            value = data.group(2)
+            desired_capabilities[key] = value
+            num_capabilities += 1
+            continue
+
+    if num_capabilities == 0:
+        raise Exception("Unable to parse desired capabilities file!")
+
+    return desired_capabilities

seleniumbase/fixtures/base_case.py

@@ -2191,7 +2191,8 @@ def save_screenshot(self, name, folder=None):
         return page_actions.save_screenshot(self.driver, name, folder)
 
     def get_new_driver(self, browser=None, headless=None,
-                       servername=None, port=None, proxy=None, switch_to=True):
+                       servername=None, port=None, proxy=None, switch_to=True,
+                       cap_file=None):
         """ This method spins up an extra browser for tests that require
             more than one. The first browser is already provided by tests
             that import base_case.BaseCase from seleniumbase. If parameters
@@ -2204,6 +2205,27 @@ def get_new_driver(self, browser=None, headless=None,
             proxy - if using a proxy server, specify the "host:port" combo here
             switch_to - the option to switch to the new driver (default = True)
         """
+        if self.browser == "remote" and self.servername == "localhost":
+            raise Exception('Cannot use "remote" browser driver on localhost!'
+                            ' Did you mean to connect to a remote Grid server'
+                            ' such as BrowserStack or Sauce Labs? In that'
+                            ' case, you must specify the "server" and "port"'
+                            ' parameters on the command line! '
+                            'Example: '
+                            '--server=user:[email protected] --port=80')
+        browserstack_ref = (
+            'https://browserstack.com/automate/capabilities')
+        sauce_labs_ref = (
+            'https://wiki.saucelabs.com/display/DOCS/Platform+Configurator#/')
+        if self.browser == "remote" and not self.cap_file:
+            raise Exception('Need to specify a desired capabilities file when '
+                            'using "--browser=remote". Add "--cap_file=FILE". '
+                            'File should be in the Python format used by: '
+                            '%s OR '
+                            '%s '
+                            'See SeleniumBase/examples/sample_cap_file_BS.py '
+                            'and SeleniumBase/examples/sample_cap_file_SL.py'
+                            % (browserstack_ref, sauce_labs_ref))
         if browser is None:
             browser = self.browser
         browser_name = browser
@@ -2220,6 +2242,8 @@ def get_new_driver(self, browser=None, headless=None,
         proxy_string = proxy
         if proxy_string is None:
             proxy_string = self.proxy_string
+        if cap_file is None:
+            cap_file = self.cap_file
         valid_browsers = constants.ValidBrowsers.valid_browsers
         if browser_name not in valid_browsers:
             raise Exception("Browser: {%s} is not a valid browser option. "
@@ -2231,7 +2255,8 @@ def get_new_driver(self, browser=None, headless=None,
                                                  use_grid=use_grid,
                                                  servername=servername,
                                                  port=port,
-                                                 proxy_string=proxy_string)
+                                                 proxy_string=proxy_string,
+                                                 cap_file=cap_file)
         self._drivers_list.append(new_driver)
         if switch_to:
             self.driver = new_driver
@@ -2606,6 +2631,7 @@ def setUp(self):
             self.servername = pytest.config.option.servername
             self.port = pytest.config.option.port
             self.proxy_string = pytest.config.option.proxy_string
+            self.cap_file = pytest.config.option.cap_file
             self.database_env = pytest.config.option.database_env
             self.log_path = pytest.config.option.log_path
             self.browser = pytest.config.option.browser
@@ -2676,7 +2702,8 @@ def setUp(self):
                                           servername=self.servername,
                                           port=self.port,
                                           proxy=self.proxy_string,
-                                          switch_to=True)
+                                          switch_to=True,
+                                          cap_file=self.cap_file)
         self._default_driver = self.driver
 
     def __insert_test_result(self, state, err):