Update the documentation

Author: mdmintz

README.md

@@ -367,8 +367,8 @@ nosetests [FILE_NAME.py]:[CLASS_NAME].[METHOD_NAME]
 ```
 
 ✅ No More Flaky Tests:
-<p>SeleniumBase methods automatically wait for page elements to finish loading before interacting with them (<i>up to a timeout limit</i>). This means you <b>no longer need</b> random <span><b>time.sleep()</b></span> statements in your scripts.</p>
-<img src="https://img.shields.io/badge/Flaky Tests%3F-%20NO%21-11BBDD.svg" alt="NO MORE FLAKY TESTS!" />
+<p>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>
+<img src="https://img.shields.io/badge/Flaky%20Tests%3F-%20NO%21-11BBDD.svg" alt="NO MORE FLAKY TESTS!" />
 
 ✅ Automated/Manual Hybrid Mode:
 <p>SeleniumBase includes a solution called <b><a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/master_qa/ReadMe.md">MasterQA</a></b>, which speeds up manual testing by having automation perform all the browser actions while the manual tester handles validation.</p>
@@ -466,14 +466,16 @@ The code above will leave your browser window open in case there's a failure. (i
 --firefox-pref=SET  # (Set a Firefox preference:value set, comma-separated.)
 --extension-zip=ZIP  # (Load a Chrome Extension .zip|.crx, comma-separated.)
 --extension-dir=DIR  # (Load a Chrome Extension directory, comma-separated.)
+--pls=PLS  # (Set pageLoadStrategy on Chrome: "normal", "eager", or "none".)
 --headless  # (Run tests in headless mode. The default arg on Linux OS.)
 --headed  # (Run tests in headed/GUI mode on Linux OS.)
 --xvfb  # (Run tests using the Xvfb virtual display server on Linux OS.)
 --locale=LOCALE_CODE  # (Set the Language Locale Code for the web browser.)
 --interval=SECONDS  # (The autoplay interval for presentations & tour steps)
 --start-page=URL  # (The starting URL for the web browser when tests begin.)
---archive-logs  #  (Archive existing log files instead of deleting them.)
---archive-downloads  #  (Archive old downloads instead of deleting them.)
+--archive-logs  # (Archive existing log files instead of deleting them.)
+--archive-downloads  # (Archive old downloads instead of deleting them.)
+--skip-js-waits  # (Skip waiting for readyState to be complete or Angular.)
 --time-limit=SECONDS  # (Safely fail any test that exceeds the time limit.)
 --slow  # (Slow down the automation. Faster than using Demo Mode.)
 --demo  # (Slow down and visually see test actions as they occur.)
@@ -499,7 +501,7 @@ The code above will leave your browser window open in case there's a failure. (i
 --dashboard  # (Enable the SeleniumBase Dashboard. Saved at: dashboard.html)
 --dash-title=STRING  # (Set the title shown for the generated dashboard.)
 --swiftshader  # (Use Chrome's "--use-gl=swiftshader" feature.)
---incognito  #  (Enable Chrome's Incognito mode.)
+--incognito  # (Enable Chrome's Incognito mode.)
 --guest  # (Enable Chrome's Guest mode.)
 --devtools  # (Open Chrome's DevTools when the browser opens.)
 --reuse-session | --rs  # (Reuse the browser session between tests.)

help_docs/ReadMe.md

@@ -10,7 +10,7 @@
 <a href="https://seleniumbase.io/examples/ReadMe/">✅ Examples</a> |
 <a href="https://seleniumbase.io/help_docs/mobile_testing/">📱 Mobile</a>
 <br />
-<a href="https://seleniumbase.io/help_docs/syntax_formats/">📝 Formats</a> |
+<a href="https://seleniumbase.io/help_docs/syntax_formats/">📝 Syntax Formats</a> |
 <a href="https://seleniumbase.io/integrations/github/workflows/ReadMe/">🤖 CI/CD</a>
 <br />
 <a href="https://seleniumbase.io/help_docs/method_summary/">📙 APIs</a> |
@@ -21,16 +21,16 @@
 <a href="https://seleniumbase.io/seleniumbase/utilities/selenium_grid/ReadMe/">🌐 Grid</a>
 <br />
 <a href="https://github.com/seleniumbase/SeleniumBase/tree/master/examples/boilerplates">♻️ Boilerplates</a> |
-<a href="https://seleniumbase.io/help_docs/locale_codes/">🗾 Locales</a>
+<a href="https://seleniumbase.io/help_docs/locale_codes/">🗾 Locale Codes</a>
 <br />
-<a href="https://seleniumbase.io/help_docs/js_package_manager/">🕹️ JSManager</a> |
-<a href="https://seleniumbase.io/examples/visual_testing/ReadMe/">🖼️ VisualTest</a>
-<br />
-<a href="https://seleniumbase.io/help_docs/translations/">🈺 Translate</a> |
-<a href="https://seleniumbase.io/examples/dialog_boxes/ReadMe/">🛂 DialogBoxes</a>
+<a href="https://seleniumbase.io/help_docs/js_package_manager/">🕹️ JS Manager</a> |
+<a href="https://seleniumbase.io/examples/visual_testing/ReadMe/">🖼️ Visual Testing</a>
 <br />
 <a href="https://seleniumbase.io/help_docs/recorder_mode/">🔴 Recorder</a> |
-<a href="https://github.com/seleniumbase/SeleniumBase/tree/master/integrations/node_js">🏃 NodeRunner</a>
+<a href="https://github.com/seleniumbase/SeleniumBase/tree/master/integrations/node_js">🚉 Node GUI</a>
+<br />
+<a href="https://seleniumbase.io/help_docs/translations/">🈺 Translator</a> |
+<a href="https://seleniumbase.io/examples/dialog_boxes/ReadMe/">🛂 Dialog Boxes</a>
 <br />
 <a href="https://seleniumbase.io/examples/presenter/ReadMe/">🎞️ Slides</a> |
 <a href="https://seleniumbase.io/examples/chart_maker/ReadMe/">📊 Charts</a>
@@ -53,9 +53,13 @@
 <div><a href="https://seleniumbase.io/seleniumbase/console_scripts/ReadMe/"><b>Console Scripts Tutorial</b></a></div>
 <div><a href="https://seleniumbase.io/examples/example_logs/ReadMe/"><b>The Dashboard</b></a></div>
 <div><a href="https://seleniumbase.io/help_docs/recorder_mode/"><b>Recorder Mode</b></a></div>
+<div><a href="https://seleniumbase.io/help_docs/commander/"><b>pytest Commander</b></a></div>
 <div><a href="https://seleniumbase.io/help_docs/syntax_formats/"><b>Syntax Formats</b></a></div>
+<div><a href="https://seleniumbase.io/examples/behave_bdd/ReadMe/"><b>Behave BDD</b></a></div>
+<div><a href="https://seleniumbase.io/help_docs/behave_gui/"><b>Behave Commander</b></a></div>
 <div><a href="https://seleniumbase.io/help_docs/mobile_testing/"><b>Mobile Device Testing</b></a></div>
 <div><a href="https://seleniumbase.io/help_docs/method_summary/"><b>Method Summary (API Ref)</b></a></div>
+<div><a href="https://seleniumbase.io/help_docs/case_plans/"><b>Case Plans</b></a></div>
 <div><a href="https://seleniumbase.io/help_docs/translations/"><b>Language Translations</b></a></div>
 <div><a href="https://seleniumbase.io/help_docs/locale_codes/"><b>Language Locale Codes</b></a></div>
 <div><a href="https://seleniumbase.io/help_docs/js_package_manager/"><b>JS Package Manager</b></a></div>
@@ -115,9 +119,13 @@
 <div><a href="https://seleniumbase.dev/seleniumbase/console_scripts/"><b>Console Scripts Tutorial</b></a></div>
 <div><a href="https://seleniumbase.dev/examples/example_logs/"><b>The Dashboard</b></a></div>
 <div><a href="https://seleniumbase.dev/help_docs/recorder_mode"><b>Recorder Mode</b></a></div>
+<div><a href="https://seleniumbase.dev/help_docs/commander"><b>pytest Commander</b></a></div>
 <div><a href="https://seleniumbase.dev/help_docs/syntax_formats"><b>Syntax Formats</b></a></div>
+<div><a href="https://seleniumbase.dev/examples/behave_bdd/"><b>Behave BDD</b></a></div>
+<div><a href="https://seleniumbase.dev/help_docs/behave_gui"><b>Behave Commander</b></a></div>
 <div><a href="https://seleniumbase.dev/help_docs/mobile_testing"><b>Mobile Device Testing</b></a></div>
 <div><a href="https://seleniumbase.dev/help_docs/method_summary"><b>Method Summary (API Ref)</b></a></div>
+<div><a href="https://seleniumbase.dev/help_docs/case_plans"><b>Case Plans</b></a></div>
 <div><a href="https://seleniumbase.dev/help_docs/translations"><b>Language Translations</b></a></div>
 <div><a href="https://seleniumbase.dev/help_docs/locale_codes"><b>Language Locale Codes</b></a></div>
 <div><a href="https://seleniumbase.dev/help_docs/js_package_manager"><b>JS Package Manager</b></a></div>

help_docs/customizing_test_runs.md

@@ -132,14 +132,16 @@ pytest my_first_test.py --settings-file=custom_settings.py
 --firefox-pref=SET  # (Set a Firefox preference:value set, comma-separated.)
 --extension-zip=ZIP  # (Load a Chrome Extension .zip|.crx, comma-separated.)
 --extension-dir=DIR  # (Load a Chrome Extension directory, comma-separated.)
+--pls=PLS  # (Set pageLoadStrategy on Chrome: "normal", "eager", or "none".)
 --headless  # (Run tests in headless mode. The default arg on Linux OS.)
 --headed  # (Run tests in headed/GUI mode on Linux OS.)
 --xvfb  # (Run tests using the Xvfb virtual display server on Linux OS.)
 --locale=LOCALE_CODE  # (Set the Language Locale Code for the web browser.)
 --interval=SECONDS  # (The autoplay interval for presentations & tour steps)
 --start-page=URL  # (The starting URL for the web browser when tests begin.)
---archive-logs  #  (Archive existing log files instead of deleting them.)
---archive-downloads  #  (Archive old downloads instead of deleting them.)
+--archive-logs  # (Archive existing log files instead of deleting them.)
+--archive-downloads  # (Archive old downloads instead of deleting them.)
+--skip-js-waits  # (Skip waiting for readyState to be complete or Angular.)
 --time-limit=SECONDS  # (Safely fail any test that exceeds the time limit.)
 --slow  # (Slow down the automation. Faster than using Demo Mode.)
 --demo  # (Slow down and visually see test actions as they occur.)
@@ -165,7 +167,7 @@ pytest my_first_test.py --settings-file=custom_settings.py
 --dashboard  # (Enable the SeleniumBase Dashboard. Saved at: dashboard.html)
 --dash-title=STRING  # (Set the title shown for the generated dashboard.)
 --swiftshader  # (Use Chrome's "--use-gl=swiftshader" feature.)
---incognito  #  (Enable Chrome's Incognito mode.)
+--incognito  # (Enable Chrome's Incognito mode.)
 --guest  # (Enable Chrome's Guest mode.)
 --devtools  # (Open Chrome's DevTools when the browser opens.)
 --reuse-session | --rs  # (Reuse the browser session between tests.)

help_docs/how_it_works.md

@@ -1,10 +1,10 @@
-## [<img src="https://seleniumbase.io/img/logo6.png" title="SeleniumBase" width="32">](https://github.com/seleniumbase/SeleniumBase/) How SeleniumBase Works:
+## [<img src="https://seleniumbase.io/img/logo6.png" title="SeleniumBase" width="32">](https://github.com/seleniumbase/SeleniumBase/) How SeleniumBase Works 👁️
 
 <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), 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.
 
-(NOTE: pytest uses a feature called test discovery to automatically find and run Python methods that start with "``test_``" from the file that you specified on the command line.)
+(NOTE: pytest uses a feature called test discovery to automatically find and run Python methods that start with ``test_`` from the file that you specified on the command line.)
 
 The most common way of using SeleniumBase is by inheriting BaseCase:
 
@@ -50,6 +50,33 @@ pytest offline_examples/
 pytest -k agent
 ```
 
+(See <a href="https://seleniumbase.io/help_docs/syntax_formats/">SyntaxFormats</a> for more ways of using SeleniumBase.)
+
+--------
+
+### ✅ No More Flaky Tests!
+
+<p>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>
+<img src="https://img.shields.io/badge/Flaky%20Tests%3F-%20NO%21-11BBDD.svg" alt="NO MORE FLAKY TESTS!" />
+
+**There are three layers of protection that provide reliability for tests using SeleniumBase:**
+
+* **(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.
+
+* **(3)**: SeleniumBase methods automatically wait for elements to be visible and interactable before interacting with those elements.
+
+**If you want to speed up your tests and you think the third level of protection is enough on it's own, you can use command-line options to remove the first, the second, or both of those first two levels of protection:**
+
+* ``--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()``.
+
+(NOTE: Those command-line options were added in SeleniumBase ``4.2.0``. Using both could lead to a 15% increase in test speed, but it could also lead to flaky tests, so use with caution.)
+
 --------
 
-For more ways of using SeleniumBase, see: <a href="https://seleniumbase.io/help_docs/syntax_formats/">SyntaxFormats</a>.
+<p><a href="https://github.com/seleniumbase/SeleniumBase/"><img src="https://seleniumbase.io/cdn/img/super_logo_sb.png" alt="SeleniumBase" title="SeleniumBase" width="200" /></a></p>
+<p><a href="https://pypi.python.org/pypi/seleniumbase" target="_blank"><img src="https://badge.fury.io/py/seleniumbase.svg" alt="PyPI version" /></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>

help_docs/recorder_mode.md

@@ -1,8 +1,8 @@
+## [<img src="https://seleniumbase.io/img/logo6.png" title="SeleniumBase" width="32">](https://github.com/seleniumbase/SeleniumBase/) Recorder Mode 🔴
+
 <!-- YouTube View --><a href="https://www.youtube.com/watch?v=eKN5nq7YbdM"><img src="http://img.youtube.com/vi/eKN5nq7YbdM/0.jpg" title="SeleniumBase on YouTube" width="285" /></a>
 <!-- GitHub Only --><p>(<b><a href="https://www.youtube.com/watch?v=eKN5nq7YbdM">Watch the tutorial on YouTube</a></b>)</p>
 
-## [<img src="https://seleniumbase.io/img/logo6.png" title="SeleniumBase" width="32">](https://github.com/seleniumbase/SeleniumBase/) Recorder Mode
-
 🔴 <b>SeleniumBase Recorder Mode</b> lets you record & export browser actions into test automation scripts.<br>
 
 <img src="https://seleniumbase.io/cdn/img/sb_recorder_notification.png" title="SeleniumBase" width="380">