test_framework
/
SeleniumBase
mirror of https://github.com/seleniumbase/SeleniumBase.git
3
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update the docs

This commit is contained in:
Michael Mintz 2020-05-21 23:39:59 -04:00
parent 82e03bc316
commit d901ea2634
10 changed files with 49 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
README.md
View File

@ -42,7 +42,7 @@
<p align="center"><div align="center"><img src="https://cdn2.hubspot.net/hubfs/100006/images/swag_labs_gif.gif" alt="SeleniumBase" title="SeleniumBase" /></div></p>
<a id="python_installation"></a>
## <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Get Started
<h2><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Get Started:</h2>
* Requires **[Python](https://www.python.org/downloads/)** and **[Git](https://git-scm.com/)**
* [<img src="https://img.shields.io/pypi/pyversions/seleniumbase.svg?color=22AAEE" alt="Python:2.7|3.5|3.6|3.7|3.8" />](https://www.python.org/downloads/)
@ -53,7 +53,7 @@ python -m pip install -U pip
```
<a id="install_seleniumbase"></a>
### <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Install ``seleniumbase``:
<h2><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Install SeleniumBase:</h2>
```bash
git clone https://github.com/seleniumbase/SeleniumBase.git
cd SeleniumBase/
@ -69,7 +69,7 @@ pip install seleniumbase
* Add ``--upgrade`` OR ``-U`` to upgrade an installation.
* Add ``--force-reinstall`` to also upgrade dependencies.
### <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Download a webdriver:
<h3><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Download a webdriver:</h3>
SeleniumBase can download a webdriver to the [seleniumbase/drivers](https://github.com/seleniumbase/SeleniumBase/tree/master/seleniumbase/drivers) folder with the ``install`` command:
```bash
@ -81,7 +81,7 @@ seleniumbase install chromedriver
seleniumbase install chromedriver latest
```
### <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Run a test on Chrome:
<h3><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Run a test on Chrome:</h3>
```bash
cd examples/
pytest my_first_test.py
@ -328,7 +328,7 @@ To pass additional data from the command-line to tests, add ``--data="ANY STRING
Now inside your tests, you can use ``self.data`` to access that.
### <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Test Directory Customization:
<h3><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Test Directory Customization:</h3>
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``)
@ -340,7 +340,7 @@ pytest my_first_test.py
```
### <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Logging / Results from Failing Tests:
<h3><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Logging / Results from Failing Tests:</h3>
Let's try an example of a test that fails:
```python
@ -363,11 +363,11 @@ You'll notice that a logs folder, "latest_logs", was created to hold information
<a id="creating_visual_reports"></a>
### <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Creating Visual Test Suite Reports:
<h3><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Creating Visual Test Suite Reports:</h3>
(NOTE: Several command-line args are different for Pytest vs Nosetests)
#### **Pytest Reports:**
<h4><b>Pytest Reports:</b></h4>
Using ``--html=report.html`` gives you a fancy report of the name specified after your test suite completes.
```bash
@ -381,7 +381,7 @@ You can also use ``--junit-xml=report.xml`` to get an xml report instead. Jenkin
pytest test_suite.py --junit-xml=report.xml
```
#### **Nosetest Reports:**
<h4><b>Nosetest Reports:</b></h4>
The ``--report`` option gives you a fancy report after your test suite completes.
```bash
@ -392,7 +392,7 @@ 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.)
### <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Using a Proxy Server:
<h3><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Using a Proxy Server:</h3>
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.
```bash
@ -410,7 +410,7 @@ pytest proxy_test.py --proxy=proxy1
```
### <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Changing the User-Agent:
<h3><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Changing the User-Agent:</h3>
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.
```bash
@ -418,13 +418,13 @@ pytest user_agent_test.py --agent="Mozilla/5.0 (Nintendo 3DS; U; ; en) Version/1
```
### <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Building Guided Tours for Websites:
<h3><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Building Guided Tours for Websites:</h3>
Learn about <a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/tour_examples/ReadMe.md">SeleniumBase Interactive Walkthroughs</a> (in the ``examples/tour_examples`` folder). It's great for prototyping a website onboarding experience.
<a id="utilizing_advanced_features"></a>
### <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Production Environments & Integrations:
<h3><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Production Environments & Integrations:</h3>
Here are some things you can do to setup a production environment for your testing:
@ -444,9 +444,9 @@ pytest [YOUR_TEST_FILE].py --with-db-reporting --with-s3-logging
```
<a id="detailed_method_specifications"></a>
### <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Detailed Method Specifications and Examples:
<h3><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Detailed Method Specifications and Examples:</h3>
#### Navigating to a web page (and related commands)
<h4>Navigating to a web page (and related commands)</h4>
```python
self.open("https://xkcd.com/378/") # This method opens the specified page.
@ -470,7 +470,7 @@ head_close_tag = source.find('</head>', head_open_tag)
everything_inside_head = source[head_open_tag+len('<head>'):head_close_tag]
```
#### Clicking
<h4>Clicking</h4>
To click an element on the page:
```python
@ -479,7 +479,7 @@ self.click("div#my_id")
**ProTip™:** In most web browsers, you can right-click on a page and select ``Inspect Element`` to see the CSS selector details that you'll need to create your own scripts.
#### Typing Text
<h4>Typing Text</h4>
self.update_text(selector, text) # updates the text from the specified element with the specified value. An exception is raised if the element is missing or if the text field is not editable. Example:
```python
@ -493,23 +493,27 @@ from selenium.webdriver.common.keys import Keys
self.find_element("textarea").send_keys(Keys.SPACE + Keys.BACK_SPACE + '\n') # The backspace should cancel out the space, leaving you with the newline
```
#### Getting the text from an element on a page
<h4>Getting the text from an element on a page</h4>
```python
text = self.get_text("header h2")
```
#### Getting the attribute value from an element on a page
<h4>Getting the attribute value from an element on a page</h4>
```python
attribute = self.get_attribute("#comic img", "title")
```
#### Asserting existance of an element on a page within some number of seconds:
<h4>Asserting existance of an element on a page within some number of seconds:</h4>
```python
self.wait_for_element_present("div.my_class", timeout=10)
```
(NOTE: You can also use: ``self.assert_element_present(ELEMENT)``)
#### Asserting visibility of an element on a page within some number of seconds:
<h4>Asserting visibility of an element on a page within some number of seconds:</h4>
```python
self.wait_for_element_visible("a.my_class", timeout=5)
```
@ -531,21 +535,23 @@ You can also use ``*=`` to search for any partial value in a CSS selector as sho
self.click('a[name*="partial_name"]')
```
#### Asserting visibility of text inside an element on a page within some number of seconds:
<h4>Asserting visibility of text inside an element on a page within some number of seconds:</h4>
```python
self.assert_text("Make it so!", "div#trek div.picard div.quotes")
self.assert_text("Tea. Earl Grey. Hot.", "div#trek div.picard div.quotes", timeout=3)
```
(NOTE: ``self.find_text(TEXT, ELEMENT)`` and ``self.wait_for_text(TEXT, ELEMENT)`` also do this. For backwords compatibility, older method names were kept, but the default timeout may be different.)
#### Asserting Anything
<h4>Asserting Anything</h4>
```python
self.assert_true(myvar1 == something)
self.assert_equal(var1, var2)
```
#### Useful Conditional Statements (with creative examples in action)
<h4>Useful Conditional Statements (with creative examples in action)</h4>
is_element_visible(selector) # is an element visible on a page
```python
@ -593,7 +599,7 @@ def get_mirror_universe_captain_picard_superbowl_ad(superbowl_year):
raise Exception("Reports of my assimilation are greatly exaggerated.")
```
#### Switching Tabs
<h4>Switching Tabs</h4>
What if your test opens up a new tab/window and now you have more than one page? No problem. You need to specify which one you currently want Selenium to use. Switching between tabs/windows is easy:
```python
@ -608,7 +614,7 @@ self.switch_to_frame('ContentManagerTextBody_ifr')
self.switch_to_default_content() # Exit the iFrame when you're done
```
#### Handle Pop-Up Alerts
<h4>Handling Pop-Up Alerts</h4>
What if your test makes an alert pop up in your browser? No problem. You need to switch to it and either accept it or dismiss it:
```python
@ -619,7 +625,7 @@ self.wait_for_and_dismiss_alert()
If you're not sure whether there's an alert before trying to accept or dismiss it, one way to handle that is to wrap your alert-handling code in a try/except block. Other methods such as .text and .send_keys() will also work with alerts.
#### Executing Custom jQuery Scripts:
<h4>Executing Custom jQuery Scripts:</h4>
jQuery is a powerful JavaScript library that allows you to perform advanced actions in a web browser.
If the web page you're on already has jQuery loaded, you can start executing jQuery scripts immediately.
@ -667,7 +673,7 @@ self.click("a.analytics") # Clicks the generated button
```
(Due to popular demand, this traffic generation example has been baked into SeleniumBase with the ``self.generate_referral(start_page, end_page)`` and the ``self.generate_traffic(start_page, end_page, loops)`` methods.)
#### Using delayed asserts:
<h4>Using delayed asserts:</h4>
Let's say you want to verify multiple different elements on a web page in a single test, but you don't want the test to fail until you verified several elements at once so that you don't have to rerun the test to find more missing elements on the same page. That's where delayed asserts come in. Here's the example:
```python
@ -690,7 +696,7 @@ class MyTestClass(BaseCase):
``delayed_assert_element()`` and ``delayed_assert_text()`` will save any exceptions that would be raised.
To flush out all the failed delayed asserts into a single exception, make sure to call ``self.process_delayed_asserts()`` at the end of your test method. If your test hits multiple pages, you can call ``self.process_delayed_asserts()`` at the end of all your delayed asserts for a single page. This way, the screenshot from your log file will have the location where the delayed asserts were made.
#### Accessing raw WebDriver
<h4>Accessing raw WebDriver</h4>
If you need access to any commands that come with standard WebDriver, you can call them directly like this:
```python
@ -700,7 +706,7 @@ self.driver.find_elements_by_partial_link_text("GitHub")
```
(In general, you'll want to use the SeleniumBase versions of methods when available.)
#### Retrying failing tests automatically
<h4>Retrying failing tests automatically</h4>
You can use ``--reruns NUM`` to retry failing tests that many times. Use ``--reruns-delay SECONDS`` to wait that many seconds between retries. Example:
```
@ -710,9 +716,9 @@ 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).
### <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Wrap-Up
<h3><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Wrap-Up</h3>
#### Congratulations on getting started with SeleniumBase!
<b>Congratulations on getting started with SeleniumBase!</b>
<p>
<div><b>If you see something, say something!</b></div>

2
examples/ReadMe.md
View File

@ -1,6 +1,6 @@
<p align="center"><a align="center" href="https://github.com/seleniumbase/SeleniumBase/blob/master/README.md"><img align="center" src="https://cdn2.hubspot.net/hubfs/100006/images/super_logo_sb8.png" alt="SeleniumBase" width="290" /></a></p>
## <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Running Example Tests:
<h2><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Running Example Tests:</h2>
SeleniumBase tests are run with **``pytest``**. Chrome is the default browser if not specifed. During test failures, logs and screenshots from the latest run are saved to the ``latest_logs/`` folder.

4
examples/translations/ReadMe.md
View File

@ -1,7 +1,7 @@
<h3 align="left"><a href="https://github.com/seleniumbase/SeleniumBase/"><img src="https://cdn2.hubspot.net/hubfs/100006/images/super_logo_m.png" title="SeleniumBase" width="290" /></a></h3>
<a id="language_tests"></a>
### <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Language Tests (Python 3+)
<h3><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Language Tests (Python 3+)</h3>
<b>SeleniumBase</b> supports the following 10 languages:
<ul>
@ -27,7 +27,7 @@ self.뒤로() = self.go_back()
```
<a id="translation_api"></a>
## <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Translation API
<h2><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Translation API</h2>
You can use SeleniumBase to selectively translate the method names of any test from one language to another via the console scripts interface. Additionally, the ``import`` line at the top of the Python file will change to import the new ``BaseCase``. Example: ``BaseCase`` becomes ``CasoDeTeste`` when a test is translated into Portuguese.

2
help_docs/ReadMe.md
View File

@ -1,6 +1,6 @@
<div><a href="https://github.com/seleniumbase/SeleniumBase"><img src="https://cdn2.hubspot.net/hubfs/100006/images/sb_media_logo.png" alt="SeleniumBase" width="240" /></a></div>
## <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Help Documents
<h2><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Help Documents</h2>
<h3>Table of Contents (<a href="https://seleniumbase.io">seleniumbase.io</a>)</h3>

2
help_docs/customizing_test_runs.md
View File

@ -1,6 +1,6 @@
[<img src="https://cdn2.hubspot.net/hubfs/100006/images/super_logo_sb.png" title="SeleniumBase" width="290">](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md)
## <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Customizing test runs
<h2><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Customizing test runs</h2>
You can customize test runs from the command-line thanks to [SeleniumBase's pytest plugin](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/plugins/pytest_plugin.py), which adds command-line options for setting/enabling the browser type, headless mode, mobile mode, multithreading mode, demo mode, proxy config, user agent config, browser extensions, and more.

2
help_docs/features_list.md
View File

@ -4,7 +4,7 @@
<p>(<b><a href="https://www.youtube.com/watch?v=Sjzq9kU5kOw">Watch the tutorial on YouTube</a></b>)</p>
<a id="feature_list"></a>
## <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> **Features:**
<h2><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Features:</h2>
* A complete test automation framework for web/mobile UI testing.
* Uses [pytest](https://docs.pytest.org/en/latest/), [unittest](https://docs.python.org/3/library/unittest.html), and [nose](http://nose.readthedocs.io/en/latest/) for test discovery and execution.
* No more flaky tests! (Smart-waiting code keeps tests reliable.)

2
help_docs/how_it_works.md
View File

@ -1,7 +1,7 @@
[<img src="https://cdn2.hubspot.net/hubfs/100006/images/super_logo_sb4.png" title="SeleniumBase" width="290">](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md)
<a id="how_seleniumbase_works"></a>
## <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> **How it works:**
<h2><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> How it works:</h2>
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/seleniumbase/plugins/pytest_plugin.py) and [SeleniumBase methods](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/method_summary.md), which provide additional functionality.

2
help_docs/mobile_testing.md
View File

@ -1,5 +1,5 @@
[<img src="https://cdn2.hubspot.net/hubfs/100006/images/SeleniumBaseText_F.png" title="SeleniumBase" align="center" width="290">](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md)
## <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Mobile Testing
<h2><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Mobile Testing</h2>
Use ``--mobile`` to run your SeleniumBase tests using Chrome's (or Edge's) mobile device emulator with default values for device metrics (CSS Width, CSS Height, Pixel-Ratio) and user agent.

4
help_docs/translations.md
View File

@ -1,7 +1,7 @@
<h3 align="left"><a href="https://github.com/seleniumbase/SeleniumBase/"><img src="https://cdn2.hubspot.net/hubfs/100006/images/super_logo_m.png" title="SeleniumBase" width="290" /></a></h3>
<a id="language_tests"></a>
### <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Language Tests (Python 3+)
<h3><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Language Tests (Python 3+)</h3>
<b>SeleniumBase</b> supports the following 10 languages:
<ul>
@ -27,7 +27,7 @@ self.뒤로() = self.go_back()
```
<a id="translation_api"></a>
## <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Translation API
<h2><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Translation API</h2>
You can use SeleniumBase to selectively translate the method names of any test from one language to another via the console scripts interface. Additionally, the ``import`` line at the top of the Python file will change to import the new ``BaseCase``. Example: ``BaseCase`` becomes ``CasoDeTeste`` when a test is translated into Portuguese.

2
help_docs/virtualenv_instructions.md
View File

@ -1,4 +1,4 @@
## <img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Virtual Environment Tutorial
<h2><img src="https://seleniumbase.io/img/sb_icon.png" title="SeleniumBase" width="30" /> Virtual Environment Tutorial</h2>
### Step 1: Install VirtualEnv and VirtualEnvWrapper: