Merge pull request #543 from seleniumbase/cap-string-parameter

Add option to set capabilities with --cap-string=STRING

Author: mdmintz

README.md

@@ -211,6 +211,7 @@ SeleniumBase provides additional Pytest command-line options for tests:
 ```bash
 --browser=BROWSER  # (The web browser to use.)
 --cap-file=FILE  # (The web browser's desired capabilities to use.)
+--cap-string=STRING  # (The web browser's desired capabilities to use.)
 --settings-file=FILE  # (Overrides SeleniumBase settings.py values.)
 --env=ENV  # (Set a test environment. Use "self.env" to use this in tests.)
 --data=DATA  # (Extra data to pass to tests. Use "self.data" in tests.)

examples/capabilities/ReadMe.md

@@ -51,3 +51,16 @@ A regex parser was built into SeleniumBase to capture all lines from the specifi
 (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``. Capabilities will override other parameters, so if you set the browser to one thing and the capabilities browser to another, SeleniumBase will use the capabilities browser as the browser. You'll need default SeleniumBase desired capabilities when using a proxy server (not the same as a Selenium Grid server), when downloading files to a desired folder, for disabling some warnings on Chrome, for overriding a website's Content Security Policy on Firefox, and for other reasons.
+
+You can also set browser desired capabilities from a command line string:
+Example:
+```bash
+pytest test_swag_labs.py --cap-string='{"browserName":"chrome","name":"test1"}' --server="127.0.0.1" --browser=remote
+```
+(Enclose cap-string in single quotes. Enclose parameter keys in double quotes.)
+
+If using a local Selenium Grid with SeleniumBase, make sure to start up the Grid Hub and nodes first:
+```bash
+seleniumbase grid-hub start
+seleniumbase grid-node start
+```

examples/raw_parameter_script.py

@@ -72,6 +72,7 @@
     sb.highlights = None
     sb.check_js = False
     sb.cap_file = None
+    sb.cap_string = None
 
     sb.setUp()
     try:

help_docs/customizing_test_runs.md

@@ -84,6 +84,7 @@ SeleniumBase provides additional Pytest command-line options for tests:
 ```bash
 --browser=BROWSER  # (The web browser to use.)
 --cap-file=FILE  # (The web browser's desired capabilities to use.)
+--cap-string=STRING  # (The web browser's desired capabilities to use.)
 --settings-file=FILE  # (Overrides SeleniumBase settings.py values.)
 --env=ENV  # (Set a test environment. Use "self.env" to use this in tests.)
 --data=DATA  # (Extra data to pass to tests. Use "self.data" in tests.)

seleniumbase/core/browser_launcher.py

@@ -1,3 +1,4 @@
+import json
 import logging
 import os
 import random
