Skip to content

Dependencies, docs, and refactoring #1939

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jul 8, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 68 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@

<h1>SeleniumBase</h1>

<h3 align="center">Python-powered web automation and testing — with advanced tools.</h3>
<h3 align="center">Automate & test web apps on any platform, with Python.</h3>

<h3 align="center"><a href="https://github.com/seleniumbase/SeleniumBase"><img src="https://seleniumbase.github.io/cdn/gif/coffee_pdbp.gif" alt="SeleniumBase test with the pdbp debugger" title="SeleniumBase test with the pdbp debugger" /></a></h3>

Expand Down Expand Up @@ -57,7 +57,42 @@

--------

<blockquote>
<p dir="auto"><strong>Jump to:</strong></p>
<ul dir="auto">
<li><a href="#multiple_examples" ><strong>Multiple Examples</strong></a></li>
<li><a href="#python_installation" ><strong>Set up Python & Git</strong></a></li>
<li><a href="#install_seleniumbase" ><strong>Install SeleniumBase</strong></a></li>
<li><a href="#basic_example_and_usage"><strong>Basic Example & Usage</strong></a></li>
<li><a href="#common_methods" ><strong>Common Test Methods</strong></a></li>
<li><a href="#fun_facts" ><strong>Fun Facts / Learn More</strong></a></li>
<li><a href="#demo_mode_and_debugging"><strong>Demo Mode and Debugging</strong></a></li>
<li><a href="#pytest_options" ><strong>Useful pytest Options</strong></a></li>
<li><a href="#new_pytest_options" ><strong>SeleniumBase Options</strong></a></li>
<li><a href="#directory_configuration"><strong>Directory Configuration</strong></a></li>
<li><a href="#seleniumbase_dashboard" ><strong>SeleniumBase Dashboard</strong></a></li>
<li><a href="#creating_visual_reports"><strong>Generating Test Reports</strong></a></li>
</ul>
</blockquote>

--------

<a id="multiple_examples"></a>
<p align="left">Run <a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/test_demo_site.py" target="_blank">test_demo_site.py</a> from <a href="https://github.com/seleniumbase/SeleniumBase/tree/master/examples" target="_blank">examples/</a> (<code>--chrome</code> is the default browser):</p>

```bash
cd examples/
pytest test_demo_site.py
```

<p align="left"><a href="https://seleniumbase.io/demo_page" target="_blank"><img src="https://seleniumbase.github.io/cdn/gif/demo_page_5.gif" width="480" alt="SeleniumBase Example" title="SeleniumBase Example" /></a></p>

> Type text, click, select, toggle, drag-and-drop, etc. Even handle iframes.

--------

Looking for overpriced coffee? Try running this test:

<p align="left"><b>Example:</b> <a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/test_coffee_cart.py" target="_blank">test_coffee_cart.py</a> from <a href="https://github.com/seleniumbase/SeleniumBase/tree/master/examples" target="_blank">./examples/</a></p>

