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

Update documentation and examples

This commit is contained in:
Michael Mintz 2023-07-03 15:30:38 -04:00
parent a203c6a6ef
commit 2e55cb1767
9 changed files with 69 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
README.md
View File

@ -9,19 +9,21 @@
<h1>SeleniumBase</h1>
<h3 align="center"><a href="https://github.com/seleniumbase/SeleniumBase/"><img src="https://seleniumbase.io/cdn/img/sb_logo_10t.png" alt="SeleniumBase" title="SeleniumBase" width="266" /></a></h3>
<h3 align="center">Automate, test, and identify regressions in web apps — using Python!</h3>
<h3 align="center">Create reliable end-to-end browser tests with Python</h3>
<h3 align="center"><a href="https://github.com/seleniumbase/SeleniumBase/"><img src="https://seleniumbase.github.io/cdn/gif/swag_mobile_2.gif" alt="SeleniumBase" title="SeleniumBase" width="480" /></a></h3>
<p align="center"><a href="https://pypi.python.org/pypi/seleniumbase" target="_blank"><img src="https://img.shields.io/pypi/v/seleniumbase.svg?color=3399EE" alt="PyPI version" /></a> <a href="https://github.com/seleniumbase/SeleniumBase/releases" target="_blank"><img src="https://img.shields.io/github/v/release/seleniumbase/SeleniumBase.svg?color=22AAEE" alt="GitHub version" /></a> <a href="https://seleniumbase.io"><img src="https://img.shields.io/badge/docs-seleniumbase.io-11BBAA.svg" alt="SeleniumBase Docs" /></a> <a href="https://github.com/seleniumbase/SeleniumBase/actions" target="_blank"><img src="https://github.com/seleniumbase/SeleniumBase/workflows/CI%20build/badge.svg" alt="SeleniumBase GitHub Actions" /></a> <a href="https://gitter.im/seleniumbase/SeleniumBase" target="_blank"><img src="https://img.shields.io/gitter/room/seleniumbase/SeleniumBase.svg" alt="Gitter chat"/></a></p>
<h4 align="center">SeleniumBase tutorials, tools, and integrations:</h4>
<p align="center">
<a href="#python_installation">🚀 Start</a> |
<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/features_list.md">🏰 Features</a> |
<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/ReadMe.md">📚 Examples</a> |
<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/customizing_test_runs.md">🎛️ Options</a> |
<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/console_scripts/ReadMe.md">🌠 Scripts</a> |
<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/mobile_testing.md">📱 Phone</a>
<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/mobile_testing.md">📱 Mobile</a>
<br />
<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/method_summary.md">📘 APIs</a> |
<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/syntax_formats.md"> 🔡 Formats</a> |
@ -48,7 +50,7 @@
<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/js_package_manager.md">🕹️ JSMgr</a> |
<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/translations.md">🌏 Translator</a> |
<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/presenter/ReadMe.md">🎞️ Presenter</a> |
<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/dialog_boxes/ReadMe.md">🛂 Boxes</a> |
<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/dialog_boxes/ReadMe.md">🛂 Dialog</a> |
<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/visual_testing/ReadMe.md">🖼️ Visual</a>
<br />
</p>
@ -117,9 +119,9 @@ With raw Selenium, that requires more code:<br />
<p>💡 SeleniumBase gives you the option to generate a dashboard and reports for tests. It also saves screenshots from failing tests to the <code>./latest_logs/</code> folder. Raw <a href="https://www.selenium.dev/documentation/webdriver/" target="_blank">Selenium</a> does not have these options out-of-the-box.</p>
<p>💡 SeleniumBase includes desktop GUI apps for running tests, such as <b>SeleniumBase Commander</b> for <code>pytest</code>, and <b>SeleniumBase Behave GUI.</b></p>
<p>💡 SeleniumBase includes desktop GUI apps for running tests, such as <b>SeleniumBase Commander</b> for <code>pytest</code> and <b>SeleniumBase Behave GUI for <a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/behave_bdd/ReadMe.md"><code>behave</code></a>.</b></p>
<p>💡 SeleniumBase has its own Recorder & Test Generator that can create tests from manual browser actions. SeleniumBase also has many other useful tools and console scripts for getting things done quickly. (<i>See the documentation for more details!</i>)</p>
<p>💡 SeleniumBase has its own Recorder / Test Generator that can create tests from manual browser actions. SeleniumBase also includes other useful tools and console scripts for getting things done quickly. (<i>See the documentation for more details!</i>)</p>
</div>
</details>
@ -134,6 +136,7 @@ With raw Selenium, that requires more code:<br />
```python
from seleniumbase import BaseCase
BaseCase.main(__name__, __file__)
class TestMFALogin(BaseCase):
def test_mfa_login(self):
@ -666,6 +669,7 @@ Let's try an example of a test that fails:
```python
""" test_fail.py """
from seleniumbase import BaseCase
BaseCase.main(__name__, __file__)
class MyTestClass(BaseCase):
@ -694,7 +698,7 @@ pytest --dashboard --rs --headless
<img src="https://seleniumbase.github.io/cdn/img/dashboard_1.png" alt="The SeleniumBase Dashboard" title="The SeleniumBase Dashboard" width="380" />
🔵 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``:
🔵 Additionally, you can host your own SeleniumBase Dashboard Server on a port of your choice. Here's an example of that using Python's ``http.server``:
```bash
python -m http.server 1948
@ -1138,6 +1142,7 @@ self.click("a.analytics") # Clicks the generated button
```python
from seleniumbase import BaseCase
BaseCase.main(__name__, __file__)
class MyTestClass(BaseCase):
@ -1192,6 +1197,9 @@ pytest --reruns=1 --reruns-delay=1
<div><b>If you like SeleniumBase, star us! ⭐</b></div>
<div><a href="https://github.com/seleniumbase/SeleniumBase/stargazers"><img src="https://img.shields.io/github/stars/seleniumbase/seleniumbase.svg?color=19A57B" title="Stargazers" /></a></div>
</p>
<p align="left"><a href="https://github.com/seleniumbase/SeleniumBase/"><img src="https://seleniumbase.github.io/cdn/img/sb_logo_10t.png" alt="SeleniumBase" title="SeleniumBase" width="266" /></a></p>
<p><div><a href="https://github.com/mdmintz">https://github.com/mdmintz</a></div></p>
<div><a href="https://github.com/seleniumbase/SeleniumBase/"><img src="https://seleniumbase.github.io/cdn/img/fancy_logo_14.png" title="SeleniumBase" width="220" /></a></div> <div><a href="https://github.com/seleniumbase/SeleniumBase/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-22BBCC.svg" title="SeleniumBase" /></a> <a href="https://gitter.im/seleniumbase/SeleniumBase" target="_blank"><img src="https://img.shields.io/gitter/room/seleniumbase/SeleniumBase.svg" alt="Gitter chat"/></a></div> <div><a href="https://github.com/seleniumbase/SeleniumBase"><img src="https://img.shields.io/badge/tested%20with-SeleniumBase-04C38E.svg" alt="Tested with SeleniumBase" /></a></div> <div><a href="https://seleniumbase.io"><img src="https://img.shields.io/badge/docs-seleniumbase.io-11BBAA.svg" alt="SeleniumBase Docs" /></a></div>
@ -1205,5 +1213,5 @@ pytest --reruns=1 --reruns-delay=1
--------
<p><a href="https://github.com/seleniumbase/SeleniumBase/"><img src="https://seleniumbase.github.io/cdn/img/sb_logo_b.png" alt="SeleniumBase" title="SeleniumBase" width="300" /></a></p>
<p><a href="https://github.com/seleniumbase/SeleniumBase/"><img src="https://seleniumbase.github.io/cdn/img/super_logo_sb.png" alt="SeleniumBase" title="SeleniumBase" width="300" /></a></p>
<p><a href="https://www.python.org/downloads/" target="_blank"><img src="https://img.shields.io/pypi/pyversions/seleniumbase.svg?color=22AAEE&logo=python&logoColor=FEDC54" title="Supported Python Versions" /></a></p>