@@ -345,8 +346,9 @@ def validate_proxy_string(proxy_string):
 
 def get_driver(browser_name, headless=False, use_grid=False,
                servername='localhost', port=4444, proxy_string=None,
-               user_agent=None, cap_file=None, disable_csp=None,
-               enable_sync=None, no_sandbox=None, disable_gpu=None,
+               user_agent=None, cap_file=None, cap_string=None,
+               disable_csp=None, enable_sync=None,
+               no_sandbox=None, disable_gpu=None,
                incognito=None, guest_mode=None, devtools=None,
                user_data_dir=None, extension_zip=None, extension_dir=None,
                mobile_emulator=False, device_width=None,
@@ -384,8 +386,8 @@ def get_driver(browser_name, headless=False, use_grid=False,
         return get_remote_driver(
             browser_name, headless, servername, port,
             proxy_string, proxy_auth, proxy_user, proxy_pass, user_agent,
-            cap_file, disable_csp, enable_sync, no_sandbox, disable_gpu,
-            incognito, guest_mode, devtools,
+            cap_file, cap_string, disable_csp, enable_sync,
+            no_sandbox, disable_gpu, incognito, guest_mode, devtools,
             user_data_dir, extension_zip, extension_dir,
             mobile_emulator, device_width, device_height, device_pixel_ratio)
     else:
@@ -400,17 +402,30 @@ 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, user_agent, cap_file, disable_csp,
-        enable_sync, no_sandbox, disable_gpu,
+        proxy_user, proxy_pass, user_agent, cap_file, cap_string,
+        disable_csp, enable_sync, no_sandbox, disable_gpu,
         incognito, guest_mode, devtools,
         user_data_dir, extension_zip, extension_dir,
         mobile_emulator, device_width, device_height, device_pixel_ratio):
     downloads_path = download_helper.get_downloads_folder()
     download_helper.reset_downloads_folder()
     address = "http://%s:%s/wd/hub" % (servername, port)
     desired_caps = {}
+    extra_caps = {}
     if cap_file:
         desired_caps = capabilities_parser.get_desired_capabilities(cap_file)
+    if cap_string:
+        try:
+            extra_caps = json.loads(cap_string)
+        except Exception as e:
+            p1 = "Invalid input format for --cap-string:\n  %s" % e
+            p2 = "The --cap-string input was: %s" % cap_string
+            p3 = "Enclose cap-string in single quotes; keys in double quotes."
+            p4 = ("""Here's an example of correct cap-string usage:\n  """
+                  """--cap-string='{"browserName":"chrome","name":"test1"}'""")
+            raise Exception("%s\n%s\n%s\n%s" % (p1, p2, p3, p4))
+        for cap_key in extra_caps.keys():
+            desired_caps[cap_key] = extra_caps[cap_key]
     if browser_name == constants.Browser.GOOGLE_CHROME:
         chrome_options = _set_chrome_options(
             downloads_path, headless,

seleniumbase/fixtures/base_case.py

@@ -1521,8 +1521,9 @@ def switch_to_default_window(self):
 
     def get_new_driver(self, browser=None, headless=None,
                        servername=None, port=None, proxy=None, agent=None,
-                       switch_to=True, cap_file=None, disable_csp=None,
-                       enable_sync=None, no_sandbox=None, disable_gpu=None,
+                       switch_to=True, cap_file=None, cap_string=None,
+                       disable_csp=None, enable_sync=None,
+                       no_sandbox=None, disable_gpu=None,
                        incognito=None, guest_mode=None, devtools=None,
                        user_data_dir=None, extension_zip=None,
                        extension_dir=None, is_mobile=False,
@@ -1539,6 +1540,7 @@ 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)
             cap_file - the file containing desired capabilities for the browser
+            cap_string - the string with desired capabilities for the browser
             disable_csp - an option to disable Chrome's Content Security Policy
             enable_sync - the option to enable the Chrome Sync feature (Chrome)
             no_sandbox - the option to enable the "No-Sandbox" feature (Chrome)
@@ -1566,7 +1568,7 @@ def get_new_driver(self, browser=None, headless=None,
             '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:
+        if self.browser == "remote" and not (self.cap_file or self.cap_string):
             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: '
@@ -1619,6 +1621,8 @@ def get_new_driver(self, browser=None, headless=None,
         #    disable_csp = True
         if cap_file is None:
             cap_file = self.cap_file
+        if cap_string is None:
+            cap_string = self.cap_string
         if is_mobile is None:
             is_mobile = False
         if d_width is None:
@@ -1641,6 +1645,7 @@ def get_new_driver(self, browser=None, headless=None,
                                                  proxy_string=proxy_string,
                                                  user_agent=user_agent,
                                                  cap_file=cap_file,
+                                                 cap_string=cap_string,
                                                  disable_csp=disable_csp,
                                                  enable_sync=enable_sync,
                                                  no_sandbox=no_sandbox,
@@ -4530,6 +4535,7 @@ def setUp(self, masterqa_mode=False):
             self.mobile_emulator = sb_config.mobile_emulator
             self.device_metrics = sb_config.device_metrics
             self.cap_file = sb_config.cap_file
+            self.cap_string = sb_config.cap_string
             self.settings_file = sb_config.settings_file
             self.database_env = sb_config.database_env
             self.message_duration = sb_config.message_duration
@@ -4693,6 +4699,7 @@ def setUp(self, masterqa_mode=False):
                                               agent=self.user_agent,
                                               switch_to=True,
                                               cap_file=self.cap_file,
+                                              cap_string=self.cap_string,
                                               disable_csp=self.disable_csp,
                                               enable_sync=self.enable_sync,
                                               no_sandbox=self.no_sandbox,

seleniumbase/plugins/pytest_plugin.py

@@ -14,6 +14,7 @@ def pytest_addoption(parser):
     This parser plugin includes the following command-line options for pytest:
     --browser=BROWSER  (The web browser to use.)
     --cap-file=FILE  (The web browser's desired capabilities to use.)
+    --cap-string=STRING  (The web browser's desired capabilities to use.)
     --settings-file=FILE  (Overrides SeleniumBase settings.py values.)
     --env=ENV  (Set a test environment. Use "self.env" to use this in tests.)
     --data=DATA  (Extra data to pass to tests. Use "self.data" in tests.)
@@ -91,13 +92,24 @@ def pytest_addoption(parser):
                      dest='cap_file',
                      default=None,
                      help="""The file that stores browser desired capabilities
-                          for BrowserStack or Sauce Labs web drivers.""")
+                          for BrowserStack, Sauce Labs, and other
+                          remote web drivers to use.""")
+    parser.addoption('--cap_string', '--cap-string',
+                     dest='cap_string',
+                     default=None,
+                     help="""The string that stores browser desired
+                          capabilities for BrowserStack, Sauce Labs,
+                          and other remote web drivers to use.
+                          Enclose cap-string in single quotes.
+                          Enclose parameter keys in double quotes.
+                          Example: --cap-string='{"name":"test1","v":"42"}'""")
     parser.addoption('--settings_file', '--settings-file', '--settings',
                      action='store',
                      dest='settings_file',
                      default=None,
-                     help="""The file that stores key/value pairs for overriding
-                          values in the SeleniumBase settings.py file.""")
+                     help="""The file that stores key/value pairs for
+                          overriding values in the
+                          seleniumbase/config/settings.py file.""")
     parser.addoption('--user_data_dir', '--user-data-dir',
                      dest='user_data_dir',
                      default=None,
@@ -415,6 +427,7 @@ def pytest_configure(config):
     sb_config.port = config.getoption('port')
     sb_config.proxy_string = config.getoption('proxy_string')
     sb_config.cap_file = config.getoption('cap_file')
+    sb_config.cap_string = config.getoption('cap_string')
     sb_config.settings_file = config.getoption('settings_file')
     sb_config.user_data_dir = config.getoption('user_data_dir')
     sb_config.database_env = config.getoption('database_env')

seleniumbase/plugins/selenium_plugin.py

@@ -12,6 +12,7 @@ class SeleniumBrowser(Plugin):
     This parser plugin includes the following command-line options for Nose:
     --browser=BROWSER  (The web browser to use.)
     --cap-file=FILE  (The web browser's desired capabilities to use.)
+    --cap-string=STRING  (The web browser's desired capabilities to use.)
     --user-data-dir=DIR  (Set the Chrome user data directory to use.)
     --server=SERVER  (The server / IP address used by the tests.)
     --port=PORT  (The port that's used by the test server.)
@@ -73,6 +74,16 @@ def options(self, parser, env):
             default=None,
             help="""The file that stores browser desired capabilities
                     for BrowserStack or Sauce Labs web drivers.""")
+        parser.add_option(
+            '--cap_string', '--cap-string',
+            dest='cap_string',
+            default=None,
+            help="""The string that stores browser desired
+                    capabilities for BrowserStack, Sauce Labs,
+                    and other remote web drivers to use.
+                    Enclose cap-string in single quotes.
+                    Enclose parameter keys in double quotes.
+                    Example: --cap-string='{"name":"test1","v":"42"}'""")
         parser.add_option(
             '--user_data_dir', '--user-data-dir',
             action='store',
@@ -326,6 +337,7 @@ def configure(self, options, conf):
     def beforeTest(self, test):
         test.test.browser = self.options.browser
         test.test.cap_file = self.options.cap_file
+        test.test.cap_string = self.options.cap_string
         test.test.headless = self.options.headless
         test.test.headed = self.options.headed
         test.test.start_page = self.options.start_page

setup.py

@@ -45,7 +45,7 @@
 
 setup(
     name='seleniumbase',
-    version='1.37.4',
+    version='1.37.5',
     description='Fast, Easy, and Reliable Browser Automation & Testing.',
     long_description=long_description,
     long_description_content_type='text/markdown',