```bash
Expand Down Expand Up @@ -97,7 +132,7 @@ class CoffeeCartTest(BaseCase):
<summary> ▶️ How is <b>SeleniumBase</b> different from raw Selenium? (<b>click to expand</b>)</summary>
<div>

<p>💡 SeleniumBase is a Python framework for browser automation and testing. SeleniumBase uses <a href="https://www.w3.org/TR/webdriver2/#endpoints" target="_blank">Selenium/WebDriver</a> APIs, and incorporates test-runners such as <code>pytest</code>, <code>nosetests</code>, and <code>behave</code> to provide organized structure, test discovery, test execution, test state (<i>eg. passed, failed, or skipped</i>), and command-line options for changing default settings (<i>such as choosing the browser to use</i>). With raw Selenium, you would need to set up your own options-parser for configuring tests from the command-line.</p>
<p>💡 SeleniumBase is a Python framework for browser automation and testing. SeleniumBase uses <a href="https://www.w3.org/TR/webdriver2/#endpoints" target="_blank">Selenium/WebDriver</a> APIs, and incorporates test-runners such as <code>pytest</code>, <code>pynose</code>, and <code>behave</code> to provide organized structure, test discovery, test execution, test state (<i>eg. passed, failed, or skipped</i>), and command-line options for changing default settings (<i>such as choosing the browser to use</i>). With raw Selenium, you would need to set up your own options-parser for configuring tests from the command-line.</p>

<p>💡 With raw Selenium, commands that use selectors need to specify the type of selector (eg. <code>"css selector", "button#myButton"</code>). With SeleniumBase, there's auto-detection between CSS Selectors and XPath, which means you don't need to specify the type of selector in your commands (<i>but optionally you could</i>).</p>

Expand Down Expand Up @@ -132,7 +167,7 @@ With raw Selenium, that requires more code:<br />
<summary> ▶️ Learn about different ways of writing tests (<b>click to expand</b>)</summary>
<div>

<p align="left">📘📝 An example test with the <b>BaseCase</b> class. Runs with <b><a href="https://docs.pytest.org/en/latest/how-to/usage.html">pytest</a></b> or <b>nosetests</b>. (<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/ReadMe.md">Learn more</a>)</p>
<p align="left">📘📝 An example test with the <b>BaseCase</b> class. Runs with <b><a href="https://docs.pytest.org/en/latest/how-to/usage.html">pytest</a></b> or <b>pynose</b>. (<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/ReadMe.md">Learn more</a>)</p>

```python
from seleniumbase import BaseCase
Expand Down Expand Up @@ -206,6 +241,8 @@ Feature: SeleniumBase scenarios for the RealWorld App
<a id="python_installation"></a>
<h2><img src="https://seleniumbase.github.io/cdn/img/python_logo.png" title="SeleniumBase" width="42" /> Set up Python & Git:</h2>

<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/pypi/pyversions/seleniumbase.svg?color=FACE42" title="Supported Python Versions" /></a>

🔵 Add <b><a href="https://www.python.org/downloads/">Python</a></b> and <b><a href="https://git-scm.com/">Git</a></b> to your System PATH.

🔵 Using a <a href="https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/virtualenv_instructions.md">Python virtual env</a> is recommended.
Expand Down Expand Up @@ -311,6 +348,8 @@ pytest my_first_test.py

<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/my_first_test.py"><img src="https://seleniumbase.github.io/cdn/gif/swag_labs_4.gif" alt="SeleniumBase Test" title="SeleniumBase Test" width="480" /></a>

> SeleniumBase easily handles login, shopping, and checkout.

<p align="left"><b>Here's the code for <a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/my_first_test.py">my_first_test.py</a>:</b></p>

```python
Expand Down Expand Up @@ -402,12 +441,21 @@ self.assert_no_js_errors() # Verify there are no JS errors.
self.type("input", "dogs\n")
```

