From 0d2a645611168965a22d1e273066e94592d118ba Mon Sep 17 00:00:00 2001 From: Michael Mintz Date: Sat, 31 Dec 2022 01:34:13 -0500 Subject: [PATCH] Update the documentation --- README.md | 92 +++++++++++++++--------------------- examples/ReadMe.md | 76 +++++++++++++++++++++++++---- help_docs/syntax_formats.md | 8 ++-- mkdocs_build/img/logo7.png | Bin 0 -> 510 bytes 4 files changed, 108 insertions(+), 68 deletions(-) create mode 100644 mkdocs_build/img/logo7.png diff --git a/README.md b/README.md index 17d66994..652da301 100755 --- a/README.md +++ b/README.md @@ -5,11 +5,11 @@ - + -

SeleniumBase Multi-Factor Authentication Demo App

+

SeleniumBase

-

SeleniumBase - Python Web-UI Testing Made Easy

+

SeleniumBase: Enterprise Python Web Testing

PyPI version GitHub version SeleniumBase Docs SeleniumBase GitHub Actions SeleniumBase

@@ -53,41 +53,18 @@ -------- -
-

SeleniumBase - Table of Contents:

- -
- --------- -

Run test_demo_site.py from examples/ (--chrome is the default browser):

+

Example: test_coffee_cart.py from SeleniumBase/examples/

```bash cd examples/ -pytest test_demo_site.py +pytest test_coffee_cart.py --demo ``` -

SeleniumBase Example

+

(--demo slows the test with highlighting for better visibility.)

--------- - -

Run test_swag_labs.py from examples/ using Demo Mode:

- -```bash -pytest test_swag_labs.py --demo -``` - -

SeleniumBase Example

+

SeleniumBase Example

-------- @@ -112,12 +89,15 @@ pytest test_swag_labs.py --demo

💡 SeleniumBase includes desktop GUI apps for running tests, such as SeleniumBase Commander for pytest, and SeleniumBase Behave GUI.

💡 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. (See the documentation for more details!)

+ -------- -

Here are a few scripts to test that app with SeleniumBase:

+
+ ▶️ Learn about different ways of writing tests (click to expand) +

📘📝 An example test with the BaseCase class. Runs with pytest or nosetests. (Learn more)

@@ -184,6 +164,11 @@ Feature: SeleniumBase scenarios for the RealWorld App And Save screenshot to logs ``` +
+
+ +-------- +

Set up Python & Git:

@@ -192,7 +177,7 @@ Feature: SeleniumBase scenarios for the RealWorld App 🔵 Using a Python virtual env is recommended. -

Install SeleniumBase:

+

Install SeleniumBase:

**You can install ``seleniumbase`` from [GitHub](https://github.com/seleniumbase/SeleniumBase) or [PyPI](https://pypi.org/project/seleniumbase/):** @@ -275,7 +260,7 @@ COMMANDS: ``` -

Downloading web drivers:

+

Downloading web drivers:

✅ SeleniumBase automatically downloads web drivers as needed, such as ``chromedriver``, ``edgedriver``, and ``geckodriver``. @@ -283,7 +268,7 @@ COMMANDS: -

Basic Example & Usage:

+

Basic Example & Usage:

🔵 If you've cloned SeleniumBase, you can run tests from the [examples/](https://github.com/seleniumbase/SeleniumBase/tree/master/examples) folder. @@ -296,7 +281,7 @@ pytest my_first_test.py > (Uses ``--chrome`` by default.) -SeleniumBase Test +SeleniumBase Test

Here's the code for my_first_test.py:

@@ -334,7 +319,7 @@ class MyTestClass(BaseCase): -

Here are some common SeleniumBase methods that you might find in tests:

+

Here are some common SeleniumBase methods that you might find in tests:

```python self.open(url) # Navigate the browser window to the URL. @@ -375,7 +360,7 @@ self.assert_no_js_errors() # Verify there are no JS errors. -

Fun Facts / Learn More:

+

Fun Facts / Learn More:

✅ SeleniumBase automatically handles common WebDriver actions such as launching web browsers before tests, saving screenshots during failures, and closing web browsers after tests.

@@ -432,7 +417,7 @@ nosetests [FILE_NAME.py]:[CLASS_NAME].[METHOD_NAME] -

Detailed Instructions:

+

Detailed Instructions:

🔵 Demo Mode helps you see what a test is doing. If a test is moving too fast for your eyes, run it in Demo Mode, which pauses the browser briefly between actions, highlights page elements being acted on, and displays assertions: @@ -586,7 +571,7 @@ Here's the command-line option to add to tests: (See [examples/custom_settings.p Inside your tests, you can use ``self.data`` to access that. -

Test Directory Configuration:

+

Test Directory Configuration:

🔵 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. @@ -642,7 +627,7 @@ Of those files, the ``pytest.ini`` config file is the most important, followed b -------- -

Log files from failed tests:

+

Log files from failed tests:

Let's try an example of a test that fails: @@ -667,7 +652,7 @@ pytest test_fail.py -------- -

The SeleniumBase Dashboard:

+

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. Example: @@ -696,7 +681,7 @@ pytest test_suite.py --dashboard --rs --headless -------- -

Generating Test Reports:

+

Generating Test Reports:

Pytest Reports:

@@ -771,7 +756,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 (Chromium or Firefox), you can add ``--proxy=IP_ADDRESS:PORT`` as an argument on the command line. @@ -800,7 +785,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. @@ -809,12 +794,12 @@ pytest user_agent_test.py --agent="Mozilla/5.0 (Nintendo 3DS; U; ; en) Version/1 ``` -

Handling Pop-Up / Pop Up Alerts:

+

Handling Pop-Up / Pop Up Alerts:

🔵 self.accept_alert() automatically waits for and accepts alert pop-ups. self.dismiss_alert() automatically waits for and dismisses alert pop-ups. On occasion, some methods like self.click(SELECTOR) might dismiss a pop-up on its own because they call JavaScript to make sure that the readyState of the page is complete before advancing. If you're trying to accept a pop-up that got dismissed this way, use this workaround: Call self.find_element(SELECTOR).click() instead, (which will let the pop-up remain on the screen), and then use self.accept_alert() to accept the pop-up (more on that here). If pop-ups are intermittent, wrap code in a try/except block. -

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. @@ -824,7 +809,7 @@ pytest user_agent_test.py --agent="Mozilla/5.0 (Nintendo 3DS; U; ; en) Version/1 --------
-

Production Environments & Integrations:

+

Production Environments & Integrations:

@@ -850,7 +835,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) @@ -1059,7 +1044,7 @@ If the web page you're on already has jQuery loaded, you can start executing jQu You'd know this because the web page would contain something like the following in the HTML:

```html - + ``` 🔵 It's OK if you want to use jQuery on a page that doesn't have it loaded yet. To do so, run the following command first: @@ -1162,7 +1147,7 @@ pytest --reruns=1 --reruns-delay=1

You can use the @retry_on_exception() decorator to retry failing methods. (First import: from seleniumbase import decorators). To learn more about SeleniumBase decorators, click here.

-

Wrap-Up

+

Wrap-Up

Congratulations on getting started with SeleniumBase! @@ -1180,11 +1165,8 @@ pytest --reruns=1 --reruns-delay=1
Join the chat!
Tested with SeleniumBase
SeleniumBase Docs
SeleniumBase PyPI downloads

-SeleniumBase on GitHub -SeleniumBase on Facebook -SeleniumBase on Gitter -SeleniumBase on Instagram -SeleniumBase on Twitter +SeleniumBase on GitHub +SeleniumBase on Gitter

SeleniumBase