4
examples/chart_maker/ReadMe.md
View File

@ -19,6 +19,7 @@ Here's the code for that pie chart presentation ([GitHub => seleniumbase/Seleniu
```python
from seleniumbase import BaseCase
BaseCase.main(__name__, __file__)
class MyChartMakerClass(BaseCase):
def test_chart_maker(self):
@ -57,6 +58,7 @@ Here are screenshots from the examples:
```python
from seleniumbase import BaseCase
BaseCase.main(__name__, __file__)
class MyChartMakerClass(BaseCase):
def test_chart_maker(self):
@ -87,9 +89,9 @@ Because that presentation above has an ``interval`` set to ``8``, it will automa
```python
from seleniumbase import BaseCase
BaseCase.main(__name__, __file__)
class MyChartMakerClass(BaseCase):
def test_chart_maker_presentation(self):
self.create_presentation(theme="sky")

6
examples/presenter/ReadMe.md
View File

@ -110,10 +110,9 @@ All methods have the optional ``name`` argument, which is only needed if you're
```python
from seleniumbase import BaseCase
BaseCase.main(__name__, __file__)
class MyPresenterClass(BaseCase):
def test_presenter(self):
self.create_presentation(theme="serif")
self.add_slide(
@ -146,8 +145,7 @@ class MyPresenterClass(BaseCase):
'<tr><td>O</td><td>Overview Mode Toggle</td></tr>\n'
'<tr><td>esc</td><td>Exit Full Screen / Overview Mode</td></tr>\n'
'<tr><td><b>.</b></td><td>Pause/Resume Toggle</td></tr>\n'
'<tr><td>space</td><td>Next Slide (alternative)</td></tr></table>'
)
'<tr><td>space</td><td>Next Slide (alternative)</td></tr></table>')
self.add_slide(
'<h3>Add <b>images</b> to slides:</h3>',
image="https://seleniumbase.github.io/other/seagulls.jpg")