SeleniumBase tests can be run with <code>pytest</code> or <code>nosetests</code>. (There's also a <a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/behave_bdd/ReadMe.md">behave BDD</a> format.)
Most SeleniumBase scripts can be run with <code>pytest</code>, <code>pynose</code>, or pure <code>python</code>. Not all test runners can run all test formats. For example, tests that use the ``sb`` pytest fixture can only be run with ``pytest``. (See <a href="https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/syntax_formats.md">Syntax Formats</a>) There's also a <a href="https://behave.readthedocs.io/en/stable/gherkin.html" target="_blank">Gherkin</a> test format that runs with <a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/behave_bdd/ReadMe.md">behave</a>.

```bash
pytest my_first_test.py --chrome
pytest test_sb_fixture.py
pytest coffee_cart_tests.py --rs
pytest test_suite.py --rs --html=report.html --dashboard

pynose basic_test.py --mobile
pynose test_suite.py --headless --report --show-report

nosetests test_suite.py --firefox
python raw_sb.py
python raw_test_scripts.py

behave realworld.feature
behave calculator.feature -D rs -D dashboard
```

<p>✅ <code>pytest</code> includes automatic test discovery. If you don't specify a specific file or folder to run, <code>pytest</code> will automatically search through all subdirectories for tests to run based on the following criteria:</p>
Expand All @@ -423,12 +471,12 @@ With a SeleniumBase [pytest.ini](https://github.com/seleniumbase/SeleniumBase/bl
pytest --collect-only -q
```

<p>✅ You can be more specific when calling <code>pytest</code> on a file:</p>
<p>✅ You can be more specific when calling <code>pytest</code> or <code>pynose</code> on a file:</p>

```bash
pytest [FILE_NAME.py]::[CLASS_NAME]::[METHOD_NAME]

nosetests [FILE_NAME.py]:[CLASS_NAME].[METHOD_NAME]
pynose [FILE_NAME.py]:[CLASS_NAME].[METHOD_NAME]
```

<p>✅ No More Flaky Tests! SeleniumBase methods automatically wait for page elements to finish loading before interacting with them (<i>up to a timeout limit</i>). This means <b>you no longer need random <span><code>time.sleep()</code></span> statements</b> in your scripts.</p>
Expand All @@ -449,6 +497,7 @@ nosetests [FILE_NAME.py]:[CLASS_NAME].[METHOD_NAME]
<a id="detailed_instructions"></a>
<h2><img src="https://seleniumbase.github.io/img/logo7.png" title="SeleniumBase" width="32" /> Detailed Instructions:</h2>

<a id="demo_mode_and_debugging"></a>
<a id="seleniumbase_demo_mode"></a>
🔵 <b>Demo Mode</b> helps you see what a test is doing. If a test is moving too fast for your eyes, run it in <b>Demo Mode</b>, which pauses the browser briefly between actions, highlights page elements being acted on, and displays assertions:

Expand Down Expand Up @@ -605,10 +654,10 @@ Here's the command-line option to add to tests: (See [examples/custom_settings.p
🔵 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.

<a id="directory_configuration"></a>
<h3><img src="https://seleniumbase.github.io/img/logo7.png" title="SeleniumBase" width="32" /> Directory Configuration:</h3>

<h3><img src="https://seleniumbase.github.io/img/logo7.png" title="SeleniumBase" width="32" /> Test Directory Configuration:</h3>

🔵 When running tests with **pytest**, you'll want a copy of **[pytest.ini](https://github.com/seleniumbase/SeleniumBase/blob/master/pytest.ini)** in your root folders. When running tests with **nosetests**, you'll want a copy of **[setup.cfg](https://github.com/seleniumbase/SeleniumBase/blob/master/setup.cfg)** in your root folders. These files specify default configuration details for tests. Folders should also include a blank ``__init__.py`` file, which allows your tests to import files from that folder.
🔵 When running tests with **pytest**, you'll want a copy of **[pytest.ini](https://github.com/seleniumbase/SeleniumBase/blob/master/pytest.ini)** in your root folders. When running tests with **pynose**, you'll want a copy of **[setup.cfg](https://github.com/seleniumbase/SeleniumBase/blob/master/setup.cfg)** in your root folders. These files specify default configuration details for tests. Folders should also include a blank ``__init__.py`` file, which allows your tests to import files from that folder.

🔵 ``sbase mkdir DIR`` creates a folder with config files and sample tests:

Expand Down Expand Up @@ -658,7 +707,7 @@ ui_tests/
└── setup.cfg
```

Of those files, the ``pytest.ini`` config file is the most important, followed by a blank ``__init__.py`` file. There's also a ``setup.cfg`` file (only needed for nosetests). Finally, the ``requirements.txt`` file can be used to help you install seleniumbase into your environments (if it's not already installed).
Of those files, the ``pytest.ini`` config file is the most important, followed by a blank ``__init__.py`` file. There's also a ``setup.cfg`` file (for pynose). Finally, the ``requirements.txt`` file can be used to help you install seleniumbase into your environments (if it's not already installed).

--------

Expand Down Expand Up @@ -688,7 +737,8 @@ pytest test_fail.py

--------

<h3><img src="https://seleniumbase.github.io/img/logo7.png" title="SeleniumBase" width="32" /> The SeleniumBase Dashboard:</h3>
<a id="seleniumbase_dashboard"></a>
<h3><img src="https://seleniumbase.github.io/img/logo7.png" title="SeleniumBase" width="32" /> SeleniumBase Dashboard:</h3>

