From 124cf19280f22acb79e174ca1ad6af5d08a513e7 Mon Sep 17 00:00:00 2001 From: Michael Mintz Date: Mon, 9 Dec 2019 04:04:03 -0500 Subject: [PATCH] Update the docs --- README.md | 17 +++-- help_docs/customizing_test_runs.md | 102 ++++++++++++++++++----------- 2 files changed, 70 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 601e6576..58ef1704 100755 --- a/README.md +++ b/README.md @@ -1,17 +1,14 @@ -[](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md) +[](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md) [ ](https://github.com/seleniumbase/SeleniumBase/releases) [ ](https://dev.azure.com/seleniumbase/seleniumbase/_build/latest?definitionId=1&branchName=master) [ ](https://travis-ci.org/seleniumbase/SeleniumBase) [ ](https://gitter.im/seleniumbase/SeleniumBase) [ ](https://github.com/seleniumbase/SeleniumBase/blob/master/LICENSE) [ ](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).
@@ -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.) diff --git a/help_docs/customizing_test_runs.md b/help_docs/customizing_test_runs.md index 6bc37785..79f1db88 100755 --- a/help_docs/customizing_test_runs.md +++ b/help_docs/customizing_test_runs.md @@ -2,69 +2,74 @@ ## 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): +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). -* 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.) +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 -pytest my_first_test.py --demo - +# 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 + +# 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 - -pytest test_suite.py --headless -n=4 - -pytest test_suite.py --reruns=1 --reruns-delay=1 - -pytest test_suite.py --server=IP_ADDRESS --port=4444 - -pytest test_suite.py --reuse-session - +# Enter Debug Mode on failures pytest test_fail.py --pdb -s +# Rerun failing tests more times +pytest test_suite.py --reruns=1 + +# Pass extra data into tests (retrieve: self.data) +pytest my_first_test.py --data="ABC,DEF" + +# 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 + +# Run tests on a remote Selenium Grid with authentication +pytest test_suite.py --server=USERNAME:KEY@IP_ADDRESS --port=80 + +# 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)" +```