Merge pull request #440 from seleniumbase/mobile-device-testing

Add mobile device testing to SeleniumBase

Author: mdmintz

README.md

@@ -1,17 +1,14 @@
-[<img src="https://cdn2.hubspot.net/hubfs/100006/images/super_logo_sb8.png" title="SeleniumBase" height="48">](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md)
+[<img src="https://cdn2.hubspot.net/hubfs/100006/images/super_logo_sb4.png" title="SeleniumBase" height="48">](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md)
 
 [<img src="https://img.shields.io/github/release/seleniumbase/SeleniumBase.svg" alt=" " />](https://github.com/seleniumbase/SeleniumBase/releases) [<img src="https://dev.azure.com/seleniumbase/seleniumbase/_apis/build/status/seleniumbase.SeleniumBase?branchName=master" alt=" " />](https://dev.azure.com/seleniumbase/seleniumbase/_build/latest?definitionId=1&branchName=master) [<img src="https://travis-ci.org/seleniumbase/SeleniumBase.svg?branch=master" alt=" " />](https://travis-ci.org/seleniumbase/SeleniumBase) [<img src="https://badges.gitter.im/seleniumbase/SeleniumBase.svg" alt=" " />](https://gitter.im/seleniumbase/SeleniumBase) [<img src="https://img.shields.io/badge/license-MIT-22BBCC.svg" alt=" " />](https://github.com/seleniumbase/SeleniumBase/blob/master/LICENSE) [<img src="https://img.shields.io/github/stars/seleniumbase/seleniumbase.svg" alt=" " />](https://github.com/seleniumbase/SeleniumBase/stargazers)
 
-All-in-one framework for web automation, end-to-end testing, and website tours. SeleniumBase uses pytest for running Python scripts, while using Selenium WebDriver for controlling web browsers.
+All-in-one framework for web automation, end-to-end testing, and website tours. SeleniumBase uses [pytest](https://pytest.org) for running Python scripts, while using [Selenium WebDriver](https://selenium.dev/) for controlling web browsers.
 
-* Contains reliable, smart-waiting code to prevent flaky tests.
-* Simplifies the process of creating UI tests for any website.
-* Includes [Plugins](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/plugins/pytest_plugin.py) for logging [test results and screenshots](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/example_logs/ReadMe.md).
-* Multiplies the abilities of [pytest](https://pytest.org) and [Selenium WebDriver](https://selenium.dev/).
-* Uses versatile [Python methods](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/method_summary.md) and [command-line options](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/customizing_test_runs.md).
+* Helps you build reliable, non-flaky UI tests for any website.
+* Includes flexible [command-line options](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/customizing_test_runs.md) for running tests.
+* Comes with easy-to-use [Python methods](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/method_summary.md) for writing tests.
 * Includes tools for [assisted-QA](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/master_qa/ReadMe.md), [visual testing](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/visual_testing/ReadMe.md), and [web tours](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/tour_examples/ReadMe.md).
-* Integrates with [Selenium Grid](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/utilities/selenium_grid/ReadMe.md), [Katalon Recorder](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/utilities/selenium_ide/ReadMe.md), and [MySQL](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/core/testcase_manager.py).
-* Supports [Azure Pipelines](https://github.com/seleniumbase/SeleniumBase/blob/master/integrations/azure/azure_pipelines/ReadMe.md), [GCP](https://github.com/seleniumbase/SeleniumBase/blob/master/integrations/google_cloud/ReadMe.md), [TravisCI](https://github.com/seleniumbase/SeleniumBase/blob/master/.travis.yml), [Docker](https://github.com/seleniumbase/SeleniumBase/blob/master/integrations/docker/ReadMe.md), and more.
+* Integrates with [Selenium Grid](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/utilities/selenium_grid/ReadMe.md), [Katalon Recorder](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/utilities/selenium_ide/ReadMe.md), and more.
 * To see the full list of SeleniumBase features, [click here](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/features_list.md).
 
 <img src="https://cdn2.hubspot.net/hubfs/100006/images/my_first_test_gif.gif" title="SeleniumBase"><br />
@@ -212,6 +209,8 @@ SeleniumBase provides additional Pytest command-line options for tests:
 --port=PORT  # (The port that's used by the test server.)
 --proxy=SERVER:PORT  # (This is the proxy server:port combo used by tests.)
 --agent=STRING  # (This designates the web browser's User Agent to use.)
+--mobile  # (The option to use the mobile emulator while running tests.)
+--metrics=STRING  # ("CSSWidth,Height,PixelRatio" for mobile emulator tests.)
 --extension-zip=ZIP  # (Load a Chrome Extension .zip file, comma-separated.)
 --extension-dir=DIR  # (Load a Chrome Extension directory, comma-separated.)
 --headless  # (The option to run tests headlessly. The default on Linux OS.)

examples/raw_parameter_script.py

@@ -35,6 +35,8 @@
     sb.data = None
     sb.environment = "test"
     sb.user_agent = None
+    sb.mobile_emulator = False
+    sb.device_metrics = None
     sb.extension_zip = None
     sb.extension_dir = None
     sb.database_env = "test"

help_docs/customizing_test_runs.md

@@ -2,69 +2,74 @@
 
 ## <img src="https://cdn2.hubspot.net/hubfs/100006/images/super_square_logo_3a.png" title="SeleniumBase" height="32"> Customizing test runs
 
-In addition to [settings.py](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/config/settings.py) (which lets you customize SeleniumBase global properties) you can customize test runs from the command line with pytest (or nosetests):
-
-* Choose the browser for tests to use (Default: Chrome)
-* Choose betweeen pytest & nose unittest runners
-* Choose whether to enter Debug Mode on failures
-* Choose additional variables to pass into tests
-* Choose the User-Agent for the browser to use
-* Choose the automation speed (with Demo Mode)
-* Choose whether to run tests multi-threaded
-* Choose whether to rerun failing tests
-* Choose whether to reuse the browser session
-* Choose a Chrome Extension to load
-* Choose a Chrome User Data Directory to use
-* Choose a BrowserStack server to run on
-* Choose a Sauce Labs server to run on
-* Choose a TestingBot server to run on
-* Choose a CrossBrowserTesting server
-* Choose a Selenium Grid to connect to
-* Choose a database to save results to
-* Choose a proxy server to connect to
-
-...and more!
-
-#### **Examples:**
-
-These are run from the **[examples](https://github.com/seleniumbase/SeleniumBase/tree/master/examples)** folder.
-(Chrome is the default browser if not specified.)
+In addition to [settings.py](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/config/settings.py) for customizing global properties, you can customize test runs [from the command-line](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/plugins/pytest_plugin.py).
+
+The following tests can be run from the [examples/](https://github.com/seleniumbase/SeleniumBase/tree/master/examples) folder:
 
 ```bash
+# Run my_first_test.py in Chrome (default browser)
 pytest my_first_test.py
 
+# Run my_first_test.py in Firefox
+pytest my_first_test.py --browser=firefox
+
+# Run tests in Demo Mode to see assertions
 pytest my_first_test.py --demo
 
-pytest my_first_test.py --browser=firefox
+# Run tests in Headless Mode (invisible browser)
+pytest test_suite.py --headless
+
+# Run tests multi-threaded using [n] threads
+pytest test_suite.py -n=4
 
+# Create a pytest html report after tests are done
 pytest test_suite.py --html=report.html
 
-nosetests test_suite.py --report --show-report
+# Enter Debug Mode on failures
+pytest test_fail.py --pdb -s
+
+# Rerun failing tests more times
+pytest test_suite.py --reruns=1
 
-pytest test_suite.py --headless -n=4
+# Pass extra data into tests (retrieve: self.data)
+pytest my_first_test.py --data="ABC,DEF"
 
-pytest test_suite.py --reruns=1 --reruns-delay=1
+# Run tests on a local Selenium Grid
+pytest test_suite.py --server=127.0.0.1
 
+# Run tests on a remote Selenium Grid
 pytest test_suite.py --server=IP_ADDRESS --port=4444
 
-pytest test_suite.py --reuse-session
+# Run tests on a remote Selenium Grid with authentication
+pytest test_suite.py --server=USERNAME:KEY@IP_ADDRESS --port=80
 
-pytest test_fail.py --pdb -s
+# Reuse the same browser session for all tests being run
+pytest test_suite.py --reuse-session
 
+# Run tests through a proxy server
 pytest proxy_test.py --proxy=IP_ADDRESS:PORT
 
+# Run tests through a proxy server with authentication
 pytest proxy_test.py --proxy=USERNAME:PASSWORD@IP_ADDRESS:PORT
 
+# Run tests while setting the web browser's User Agent
 pytest user_agent_test.py --agent="USER-AGENT-STRING"
 
+# Run tests using Chrome's mobile device emulator (default settings)
+pytest test_swag_labs.py --mobile
+
+# Run mobile tests specifying CSS Width, CSS Height, and Pixel-Ratio
+pytest test_swag_labs.py --mobile --metrics="411,731,3"
+
+# Run tests while changing SeleniumBase default settings
 pytest my_first_test.py --settings-file=custom_settings.py
 ```
 
-You can interchange **pytest** with **nosetests**, but using pytest is strongly recommended because developers stopped supporting nosetests. Chrome is the default browser if not specified.
+You can interchange **pytest** with **nosetests** for most things, but using pytest is strongly recommended because developers stopped supporting nosetests. Chrome is the default browser if not specified.
 
 (NOTE: If you're using **pytest** for running tests outside of the SeleniumBase repo, **you'll want a copy of [pytest.ini](https://github.com/seleniumbase/SeleniumBase/blob/master/pytest.ini) at the base of the new folder structure**. If using **nosetests**, the same applies for [setup.cfg](https://github.com/seleniumbase/SeleniumBase/blob/master/setup.cfg).)
 
-An easy way to override seleniumbase/config/settings.py is by using a custom settings file.
+An easy way to override [seleniumbase/config/settings.py](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/config/settings.py) is by using a custom settings file.
 Here's the command-line option to add to tests: (See [examples/custom_settings.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/custom_settings.py))
 ``--settings-file=custom_settings.py``
 (Settings include default timeout values, a two-factor auth key, DB credentials, S3 credentials, and other important settings used by tests.)
@@ -194,6 +199,8 @@ SeleniumBase provides additional Pytest command-line options for tests:
 --port=PORT  # (The port that's used by the test server.)
 --proxy=SERVER:PORT  # (This is the proxy server:port combo used by tests.)
 --agent=STRING  # (This designates the web browser's User Agent to use.)
+--mobile  # (The option to use the mobile emulator while running tests.)
+--metrics=STRING  # ("CSSWidth,Height,PixelRatio" for mobile emulator tests.)
 --extension-zip=ZIP  # (Load a Chrome Extension .zip file, comma-separated.)
 --extension-dir=DIR  # (Load a Chrome Extension directory, comma-separated.)
 --headless  # (The option to run tests headlessly. The default on Linux OS.)
@@ -246,3 +253,18 @@ If you wish to change the User-Agent for your browser tests (Chrome and Firefox
 ```bash
 pytest user_agent_test.py --agent="Mozilla/5.0 (Nintendo 3DS; U; ; en) Version/1.7412.EU"
 ```
+
+#### **Mobile Device Testing:**
+
+Use ``--mobile`` to quickly run your tests using Chrome's mobile device emulator with default values for device metrics (CSS Width, CSS Height, Pixel-Ratio) and a default value set for the user agent. To configure the mobile device metrics, use ``--metrics="CSS_Width,CSS_Height,Pixel_Ratio"`` to set those values. You'll also be able to set the user agent with ``--agent="USER-AGENT-STRING"`` (a default user agent will be used if not specified). To find real values for device metrics, [see this GitHub Gist](https://gist.github.com/sidferreira/3f5fad525e99b395d8bd882ee0fd9d00). For a list of available user agent strings, [check out this page](https://developers.whatismybrowser.com/useragents/explore/).
+
+```bash
+# Run tests using Chrome's mobile device emulator (default settings)
+pytest test_swag_labs.py --mobile
+
+# Run mobile tests specifying CSS Width, CSS Height, and Pixel-Ratio
+pytest test_swag_labs.py --mobile --metrics="411,731,3"
+
+# Run mobile tests specifying the user agent
+pytest test_swag_labs.py --mobile --agent="Mozilla/5.0 (Linux; Android 9; Pixel 3 XL)"
+```

seleniumbase/core/browser_launcher.py

@@ -125,7 +125,8 @@ def _add_chrome_disable_csp_extension(chrome_options):
 def _set_chrome_options(
         downloads_path, headless, proxy_string, proxy_auth,
         proxy_user, proxy_pass, user_agent, disable_csp, enable_sync,
-        user_data_dir, extension_zip, extension_dir):
+        user_data_dir, extension_zip, extension_dir, mobile_emulator,
+        device_width, device_height, device_pixel_ratio):
     chrome_options = webdriver.ChromeOptions()
     prefs = {
         "download.default_directory": downloads_path,
@@ -140,6 +141,23 @@ def _set_chrome_options(
     chrome_options.add_experimental_option(
         "excludeSwitches", ["enable-automation"])
     chrome_options.add_experimental_option("useAutomationExtension", False)
+    if mobile_emulator:
+        emulator_settings = {}
+        device_metrics = {}
+        if type(device_width) is int and type(device_height) is int and (
+                type(device_pixel_ratio) is int):
+            device_metrics["width"] = device_width
+            device_metrics["height"] = device_height
+            device_metrics["pixelRatio"] = device_pixel_ratio
+        else:
+            device_metrics["width"] = 411
+            device_metrics["height"] = 731
+            device_metrics["pixelRatio"] = 3
+        emulator_settings["deviceMetrics"] = device_metrics
+        if user_agent:
+            emulator_settings["userAgent"] = user_agent
+        chrome_options.add_experimental_option(
+            "mobileEmulation", emulator_settings)
     if enable_sync:
         chrome_options.add_experimental_option(
             "excludeSwitches", ["disable-sync"])
@@ -302,7 +320,8 @@ 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, user_data_dir=None,
-               extension_zip=None, extension_dir=None):
+               extension_zip=None, extension_dir=None, mobile_emulator=False,
+               device_width=None, device_height=None, device_pixel_ratio=None):
     proxy_auth = False
     proxy_user = None
     proxy_pass = None
@@ -336,19 +355,22 @@ def get_driver(browser_name, headless=False, use_grid=False,
             browser_name, headless, servername, port,
             proxy_string, proxy_auth, proxy_user, proxy_pass, user_agent,
             cap_file, disable_csp, enable_sync, user_data_dir,
-            extension_zip, extension_dir)
+            extension_zip, extension_dir, mobile_emulator,
+            device_width, device_height, device_pixel_ratio)
     else:
         return get_local_driver(
             browser_name, headless,
             proxy_string, proxy_auth, proxy_user, proxy_pass, user_agent,
             disable_csp, enable_sync, user_data_dir,
-            extension_zip, extension_dir)
+            extension_zip, extension_dir, mobile_emulator,
+            device_width, device_height, device_pixel_ratio)
 
 
 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, user_data_dir, extension_zip, extension_dir):
+        enable_sync, 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)
@@ -359,7 +381,8 @@ def get_remote_driver(
         chrome_options = _set_chrome_options(
             downloads_path, headless, proxy_string, proxy_auth,
             proxy_user, proxy_pass, user_agent, disable_csp, enable_sync,
-            user_data_dir, extension_zip, extension_dir)
+            user_data_dir, extension_zip, extension_dir, mobile_emulator,
+            device_width, device_height, device_pixel_ratio)
         capabilities = chrome_options.to_capabilities()
         for key in desired_caps.keys():
             capabilities[key] = desired_caps[key]
@@ -469,7 +492,8 @@ def get_local_driver(
         browser_name, headless,
         proxy_string, proxy_auth, proxy_user, proxy_pass, user_agent,
         disable_csp, enable_sync, user_data_dir,
-        extension_zip, extension_dir):
+        extension_zip, extension_dir,
+        mobile_emulator, device_width, device_height, device_pixel_ratio):
     '''
     Spins up a new web browser and returns the driver.
     Can also be used to spin up additional browsers for the same test.
@@ -539,7 +563,8 @@ def get_local_driver(
                 downloads_path, headless,
                 proxy_string, proxy_auth, proxy_user, proxy_pass,
                 user_agent, disable_csp, enable_sync, user_data_dir,
-                extension_zip, extension_dir)
+                extension_zip, extension_dir, mobile_emulator,
+                device_width, device_height, device_pixel_ratio)
             return webdriver.Chrome(executable_path=LOCAL_EDGEDRIVER,
                                     options=chrome_options)
         else:
@@ -563,7 +588,8 @@ def get_local_driver(
                 downloads_path, headless,
                 proxy_string, proxy_auth, proxy_user, proxy_pass,
                 user_agent, disable_csp, enable_sync, user_data_dir,
-                extension_zip, extension_dir)
+                extension_zip, extension_dir, mobile_emulator,
+                device_width, device_height, device_pixel_ratio)
             if LOCAL_CHROMEDRIVER and os.path.exists(LOCAL_CHROMEDRIVER):
                 make_driver_executable_if_not(LOCAL_CHROMEDRIVER)
             elif not is_chromedriver_on_path():