15
examples/presenter/my_presentation.py
View File

@ -48,8 +48,9 @@ class MyPresenterClass(BaseCase):
self.add_slide(
"<h3>Add <b>code</b> to slides:</h3>",
code=(
"from seleniumbase import BaseCase\n\n"
"class MyTestClass(BaseCase):\n\n"
"from seleniumbase import BaseCase\n"
"BaseCase.main(__name__, __file__)\n\n"
"class MyTestClass(BaseCase):\n"
" def test_basics(self):\n"
' self.open("https://xkcd.com/353/")\n'
' self.assert_title("xkcd: Python")\n'
@ -64,8 +65,9 @@ class MyPresenterClass(BaseCase):
self.add_slide(
"<h3>Highlight <b>code</b> in slides:</h3>",
code=(
"from seleniumbase import BaseCase\n\n"
"<mark>class MyTestClass(BaseCase):</mark>\n\n"
"from seleniumbase import BaseCase\n"
"BaseCase.main(__name__, __file__)\n\n"
"<mark>class MyTestClass(BaseCase):</mark>\n"
" def test_basics(self):\n"
' self.open("https://xkcd.com/353/")\n'
' self.assert_title("xkcd: Python")\n'
@ -84,8 +86,9 @@ class MyPresenterClass(BaseCase):
self.add_slide(
"<h3>Getting started is <b>easy</b>:</h3>",
code=(
"from seleniumbase import BaseCase\n\n"
"class MyPresenterClass(BaseCase):\n\n"
"from seleniumbase import BaseCase\n"
"BaseCase.main(__name__, __file__)\n\n"
"class MyPresenterClass(BaseCase):\n"
" def test_presenter(self):\n"
' self.create_presentation(theme="serif")\n'
' self.add_slide("Welcome to Presenter!")\n'

1
examples/test_verify_chromedriver.py
View File

@ -1,4 +1,5 @@
from seleniumbase import BaseCase
BaseCase.main(__name__, __file__)
class ChromedriverTests(BaseCase):

4
examples/tour_examples/ReadMe.md
View File

@ -103,16 +103,18 @@ All methods have the optional ``name`` argument, which is only needed if you're
```python
from seleniumbase import BaseCase
BaseCase.main(__name__, __file__)
class MyTourClass(BaseCase):
def test_google_tour(self):
self.open('https://google.com/ncr')
self.wait_for_element('input[title="Search"]')
self.hide_elements("iframe")
self.create_tour(theme="dark")
self.add_tour_step("Welcome to Google!", title="SeleniumBase Tours")
self.add_tour_step("Type in your query here.", 'input[title="Search"]')
self.add_tour_step("Type in your query here.", '[title="Search"]')
self.play_tour()
self.highlight_type('input[title="Search"]', "Google")

6
examples/visual_testing/ReadMe.md
View File

@ -73,9 +73,9 @@ Here's an example where clicking a button makes a hidden element visible:
```python
from seleniumbase import BaseCase
BaseCase.main(__name__, __file__)
class VisualLayoutTest(BaseCase):
def test_applitools_layout_change_failure(self):
self.open('https://applitools.com/helloworld?diff1')
print('\nCreating baseline in "visual_baseline" folder.')
@ -107,9 +107,9 @@ Here's an example where a button is removed from a web page:
```python
from seleniumbase import BaseCase
BaseCase.main(__name__, __file__)
class VisualLayoutTest(BaseCase):
def test_python_home_layout_change_failure(self):
self.open('https://python.org/')
print('\nCreating baseline in "visual_baseline" folder.')
@ -144,9 +144,9 @@ Here's another example, where a web site logo is resized:
```python
from seleniumbase import BaseCase
BaseCase.main(__name__, __file__)
class VisualLayoutTest(BaseCase):
def test_xkcd_layout_change_failure(self):
self.open('https://xkcd.com/554/')
print('\nCreating baseline in "visual_baseline" folder.')

38
help_docs/how_it_works.md
View File

@ -4,23 +4,41 @@
<a id="how_seleniumbase_works"></a>
👁️🔎 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 (using [Selenium WebDriver](https://www.selenium.dev/documentation/webdriver/)), 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.
👁️🔎 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 (using [Selenium WebDriver](https://www.selenium.dev/documentation/webdriver/)), 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 options](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.
👁️🔎 ``pytest`` uses a feature called test discovery to automatically find and run Python methods that start with ``test_`` when those methods are located in Python files that start with ``test_`` or end with ``_test.py``.
👁️🔎 The most common way of using **SeleniumBase** is by inheriting ``BaseCase``:
👁️🔎 The most common way of using **SeleniumBase** is by importing ``BaseCase``:
```python
from seleniumbase import BaseCase
```
Then have your test classes inherit ``BaseCase``:
👁️🔎 This line activates ``pytest`` when a file is called directly with ``python``:
```python
BaseCase.main(__name__, __file__)
```
👁️🔎 Classes can inherit ``BaseCase`` to gain SeleniumBase functionality:
```python
class MyTestClass(BaseCase):
```
Here's what a full test might look like:
👁️🔎 Test methods inside ``BaseCase`` classes become SeleniumBase tests: (These tests automatically launch a web browser before starting, and quit the web browser after ending. Default settings can be changed via command-line options.)
```python
def test_abc(self):
```
👁️🔎 SeleniumBase APIs can be called from tests via ``self``:
```python
self.open("https://example.com")
```
👁️🔎 Here's what a full test might look like:
```python
from seleniumbase import BaseCase
@ -46,14 +64,14 @@ class TestMFALogin(BaseCase):
👁️🔎 Here are some examples of running tests with ``pytest``:
```bash
pytest --headless -n8 --dashboard --html=report.html -v --rs --crumbs
pytest test_mfa_login.py
pytest --headless -n8 --dashboard --html=report.html -v --rs --crumbs
pytest -m marker2
pytest offline_examples/
pytest -k agent
pytest offline_examples/
```
(See <a href="https://seleniumbase.io/help_docs/syntax_formats/">SyntaxFormats</a> for more ways of using <b>SeleniumBase</b>.)
(See <a href="https://seleniumbase.io/help_docs/syntax_formats/">Syntax_Formats</a> for more ways of structuring <b>SeleniumBase</b> tests.)
--------
@ -66,7 +84,7 @@ pytest -k agent
* **(1)**: Selenium's default ``pageLoadStrategy`` is ``normal``: This strategy causes Selenium to wait for the full page to load, with HTML content and sub-resources downloaded and parsed.
* **(2)**: SeleniumBase includes methods such as ``wait_for_ready_state_complete()`` and ``wait_for_angularjs()``, which run inside other SeleniumBase methods to ensure that it's safe to proceed with the next command.
* **(2)**: SeleniumBase includes methods such as ``wait_for_ready_state_complete()``, which run inside other SeleniumBase methods to ensure that it's safe to proceed with the next command.
* **(3)**: SeleniumBase methods automatically wait for elements to be visible and interactable before interacting with those elements.
@ -74,9 +92,9 @@ pytest -k agent
* ``--pls=none`` --> Set ``pageLoadStrategy`` to ``"none"``: This strategy causes Selenium to return immediately after the initial HTML content is fully received by the browser.
* ``--sjw`` --> Skip JS Waits, which include ``wait_for_ready_state_complete()`` and ``wait_for_angularjs()``.
* ``--sjw`` --> Skip JS Waits, such as ``wait_for_ready_state_complete()``.
--------
<p><a href="https://github.com/seleniumbase/SeleniumBase/"><img src="https://seleniumbase.github.io/cdn/img/super_logo_sb.png" alt="SeleniumBase" title="SeleniumBase" width="300" /></a></p>
<p><a href="https://www.python.org/downloads/" target="_blank"><img src="https://img.shields.io/pypi/pyversions/seleniumbase.svg?color=22AAEE&logo=python" title="Supported Python Versions" /></a></p>
<p><a href="https://www.python.org/downloads/" target="_blank"><img src="https://img.shields.io/pypi/pyversions/seleniumbase.svg?color=22AAEE&logo=python&logoColor=FEDC54" title="Supported Python Versions" /></a></p>

4
help_docs/syntax_formats.md
View File

@ -73,6 +73,7 @@ There are situations where you may want to customize the <code>setUp</code> and
```python
from seleniumbase import BaseCase
BaseCase.main(__name__, __file__)
class BaseTestCase(BaseCase):
def setUp(self):
@ -150,6 +151,7 @@ With SeleniumBase, you can use Page Objects to break out code from tests, but re
```python
from seleniumbase import BaseCase
BaseCase.main(__name__, __file__)
class LoginPage:
def login_to_swag_labs(self, sb, username):
@ -235,6 +237,7 @@ When you want to use SeleniumBase methods via <code>BaseCase</code>, but you wan
```python
from selenium import webdriver
from seleniumbase import BaseCase
BaseCase.main(__name__, __file__)
class OverrideDriverTest(BaseCase):
def get_new_driver(self, *args, **kwargs):
@ -267,6 +270,7 @@ The above format lets you customize [selenium-wire](https://github.com/wkeeling/
```python
from seleniumbase import BaseCase
from seleniumwire import webdriver # Requires "pip install selenium-wire"
BaseCase.main(__name__, __file__)
class WireTestCase(BaseCase):