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.
-* 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.
+
+
+
+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
+```
+
+
+
+--------
-
Creating Visual Test Suite Reports:
-
-(NOTE: Several command-line args are different for Pytest vs Nosetests)
+
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 @@
-
+
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.
+
+
+
+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
+```
+
+
+
+--------
+
+
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
-### 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
+
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