From 7649a920728c667e981f66815ed79863b2077a95 Mon Sep 17 00:00:00 2001 From: Michael Mintz Date: Fri, 18 Dec 2020 01:27:39 -0500 Subject: [PATCH] Update the docs --- CHANGELOG.md | 4 +- README.md | 73 +++++++++++++++++++---------- help_docs/chart_maker.md | 2 +- help_docs/chinese.md | 4 +- help_docs/customizing_test_runs.md | 62 ++++++++++++++++++------ help_docs/how_it_works.md | 4 +- help_docs/install.md | 4 +- help_docs/method_summary.md | 6 +-- help_docs/webdriver_installation.md | 4 +- mkdocs.yml | 10 ++-- 10 files changed, 114 insertions(+), 59 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 065b2991..8fe5a705 100755 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,3 @@ -## CHANGELOG +

CHANGELOG

-### See: [SeleniumBase/releases](https://github.com/seleniumbase/SeleniumBase/releases) +

See: [SeleniumBase/releases](https://github.com/seleniumbase/SeleniumBase/releases)

diff --git a/README.md b/README.md index 695cde6c..681fecb8 100755 --- a/README.md +++ b/README.md @@ -3,10 +3,10 @@ - +

-SeleniumBase

+SeleniumBase

@@ -16,7 +16,7 @@ SeleniumBase SeleniumBase.io Docs

-

SeleniumBase is a complete framework for browser automation, end-to-end testing, reports, charts, presentations, website tours, and visual testing. +

SeleniumBase is a complete browser automation solution for end-to-end testing, reports, charts, presentations, website tours, and visual testing. Tests are run with pytest. Browsers are controlled by WebDriver.

@@ -48,11 +48,11 @@ Tests are run with pytest πŸ›‚ MasterQA

-* Simplifies the process of creating UI tests for websites. -* Uses reliable, smart-waiting code to prevent flaky tests. -* Includes tools for [logging, screenshots, and test reports](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/example_logs/ReadMe.md). -* Has plugins that add new [pytest command-line options](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/customizing_test_runs.md). -* Enhances Selenium's Python API with [versatile methods](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/method_summary.md). +* Simplifies the creation of Web-UI tests. +* Smart-waiting code keeps tests reliable. +* Includes tools for [logging and reports](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/example_logs/ReadMe.md). +* Has plugins that add new [pytest options](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/customizing_test_runs.md). +* Has a vast library of [versatile methods](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/method_summary.md). -------- @@ -67,14 +67,14 @@ pytest test_swag_labs.py --demo -------- -

Quick Start: πŸš€

+

Quick Start: πŸš€

* Add **[Python](https://www.python.org/downloads/)** and **[Git](https://git-scm.com/)** to your System PATH. * Create a **[Python virtual environment](https://seleniumbase.io/help_docs/virtualenv_instructions/)**. -

Install SeleniumBase:

+

Install SeleniumBase:

* You can install ``seleniumbase`` from [pypi](https://pypi.python.org/pypi/seleniumbase): @@ -131,7 +131,7 @@ COMMANDS: * (Use "pytest" for running tests) * ``` -

Download a webdriver:

+

Download a webdriver:

SeleniumBase can download webdrivers to the [seleniumbase/drivers](https://github.com/seleniumbase/SeleniumBase/tree/master/seleniumbase/drivers) folder with the ``install`` command: @@ -150,7 +150,7 @@ sbase install chromedriver latest (See [seleniumbase.io/seleniumbase/console_scripts/ReadMe/](https://seleniumbase.io/seleniumbase/console_scripts/ReadMe/) for more information on SeleniumBase console scripts.) -

Create and run tests:

+

Create and run tests:

* ``sbase mkdir DIR`` creates a folder with sample tests: @@ -261,7 +261,7 @@ self.save_screenshot(FILE_NAME) # Save a screenshot of the current page For the complete list of SeleniumBase methods, see: Method Summary -

Learn More:

+

Learn More:

Automatic WebDriver abilities:

SeleniumBase automatically handles common WebDriver actions such as spinning up web browsers and saving screenshots during test failures. (Read more about customizing test runs.) @@ -317,7 +317,7 @@ For a full list of SeleniumBase features, -

Detailed Instructions:

+

Detailed Instructions:

Use Demo Mode to help you see what tests are asserting. @@ -444,7 +444,7 @@ To pass additional data from the command-line to tests, add ``--data="ANY STRING Inside your tests, you can use ``self.data`` to access that. -

Test Directory Customization:

+

Test Directory Customization:

For running tests outside of the SeleniumBase repo with **Pytest**, you'll want a copy of **[pytest.ini](https://github.com/seleniumbase/SeleniumBase/blob/master/pytest.ini)** on the root folder. For running tests outside of the SeleniumBase repo with **Nosetests**, you'll want a copy of **[setup.cfg](https://github.com/seleniumbase/SeleniumBase/blob/master/setup.cfg)** on the root folder. (Subfolders should include a blank ``__init__.py`` file.) These files specify default configuration details for tests. (For nosetest runs, you can also specify a .cfg file by using ``--config``. Example ``nosetests [MY_TEST.py] --config=[MY_CONFIG.cfg]``) @@ -457,7 +457,7 @@ pytest test_demo_site.py ``` -

Logging / Results from Failing Tests:

+

Logging / Results from Failing Tests:

Let's try an example of a test that fails: @@ -480,11 +480,34 @@ pytest test_fail.py You'll notice that a logs folder, "latest_logs", was created to hold information about the failing test, and screenshots. During test runs, past results get moved to the archived_logs folder if you have ARCHIVE_EXISTING_LOGS set to True in [settings.py](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/config/settings.py), or if your run tests with ``--archive-logs``. If you choose not to archive existing logs, they will be deleted and replaced by the logs of the latest test run. +-------- + +

The SeleniumBase Dashboard:

+ +The ``--dashboard`` option for pytest generates a SeleniumBase Dashboard located at ``dashboard.html``, which updates automatically as tests run and produce results. + +The SeleniumBase Dashboard + +Additionally, you can host your own SeleniumBase Dashboard Server on a port of your choice. Here's an example of that using Python 3's ``http.server``: + +```bash +python -m http.server 1948 +``` + +Now you can navigate to ``http://localhost:1948/dashboard.html`` in order to view the served dashboard from a web browser. (Be sure to run that command in the same directory where you ran your tests.) + +Here's a full example of what the SeleniumBase Dashboard may look like: + +```bash +pytest test_suite.py --dashboard --rs --headless +``` + +The SeleniumBase Dashboard + +-------- -

Creating Visual Test Suite Reports:

- -(NOTE: Several command-line args are different for Pytest vs Nosetests) +

Creating Visual Test Suite Reports:

Pytest Reports:

@@ -523,7 +546,7 @@ pytest test_suite.py --alluredir=allure_results ``` -

Using a Proxy Server:

+

Using a Proxy Server:

If you wish to use a proxy server for your browser tests (Chrome and Firefox only), you can add ``--proxy=IP_ADDRESS:PORT`` as an argument on the command-line. @@ -544,7 +567,7 @@ pytest proxy_test.py --proxy=proxy1 ``` -

Changing the User-Agent:

+

Changing the User-Agent:

If you wish to change the User-Agent for your browser tests (Chromium and Firefox only), you can add ``--agent="USER AGENT STRING"`` as an argument on the command-line. @@ -553,13 +576,13 @@ pytest user_agent_test.py --agent="Mozilla/5.0 (Nintendo 3DS; U; ; en) Version/1 ``` -

Building Guided Tours for Websites:

+

Building Guided Tours for Websites:

Learn about SeleniumBase Interactive Walkthroughs (in the ``examples/tour_examples`` folder). It's great for prototyping a website onboarding experience. -

Production Environments & Integrations:

+

Production Environments & Integrations:

Here are some things you can do to set up a production environment for your testing: @@ -580,7 +603,7 @@ pytest [YOUR_TEST_FILE.py] --with-db-reporting --with-s3-logging ``` -

Detailed Method Specifications and Examples:

+

Detailed Method Specifications and Examples:

Navigating to a web page (and related commands)

@@ -868,7 +891,7 @@ pytest --reruns 5 --reruns-delay 1 Additionally, you can use the ``@retry_on_exception()`` decorator to specifically retry failing methods. (First import: ``from seleniumbase import decorators``) To learn more about SeleniumBase decorators, [click here](https://github.com/seleniumbase/SeleniumBase/tree/master/seleniumbase/common). -

Wrap-Up

+

Wrap-Up

Congratulations on getting started with SeleniumBase! diff --git a/help_docs/chart_maker.md b/help_docs/chart_maker.md index 3f293b7c..956961d6 100755 --- a/help_docs/chart_maker.md +++ b/help_docs/chart_maker.md @@ -1,4 +1,4 @@ -

SeleniumBase

+

SeleniumBase

πŸ“Š ChartMaker πŸ“ˆ

diff --git a/help_docs/chinese.md b/help_docs/chinese.md index 8b1bb015..88c902e0 100644 --- a/help_docs/chinese.md +++ b/help_docs/chinese.md @@ -46,7 +46,7 @@

Selenium ε’Œ pytest η»„εˆδ½Ώη”¨.

-

SeleniumBase

+

SeleniumBase

立即开始:

@@ -105,7 +105,7 @@ pytest my_first_test.py pytest my_first_test.py --demo ``` - + 歀倄为相关代码 [my_first_test.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/my_first_test.py): diff --git a/help_docs/customizing_test_runs.md b/help_docs/customizing_test_runs.md index 76384fbc..fd343283 100755 --- a/help_docs/customizing_test_runs.md +++ b/help_docs/customizing_test_runs.md @@ -1,6 +1,6 @@ -[](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md) +[](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md) -

CLI Options

+

CLI Options

You can customize test runs from the command-line interface thanks to [SeleniumBase's pytest plugin](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/plugins/pytest_plugin.py), which adds CLI options for setting/enabling the browser type, headless mode, mobile mode, multithreading mode, demo mode, proxy config, user agent config, browser extensions, and more. @@ -155,14 +155,14 @@ Or the short form: sbase options ``` -### Customizing default settings: +

Customizing default settings:

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.) -### Running tests on a remote Selenium Grid: +

Running tests on a remote Selenium Grid:

SeleniumBase lets you run tests on remote Selenium Grids such as [BrowserStack](https://www.browserstack.com/automate#)'s Selenium Grid, [Sauce Labs](https://saucelabs.com/products/open-source-frameworks/selenium)'s Selenium Grid, [TestingBot](https://testingbot.com/features)'s Selenium Grid, other Grids, and even your own Grid: @@ -200,7 +200,7 @@ pytest my_first_test.py --server=USERNAME:KEY@hub.lambdatest.com --port=80 Or you can create your own Selenium Grid for test distribution. ([See this ReadMe for details](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/utilities/selenium_grid/ReadMe.md)) -### Example tests using Logging: +

Example tests using Logging:

```bash pytest test_suite.py --browser=chrome @@ -208,7 +208,7 @@ pytest test_suite.py --browser=chrome (During test failures, logs and screenshots from the most recent test run will get saved to the ``latest_logs/`` folder. Those logs will get moved to ``archived_logs/`` if you have ARCHIVE_EXISTING_LOGS set to True in [settings.py](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/config/settings.py), otherwise log files with be cleaned up at the start of the next test run.) -### Demo Mode: +

Demo Mode:

If any test is moving too fast for your eyes to see what's going on, you can run it in **Demo Mode** by adding ``--demo`` on the command line, which pauses the browser briefly between actions, highlights page elements being acted on, and lets you know what test assertions are happening in real time: @@ -222,15 +222,15 @@ You can override the default wait time by either updating [settings.py](https:// pytest my_first_test.py --demo --demo-sleep=1.2 ``` -### Passing additional data to tests: +

Passing additional data to tests:

If you want to pass additional data from the command line to your tests, you can use ``--data=STRING``. Now inside your tests, you can use ``self.data`` to access that. -### Running tests multithreaded: +

Running tests multithreaded:

To run Pytest multithreaded on multiple CPUs at the same time, add ``-n=NUM`` or ``-n NUM`` on the command line, where NUM is the number of CPUs you want to use. -### Retrying failing tests automatically: +

Retrying failing tests automatically:

You can use ``--reruns=NUM`` to retry failing tests that many times. Use ``--reruns-delay=SECONDS`` to wait that many seconds between retries. Example: @@ -238,7 +238,7 @@ You can use ``--reruns=NUM`` to retry failing tests that many times. Use ``--rer pytest --reruns=2 --reruns-delay=1 ``` -### Debugging tests: +

Debugging tests:

You can use the following calls in your scripts to help you debug issues: @@ -256,7 +256,33 @@ pytest my_first_test.py --pdb -s The code above will leave your browser window open in case there's a failure. (ipdb commands: 'c', 's', 'n' => continue, step, next). -### Pytest Reports: +-------- + +

The SeleniumBase Dashboard:

+ +The ``--dashboard`` option for pytest generates a SeleniumBase Dashboard located at ``dashboard.html``, which updates automatically as tests run and produce results. + +The SeleniumBase Dashboard + +Additionally, you can host your own SeleniumBase Dashboard Server on a port of your choice. Here's an example of that using Python 3's ``http.server``: + +```bash +python -m http.server 1948 +``` + +Now you can navigate to ``http://localhost:1948/dashboard.html`` in order to view the served dashboard from a web browser. (Be sure to run that command in the same directory where you ran your tests.) + +Here's a full example of what the SeleniumBase Dashboard may look like: + +```bash +pytest test_suite.py --dashboard --rs --headless +``` + +The SeleniumBase Dashboard + +-------- + +

Pytest Reports:

Using ``--html=report.html`` gives you a fancy report of the name specified after your test suite completes. @@ -266,7 +292,9 @@ pytest test_suite.py --html=report.html Example Pytest Report -### Nosetest Reports: +-------- + +

Nosetest Reports:

The ``--report`` option gives you a fancy report after your test suite completes. @@ -278,7 +306,9 @@ nosetests test_suite.py --report (NOTE: You can add ``--show_report`` to immediately display Nosetest reports after the test suite completes. Only use ``--show_report`` when running tests locally because it pauses the test run.) -### Using a Proxy Server: +-------- + +

Using a Proxy Server:

If you wish to use a proxy server for your browser tests (Chrome and Firefox only), you can add ``--proxy=IP_ADDRESS:PORT`` as an argument on the command line. @@ -298,7 +328,9 @@ To make things easier, you can add your frequently-used proxies to PROXY_LIST in pytest proxy_test.py --proxy=proxy1 ``` -### Changing the User-Agent: +-------- + +

Changing the User-Agent:

If you wish to change the User-Agent for your browser tests (Chrome and Firefox only), you can add ``--agent="USER-AGENT-STRING"`` as an argument on the command line. @@ -306,7 +338,7 @@ If you wish to change the User-Agent for your browser tests (Chrome and Firefox pytest user_agent_test.py --agent="Mozilla/5.0 (Nintendo 3DS; U; ; en) Version/1.7412.EU" ``` -### Mobile Device Testing: +

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/). diff --git a/help_docs/how_it_works.md b/help_docs/how_it_works.md index b80490ef..500c990e 100755 --- a/help_docs/how_it_works.md +++ b/help_docs/how_it_works.md @@ -1,7 +1,7 @@ -[](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md) +[](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md) -

How it works:

+

How it works:

At the core, SeleniumBase works by extending [pytest](https://docs.pytest.org/en/latest/) as a direct plugin. SeleniumBase automatically spins up web browsers for tests, and then gives those tests access to the SeleniumBase libraries through the [BaseCase class](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/fixtures/base_case.py). Tests are also given access to [SeleniumBase command-line arguments](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/customizing_test_runs.md) and [SeleniumBase methods](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/method_summary.md), which provide additional functionality. diff --git a/help_docs/install.md b/help_docs/install.md index 277a3e00..1fa205bf 100755 --- a/help_docs/install.md +++ b/help_docs/install.md @@ -1,6 +1,6 @@ -[](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md) +[](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md) -## Installation +

Installation

If installing SeleniumBase directly [from PyPI (the Python Package Index)](https://pypi.python.org/pypi/seleniumbase), use: ```bash diff --git a/help_docs/method_summary.md b/help_docs/method_summary.md index 1baf83ad..f24bfc5f 100755 --- a/help_docs/method_summary.md +++ b/help_docs/method_summary.md @@ -1,6 +1,6 @@ -[](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md) +[](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md) -## Method Summary (API Reference) +

Method Summary (API Reference)

Here's a summary of SeleniumBase method definitions, which are defined in [base_case.py](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/fixtures/base_case.py) @@ -401,7 +401,7 @@ self.add_series_to_chart(data_name=None, chart_name=None) self.add_data_point(label, value, color=None, chart_name=None) -self.save_chart(chart_name=None, filename=None) +self.save_chart(chart_name=None, filename=None, folder=None) self.display_chart(chart_name=None, filename=None, interval=0) diff --git a/help_docs/webdriver_installation.md b/help_docs/webdriver_installation.md index 332132b5..1b14e723 100755 --- a/help_docs/webdriver_installation.md +++ b/help_docs/webdriver_installation.md @@ -1,6 +1,6 @@ -[](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md) +[](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md) -## Installing webdrivers +

Installing webdrivers

To run web automation, you'll need webdrivers for each browser you plan on using. Here are some commands that'll automatically download the driver you need into the SeleniumBase ``drivers`` folder once you've installed SeleniumBase: diff --git a/mkdocs.yml b/mkdocs.yml index 282ded72..c72bbe72 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,8 +1,8 @@ # Project information -site_name: Docs - seleniumbase.io +site_name: SeleniumBase - Docs site_url: https://seleniumbase.io site_author: Michael Mintz -site_description: The world's most powerful all-in-one web automation platform. Build fast, reliable, end-to-end tests with Python. +site_description: The most advanced web automation platform for fast, reliable, end-to-end testing with Python. # Repository information repo_name: seleniumbase/SeleniumBase repo_url: https://github.com/seleniumbase/SeleniumBase @@ -24,8 +24,8 @@ markdown_extensions: # Configuration theme: name: material - logo: img/logo3a.png - favicon: img/logo3a.png + logo: img/grad_logo.png + favicon: img/logo4.png include_homepage_in_sidebar: true sticky_navigation: true language: en @@ -53,7 +53,7 @@ plugins: on_pre_build: docs.prepare:main # Page tree nav: - - SeleniumBase Docs: README.md + - SeleniumBase - Docs: README.md - Features List: help_docs/features_list.md - Running Example Tests: examples/ReadMe.md - Command Line Options: help_docs/customizing_test_runs.md