diff --git a/examples/ReadMe.md b/examples/ReadMe.md index 7d630ae1..b27938bf 100755 --- a/examples/ReadMe.md +++ b/examples/ReadMe.md @@ -1,6 +1,6 @@ -## [](https://github.com/seleniumbase/SeleniumBase/) Example Tests: +## [](https://github.com/seleniumbase/SeleniumBase/) Example Tests:

SeleniumBase Demo Page

@@ -13,17 +13,13 @@ (NOTE: Some example tests fail on purpose to demonstrate [logging features](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/example_logs/ReadMe.md).) -

Example tests with run commands to help you get started:

+-------- -Run an [example test](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/my_first_test.py) in Chrome: (Default: ``--browser=chrome``) +

Example tests with run commands to help you get started:

-```bash -pytest my_first_test.py -``` +-------- -
- -Run an [example test](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/test_demo_site.py) on the SeleniumBase Demo Site: +Run an [example test](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/test_demo_site.py): (Default option: ``--browser=chrome``) ```bash pytest test_demo_site.py @@ -31,12 +27,16 @@ pytest test_demo_site.py
+-------- + Run an example test in Firefox: ```bash pytest my_first_test.py --browser=firefox ``` +-------- + Run an example test in Demo Mode: (highlight assertions) ```bash @@ -45,6 +45,18 @@ pytest test_swag_labs.py --demo
+-------- + +Run [test_coffee_cart.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/test_coffee_cart.py) to test the [Coffee Cart](https://seleniumbase.io/coffee/) app: + +```bash +pytest test_coffee_cart.py --demo +``` + +SeleniumBase Example + +-------- + Run a [Wordle-solver example](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/wordle_test.py): ```bash @@ -53,12 +65,16 @@ pytest wordle_test.py
+-------- + Run an example test in Headless Mode: (invisible browser) ```bash pytest my_first_test.py --headless ``` +-------- + Run an [example test](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/test_swag_labs.py) using Chrome's mobile device emulator: (default settings) ```bash @@ -67,6 +83,8 @@ pytest test_swag_labs.py --mobile
+-------- + Run another [example test](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/test_xkcd.py) in Demo Mode: (highlight assertions) ```bash @@ -75,66 +93,88 @@ pytest test_xkcd.py --demo
+-------- + Run a [test suite](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/test_suite.py) with verbose output: (see more details) ```bash pytest test_suite.py -v ``` +-------- + Run a test suite multi-threaded using [n] threads: ```bash pytest test_suite.py -n=4 ``` +-------- + Run a [parameterized test](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/parameterized_test.py): (Generates multiple tests from one) ```bash pytest parameterized_test.py -v ``` +-------- + Run a test suite and generate a SeleniumBase Dashboard: ```bash pytest test_suite.py --dashboard ``` +-------- + Run a test suite and generate a pytest report: ```bash pytest test_suite.py --html=report.html ``` +-------- + Run a [failing test](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/test_fail.py): (See the ``latest_logs/`` folder for logs and screenshots) ```bash pytest test_fail.py ``` +-------- + Run a failing test with Debug-mode enabled: (``pdb`` activates on failures) ```bash pytest test_fail.py --pdb -s ``` +-------- + Run a test suite that demonstrates the use of pytest markers: ```bash pytest -m marker_test_suite -v ``` +-------- + Run a test suite that reuses the browser session between tests: ```bash pytest test_suite.py --reuse-session ``` +-------- + Run an [example test](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/rate_limiting_test.py) demonstrating the ``rate_limited`` Python decorator: ```bash pytest rate_limiting_test.py ``` +-------- + Run an [example test](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/upload_file_test.py) that demonstrates how to upload a file to a website: ```bash @@ -161,12 +201,16 @@ Run an example test with nosetests: nosetests my_first_test.py ``` +-------- + Run an example test suite and generate a nosetest report: ```bash nosetests test_suite.py --report --show-report ``` +-------- + Run an example test using a nosetest configuration file: ```bash @@ -181,7 +225,7 @@ For more advanced run commands, such as using a proxy server, see [../help_docs/ If you just need to perform some quick website verification on various devices, you can use the SeleniumBase Device Farm. Just plug in a website URL, and it will display how the website looks on four different devices: -
+
-------- @@ -193,6 +237,18 @@ python gui_test_runner.py +(The newer [SeleniumBase Commander](https://seleniumbase.io/help_docs/commander/) improves on that.) + +-------- + +🎖️ To launch the SeleniumBase Commander GUI for pytest: + +```bash +sbase gui +``` + + + -------- diff --git a/help_docs/syntax_formats.md b/help_docs/syntax_formats.md index 0e9c511a..468e70db 100755 --- a/help_docs/syntax_formats.md +++ b/help_docs/syntax_formats.md @@ -44,7 +44,7 @@ In this format, (which is used by most of the tests in the SeleniumBase examples folder), BaseCase is imported at the top of a Python file, followed by a Python class inheriting BaseCase. Then, any test method defined in that class automatically gains access to SeleniumBase methods, including the setUp() and tearDown() methods that are automatically called for opening and closing web browsers at the start and end of tests. -To run a test of this format, use **``pytest``** or ``nosetests``. If you add: ``if __name__ == "__main__":`` ``pytest.main([__file__])`` to a file, you can also use ``python`` as a runner, which invokes ``pytest``. Here's an example: +To run a test of this format, use **``pytest``** or ``nosetests``. If you add: ``if __name__ == "__main__":`` ``pytest.main([__file__])`` to a file, you can also use ``python`` as a test runner, which invokes ``pytest``. Here's an example: ```python from seleniumbase import BaseCase @@ -60,13 +60,15 @@ class MyTestClass(BaseCase): self.assert_exact_text("Demo Page", "h1") self.assert_no_js_errors() -if __name__ == "__main__": # Use "python" to call "pytest" +if __name__ == "__main__": from pytest import main - main([__file__]) + main([__file__, "-s"]) ``` (See examples/test_demo_site.py for the full test.) +Starting with ``seleniumbase`` ``4.11.0``, you can also include ``BaseCase.main(__name__, __file__)`` in your script to invoke ``pytest`` via ``python``. (Eg. [coffee_cart_tests.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/coffee_cart_tests.py)) + Using ``BaseCase`` inheritance is a great starting point for anyone learning SeleniumBase, and it follows good object-oriented programming principles. diff --git a/mkdocs_build/img/logo7.png b/mkdocs_build/img/logo7.png new file mode 100644 index 0000000000000000000000000000000000000000..a99178a232b27e596da71191a96ca6dc501cacc5 GIT binary patch literal 510 zcmeAS@N?(olHy`uVBq!ia0vp^4j|0I1SD0tpLGH$#^NA%Cx&(BWL^R}7O4@QX}-P; zT0k}j17mw80}DtA5K93u0|V0nCb)>h0%imoB$+xhp$n+E#M8wwB!l&Bs9_dUpn$1b zSQ1afk?x9yEpZ2qDVa?==48+@^@gO=27!Z@4yl<3te+74MCNt}$Lasw#wYf@uMxi& z_J9A~ndZOm@q9LT8f(4S&|9OxSS!V0x2!3im^)B*_;H%jD&J*$a3#@{}-K=I_5I7CFJSdHRa< z1n!r=?)=l0-LdzWRkQh#-e+ z7iM#}iX0W2G-czVmkm=d3GvHLfHC{GotW}fajEl%nvxtvm(KzlOB7nVJoxfE?*E%V zF(z%Jb$h4olMcbB9_))wyqi$v{N};(d``GIP;>|%uRMnN;u~A_vyA|$SH06z*k{xFi+m8BWc#+4}2fkeSSY>x+yrh WRDO2oqq1^PJb1eLxvX