🔵 The ``--dashboard`` option for pytest generates a SeleniumBase Dashboard located at ``dashboard.html``, which updates automatically as tests run and produce results. Example:

Expand Down Expand Up @@ -747,17 +797,17 @@ You can also use ``--junit-xml=report.xml`` to get an xml report instead. Jenkin
pytest test_suite.py --junit-xml=report.xml
```

<h4><b>Nosetest Reports:</b></h4>
<h4><b>pynose Reports:</b></h4>

The ``--report`` option gives you a fancy report after your test suite completes.

```bash
nosetests test_suite.py --report
pynose test_suite.py --report
```

<img src="https://seleniumbase.github.io/cdn/img/nose_report.png" alt="Example Nosetest Report" title="Example Nosetest Report" width="320" />
<img src="https://seleniumbase.github.io/cdn/img/nose_report.png" alt="Example pynose Report" title="Example pynose Report" width="320" />

(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.)
(NOTE: You can add ``--show-report`` to immediately display pynose reports after the test suite completes. Only use ``--show-report`` when running tests locally because it pauses the test run.)

<h4><b>Behave Dashboard & Reports:</b></h4>

Expand Down Expand Up @@ -1209,6 +1259,7 @@ pytest --reruns=1 --reruns-delay=1
<span><a href="https://www.youtube.com/playlist?list=PLp9uKicxkBc5UIlGi2BuE3aWC7JyXpD3m"><img src="https://seleniumbase.github.io/cdn/img/youtube.png" title="SeleniumBase Playlist on YouTube" alt="SeleniumBase Playlist on YouTube" width="54" /></a></span>
<span><a href="https://github.com/seleniumbase/SeleniumBase"><img src="https://seleniumbase.github.io/img/social/share_github.svg" title="SeleniumBase on GitHub" alt="SeleniumBase on GitHub" width="50" /></a></span>
<span><a href="https://gitter.im/seleniumbase/SeleniumBase" target="_blank"><img src="https://seleniumbase.github.io/img/social/share_gitter.svg" title="SeleniumBase on Gitter" alt="SeleniumBase on Gitter" width="38" /></a></span>
<span><a href="https://twitter.com/seleniumbase" target="_blank"><img src="https://seleniumbase.io/img/social/share_twitter.svg" title="SeleniumBase on Twitter" alt="SeleniumBase on Twitter" width="50" /></a></span>
</div></p>

--------
Expand Down
14 changes: 7 additions & 7 deletions examples/ReadMe.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,28 +193,28 @@ sbase gui

--------

<b>SeleniumBase tests can also be run with ``nosetests``:</b>
<b>SeleniumBase tests can also be run with ``pynose``:</b>

Run an example test with nosetests:
Run an example test with pynose:

```bash
nosetests my_first_test.py
pynose my_first_test.py
```

--------

Run an example test suite and generate a nosetest report:
Run an example test suite and generate a pynose test report:

```bash
nosetests test_suite.py --report --show-report
pynose test_suite.py --report --show-report
```

--------

Run an example test using a nosetest configuration file:
Run an example test using a pynose configuration file:

```bash
nosetests my_first_test.py --config=example_config.cfg
pynose my_first_test.py --config=example_config.cfg
```

--------
Expand Down
10 changes: 5 additions & 5 deletions examples/example_logs/ReadMe.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,17 +90,17 @@ pytest test_suite.py --junit-xml=report.xml

--------

<h3><img src="https://seleniumbase.github.io/img/logo6.png" title="SeleniumBase" width="32" /> Nosetest Reports:</h3>
<h3><img src="https://seleniumbase.github.io/img/logo6.png" title="SeleniumBase" width="32" /> pynose Test Reports:</h3>

The ``nosetests`` ``--report`` option gives you a fancy report after your tests complete.
The ``pynose`` ``--report`` option gives you a fancy report after your tests complete.

```bash
nosetests test_suite.py --report
pynose test_suite.py --report
```

<img src="https://seleniumbase.github.io/cdn/img/nose_report.png" alt="Example Nosetest Report" title="Example Nosetest Report" width="320" />
<img src="https://seleniumbase.github.io/cdn/img/nose_report.png" alt="Example pynose Test Report" title="Example pynose Test Report" width="320" />

(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.)
(NOTE: You can add ``--show-report`` to immediately display pynose reports after the test suite completes. Only use ``--show-report`` when running tests locally because it pauses the test run.)

--------

Expand Down
4 changes: 2 additions & 2 deletions examples/github_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,5 +17,5 @@ def test_github(self):
self.assert_element("div.repository-content")
self.assert_text("SeleniumBase", "strong a")
self.click('a[title="seleniumbase"]')
self.slow_click('a[title="fixtures"]')
self.assert_element('a[title="base_case.py"]')
self.slow_click('a:contains("fixtures")')
self.assert_element('a:contains("base_case.py")')
7 changes: 2 additions & 5 deletions examples/hack_the_planet.py
Original file line number Diff line number Diff line change
Expand Up @@ -87,11 +87,8 @@ def test_all_your_base_are_belong_to_us(self):
self.set_text_content("h1 span:nth-of-type(3)", "BELONG")
self.set_text_content("h1 span:nth-of-type(4)", "TO")
self.set_text_content("h1 span:nth-of-type(5)", "US")
self.type('input[name="q"]', aybabtu.lower())
self.click("h1", scroll=False)
self.highlight('a[href="/pricing"]', loops=5, scroll=False)
self.highlight('input[name="q"]', loops=5, scroll=False)
self.highlight("h1", loops=8, scroll=False)
self.highlight('a[href="/pricing"]', loops=6, scroll=False)
self.highlight("h1.h2-mktg", loops=7, scroll=False)

self.open("https://dev.to/top/infinity")
self.click_if_visible('button[aria-label="Close campaign banner"]')
Expand Down
15 changes: 8 additions & 7 deletions examples/migration/protractor/ReadMe.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,17 +8,18 @@

```bash
$ pytest --rs -v --guest
========================== test session starts ==========================
platform darwin -- Python 3.9.2, pytest-6.2.3, py-1.10.0, pluggy-0.13.1
metadata: {'Python': '3.9.2', 'Platform': 'macOS-10.14.6-x86_64-i386-64bit', 'Packages': {'pytest': '6.2.4', 'py': '1.10.0', 'pluggy': '0.13.1'}, 'Plugins': {'html': '2.0.1', 'rerunfailures': '10.0', 'xdist': '2.2.1', 'metadata': '1.11.0', 'ordering': '0.6', 'forked': '1.3.0', 'seleniumbase': '1.63.10'}}
rootdir: /Users/michael/github/SeleniumBase/examples, configfile: pytest.ini
plugins: html-2.0.1, rerunfailures-10.0, xdist-2.2.1, metadata-1.11.0, ordering-0.6, forked-1.3.0, seleniumbase-1.63.10
collected 4 items
=========================== test session starts ============================
platform darwin -- Python 3.11.2, pytest-7.4.0, pluggy-1.2.0 -- /Users/michael/.virtualenvs/sb_venv/bin/python
metadata: {'Python': '3.11.2', 'Platform': 'macOS-13.2.1-arm64-arm-64bit', 'Packages': {'pytest': '7.4.0', 'pluggy': '1.2.0'}, 'Plugins': {'html': '2.0.1', 'rerunfailures': '12.0', 'metadata': '3.0.0', 'ordering': '0.6', 'xdist': '3.3.1', 'seleniumbase': '4.15.10'}}
rootdir: /Users/michael/github/SeleniumBase/examples
configfile: pytest.ini
plugins: html-2.0.1, rerunfailures-12.0, metadata-3.0.0, ordering-0.6, xdist-3.3.1, seleniumbase-4.15.10
collected 4 items

example_test.py::AngularJSHomePageTests::test_greet_user PASSED
example_test.py::AngularJSHomePageTests::test_todo_list PASSED
input_test.py::AngularMaterialInputTests::test_invalid_input PASSED
mat_paginator_test.py::AngularMaterialPaginatorTests::test_pagination PASSED

========================== 4 passed in 10.34s ==========================
============================ 4 passed in 4.24s =============================
```
Loading