Update multiple ReadMe files

mdmintz · mdmintz · commit c5f8018d7865 · 2018-07-31T14:47:10.000-04:00
diff --git a/README.md b/README.md
@@ -63,7 +63,7 @@ SeleniumBase was originally built for [testing HubSpot's platform](https://produ
 
 ## Get Started:
 
-Before installation, **[install Python](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/install_python_pip_git.md)** and **[get a WebDriver](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/webdriver_installation.md)** on your system PATH.
+Before installation, **[install Python](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/install_python_pip_git.md)** and **[install a web driver](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/webdriver_installation.md)**.
 
 
 ### ![http://seleniumbase.com](https://cdn2.hubspot.net/hubfs/100006/images/super_logo_tiny.png "SeleniumBase") **Step 1:** Clone SeleniumBase
@@ -151,32 +151,23 @@ If the example test is moving too fast for your eyes to see what's going on, you
 pytest my_first_test.py --demo_mode
 ```
 
-You can override the default wait time by either updating [settings.py](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/config/settings.py) or by using ``--demo_sleep={NUM}`` when using Demo Mode. (NOTE: If you use ``--demo_sleep={NUM}`` without using ``--demo_mode``, nothing will happen.)
-
-```bash
-pytest my_first_test.py --demo_mode --demo_sleep=1.2
-```
-
-You can also use the following in your scripts to slow down the tests:
+You can use the following in your scripts to help you debug issues::
 
 ```python
 import time; time.sleep(5)  # sleep for 5 seconds (add this after the line you want to pause on)
 import ipdb; ipdb.set_trace()  # waits for your command. n = next line of current method, c = continue, s = step / next executed line (will jump)
+import pytest; pytest.set_trace()  # similar to ipdb, but specific to pytest
 ```
 
-(NOTE: If you're using pytest instead of nosetests and you want to use ipdb in your script for debugging purposes, you'll need to add ``--capture=no`` (or ``-s``) on the command line, or use ``import pytest; pytest.set_trace()`` instead of using ipdb. More info on that [here](http://stackoverflow.com/questions/2678792/can-i-debug-with-python-debugger-when-using-py-test-somehow).)
-
-You may also want to have your test sleep in other situations where you need to have your test wait for something. If you know what you're waiting for, you should be specific by using a command that waits for something specific to happen.
-
-If you need to debug things on the fly (in case of errors), use this:
+**To pause an active test that throws an exception or error, add ``--pdb --pdb-failures -s``:**
 
 ```bash
 pytest my_first_test.py --browser=chrome --pdb --pdb-failures -s
 ```
 
-The above code (with --pdb) will leave your browser window open in case there's a failure, which is possible if the web pages from the example change the data that's displayed on the page. (ipdb commands: 'c', 's', 'n' => continue, step, next). You may need the ``-s`` in order to see all console output.
+The code above will leave your browser window open in case there's a failure. (ipdb commands: 'c', 's', 'n' => continue, step, next).
 
-Here are some other useful nosetest arguments for appending to your run commands:
+Here are some other useful **nosetest**-specific arguments:
 
 ```bash
 --logging-level=INFO  # Hide DEBUG messages, which can be overwhelming.
@@ -185,7 +176,7 @@ Here are some other useful nosetest arguments for appending to your run commands
 --with-id  # If -v is also used, will number the tests for easy counting.
 ```
 
-During test failures you'll get detailed log files, which include screenshots, page source, and basic test info, which will get added to the logs folder at ``latest_logs/``. (Unless you have ARCHIVE_EXISTING_LOGS set to True in [settings.py](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/config/settings.py), log files with be cleaned up at the start of the next test run. If the archive feature is enabled, those logs will get saved to the ``archived_logs/`` folder.) The ``my_test_suite.py`` collection contains tests that fail on purpose so that you can see how logging works.
+During test failures, logs and screenshots from the most recent test run will get saved to the ``latest_logs/`` folder. Those logs will get moved to ``archived_logs/`` if you have ARCHIVE_EXISTING_LOGS set to True in [settings.py](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/config/settings.py), otherwise log files with be cleaned up at the start of the next test run. The ``my_test_suite.py`` collection contains tests that fail on purpose so that you can see how logging works.
 
 ```bash
 cd examples/
@@ -210,7 +201,7 @@ To run Pytest multithreaded on multiple CPUs at the same time, add ``-n=NUM`` or
 <a id="creating_visual_reports"></a>
 ### ![http://seleniumbase.com](https://cdn2.hubspot.net/hubfs/100006/images/super_logo_tiny.png "SeleniumBase") **Creating Visual Test Suite Reports:**
 
-(NOTE: The command line args are different for Pytest vs Nosetests)
+(NOTE: Several command line args are different for Pytest vs Nosetests)
 
 #### **Pytest Reports:**
 
diff --git a/console_scripts/ReadMe.md b/console_scripts/ReadMe.md
@@ -1,10 +1,32 @@
 ## Console Scripts
 
+SeleniumBase console scripts help you get things done more easily, such as installing web drivers, creating a test directory with necessary configuration files, converting old Webdriver unittest scripts into SeleniumBase code, and using the Selenium Grid.
+
+For running tests from the command line, [use **pytest** with SeleniumBase](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/customizing_test_runs.md).
+
+### install
+
+* Usage:
+``seleniumbase install [DRIVER_NAME]``
+        (Drivers: chromedriver, geckodriver, edgedriver)
+
+* Example:
+``seleniumbase install chromedriver``
+
+* Output:
+Installs the specified webdriver.
+(chromedriver is required for Google Chrome automation)
+(geckodriver is required for Mozilla Firefox automation)
+(edgedriver is required for Microsoft Edge automation)
+
 ### mkdir
 
 * Usage:
 ``seleniumbase mkdir [DIRECTORY_NAME]``
 
+* Example:
+``seleniumbase mkdir gui_tests``
+
 * Output:
 Creates a new folder for running SeleniumBase scripts.
 The new folder contains default config files,
@@ -15,7 +37,7 @@ test frameworks.
 ### convert
 
 * Usage:
-``seleniumbase convert [MY_TEST.py]``
+``seleniumbase convert [PYTHON_WEBDRIVER_UNITTEST_FILE]``
 
 * Output:
 Converts a Selenium IDE exported WebDriver unittest
diff --git a/examples/ReadMe.md b/examples/ReadMe.md
@@ -1,22 +1,14 @@
 ## Running SeleniumBase Scripts
 
-(NOTE: If you didn't install SeleniumBase properly, these scripts won't work. Installation steps include ``pip install seleniumbase`` OR ``pip install -r requirements.txt`` + ``python setup.py develop``" from the top-level directory.)
+To run tests, make sure you've already installed SeleniumBase using ``pip install seleniumbase`` OR ``pip install -r requirements.txt`` + ``python setup.py develop`` from the top-level directory.
 
-To makes things easier, here's a simple GUI program that allows you to kick off a few example scripts by pressing a button:
-
-```bash
-python gui_test_runner.py
-```
+You can interchange **pytest** with **nosetests**, but using pytest is strongly recommended because developers stopped supporting nosetests. Chrome is the default browser if not specified.
 
-(NOTE: With the exception of [my_first_test.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/my_first_test.py), which should pass, many other tests in this folder fail on purpose to demonstrate features such as screenshots on failure, exception logging, and test reports.)
+During test failures, logs and screenshots from the most recent test run will get saved to the ``latest_logs/`` folder. Those logs will get moved to ``archived_logs/`` if you have ARCHIVE_EXISTING_LOGS set to True in [settings.py](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/config/settings.py)
 
-(NOTE: You can interchange ``pytest`` with ``nosetests`` in most of these examples.)
+(NOTE: Many tests in this folder fail on purpose to demonstrate the built-in logging, screenshots, and reporting features.)
 
-<img src="https://cdn2.hubspot.net/hubfs/100006/images/The_GUI_Runner.png" title="GUI Test Runner" height="400">
-
-When you run tests, you’ll see two folders appear: “latest_logs” and “archived_logs”. The “latest_logs” folder will contain log files from the most recent test run, but logs will only be created if the test run is failing. Afterwards, logs from the “latest_logs” folder will get pushed to the “archived_logs” folder if you have have the ``ARCHIVE_EXISTING_LOGS`` feature enabled in [settings.py](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/config/settings.py).
-
-**For running scripts the usual way, here are some of the example run commands:**
+**Here are some example run commands to help get you started:**
 
 Run the example test in Chrome:
 ```bash
@@ -28,41 +20,51 @@ Run the example test in Firefox:
 pytest my_first_test.py --browser=firefox
 ```
 
-Run the example test in Demo Mode (runs slower and adds highlights):
+Run the example test in Demo Mode (highlights page objects being acted on):
 ```bash
 pytest my_first_test.py --browser=chrome --demo_mode
 ```
 
-Run the example test suite in Chrome and generate an html report: (nosetests-only)
+Run the example test suite and generate an pytest report: (pytest-only)
 ```bash
-nosetests my_test_suite.py --browser=chrome --report --show_report
+pytest basic_script.py --html=report.html
 ```
 
-Run the example test suite in Firefox and generate an html report: (nosetests-only)
+Run the example test suite and generate a nosetest report: (nosetests-only)
 ```bash
-nosetests my_test_suite.py --browser=firefox --report --show_report
+nosetests my_test_suite.py --report --show_report
 ```
 
-Run a test with configuration specifed by a config file:
+Run a test using a nosetest configuration file: (nosetests-only)
 ```bash
 nosetests my_first_test.py --config=example_config.cfg
 ```
 
-Run a test demonstrating the use of Python decorators available:
+Run a test demonstrating the use of SeleniumBase Python decorators available:
 ```bash
 pytest rate_limiting_test.py
 ```
 
-Run a failing test with pdb mode enabled: (If a test failure occurs, test enters pdb mode)
+Run a failing test: (See the ``latest_logs/`` folder afterwards for logs and screenshots)
 ```bash
-pytest test_fail.py --browser=chrome --pdb --pdb-failures
+pytest test_fail.py --browser=chrome
 ```
 
-Run a failing test (and then look into the ``latest_logs`` folder afterwards:
+Run a failing test with Debugging-mode enabled: (If a test failure occurs, pdb activates)
 ```bash
-pytest test_fail.py --browser=chrome
+pytest test_fail.py --browser=chrome --pdb --pdb-failures -s
 ```
 
 For more advanced run commands, such as using a proxy server,  see [../help_docs/customizing_test_runs.md](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/customizing_test_runs.md)
 
+--------
+
+To makes things easier, here's a simple GUI program that allows you to kick off a few example scripts by pressing a button:
+
+```bash
+python gui_test_runner.py
+```
+
+<img src="https://cdn2.hubspot.net/hubfs/100006/images/The_GUI_Runner.png" title="GUI Test Runner" height="400">
+
 (NOTE: If you see any ``*.pyc`` files appear as you run tests, that's perfectly normal. Compiled bytecode is a natural result of running Python code.)
diff --git a/help_docs/customizing_test_runs.md b/help_docs/customizing_test_runs.md
@@ -1,20 +1,22 @@
-### Customizing test runs from the command line
+### Customizing test runs with **pytest** (or nosetests)
 
-In addition to [settings.py](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/config/settings.py), which allows you to customize the test framework, SeleniumBase gives you the flexibility to customize & control test runs from the command line:
+In addition to [settings.py](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/config/settings.py) (which lets you customize SeleniumBase global properties) you can customize test runs from the command line:
 
-* Set the browser for tests to use (Default: Chrome)
-* Change the automation speed (with Demo Mode)
+* Choose the browser for tests to use (Default: Chrome)
 * Choose betweeen pytest & nose unittest runners
-* Specify what to log and where to store logs
-* Choose additional variables to pass into tests
 * Choose whether to enter Debug Mode on failures
-* Specify a proxy server to connect to
-* Choose a database to save results to
+* Choose additional variables to pass into tests
+* Change the automation speed (with Demo Mode)
+* Choose whether to run tests multi-threaded
 * Choose a Selenium Grid to connect to
+* Choose a database to save results to
+* Choose a proxy server to connect to
 
 ...and more!
 
-**Examples:** (These are run from the **[examples](https://github.com/seleniumbase/SeleniumBase/tree/master/examples)** folder.):
+#### **Examples:**
+
+(These are run from the **[examples](https://github.com/seleniumbase/SeleniumBase/tree/master/examples)** folder.)
 
 ```bash
 pytest my_first_test.py
@@ -25,67 +27,64 @@ pytest my_first_test.py --browser=firefox
 
 pytest basic_script.py -s --pdb --pdb-failures
 
-pytest my_test_suite.py --server=IP_ADDRESS -n 4
-
 pytest basic_script.py --html=report.html
 
 nosetests my_test_suite.py --report --show_report
 
+pytest my_test_suite.py --server=IP_ADDRESS -n 4
+
 pytest my_test_suite.py --proxy=IP_ADDRESS:PORT
 ```
 
-You can interchange **nosetests** with **pytest**. Chrome is the default browser if not specified. The ``-s`` option may produce additional output to make debugging easier.
+You can interchange **pytest** with **nosetests**, but using pytest is strongly recommended because developers stopped supporting nosetests. Chrome is the default browser if not specified.
 
 (NOTE: If you're using **pytest** for running tests outside of the SeleniumBase repo, **you'll want a copy of [pytest.ini](https://github.com/seleniumbase/SeleniumBase/blob/master/pytest.ini) at the base of the new folder structure**. If using **nosetests**, the same applies for [setup.cfg](https://github.com/seleniumbase/SeleniumBase/blob/master/setup.cfg).)
 
-**Example tests using Logging**:
+#### **Example tests using Logging:**
+
 ```bash
 pytest my_test_suite.py --browser=chrome
 ```
-(NOTE: You'll automatically get full logging on test failures, which include screenshots, page source, and basic test info in the logs folder, which is ``latest_logs/`` initially, and those logs will be saved in ``archived_logs/`` if you have ARCHIVE_EXISTING_LOGS set to True in [settings.py](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/config/settings.py))
+(During test failures, logs and screenshots from the most recent test run will get saved to the ``latest_logs/`` folder. Those logs will get moved to ``archived_logs/`` if you have ARCHIVE_EXISTING_LOGS set to True in [settings.py](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/config/settings.py), otherwise log files with be cleaned up at the start of the next test run.)
 
-**Demo Mode:**
+#### **Demo Mode:**
 
-If any test is moving too fast for your eyes to see what's going on, you can run it in **Demo Mode** by adding ``--demo_mode`` on the command line, which pauses the browser briefly between actions, and highlights page elements being acted on:
+If any test is moving too fast for your eyes to see what's going on, you can run it in **Demo Mode** by adding ``--demo_mode`` on the command line, which pauses the browser briefly between actions, highlights page elements being acted on, and lets you know what test assertions are happening in real time:
 
 ```bash
 pytest my_first_test.py --browser=chrome --demo_mode
 ```
 
 You can override the default wait time by either updating [settings.py](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/config/settings.py) or by using ``--demo_sleep={NUM}`` when using Demo Mode. (NOTE: If you use ``--demo_sleep={NUM}`` without using ``--demo_mode``, nothing will happen.)
 
-If you ever make any changes to your local copy of ``settings.py``, you may need to run ``python setup.py install`` for those changes to take effect.
-
 ```bash
 pytest my_first_test.py --browser=chrome --demo_mode --demo_sleep=1.2
 ```
 
-**You can also use the following in your scripts to slow down the tests:**
+#### **Passing additional data to tests:**
+
+If you want to pass additional data from the command line to your tests, you can use ``--data=STRING``. Now inside your tests, you can use ``self.data`` to access that.
+
+#### **Running tests multithreaded:**
+
+To run Pytest multithreaded on multiple CPUs at the same time, add ``-n=NUM`` or ``-n NUM`` on the command line, where NUM is the number of CPUs you want to use.
+
+#### **Debugging tests:**
+
+**You can use the following code snippets in your scripts to help you debug issues:**
 ```python
 import time; time.sleep(5)  # sleep for 5 seconds (add this after the line you want to pause on)
 import ipdb; ipdb.set_trace()  # waits for your command. n = next line of current method, c = continue, s = step / next executed line (will jump)
+import pytest; pytest.set_trace()  # similar to ipdb, but specific to pytest
 ```
 
-(NOTE: If you're using pytest instead of nosetests and you want to use ipdb in your script for debugging purposes, you'll either need to add ``--capture=no`` on the command line, or use ``import pytest; pytest.set_trace()`` instead of using ipdb. More info on that [here](http://stackoverflow.com/questions/2678792/can-i-debug-with-python-debugger-when-using-py-test-somehow).)
-
-You may also want to have your test sleep in other situations where you need to have your test wait for something. If you know what you're waiting for, you should be specific by using a command that waits for something specific to happen.
-
-**If you need to debug things on the fly (in case of errors), use this:**
+**To pause an active test that throws an exception or error, add ``--pdb --pdb-failures -s``:**
 
 ```bash
 pytest my_first_test.py --browser=chrome --pdb --pdb-failures -s
 ```
 
-The above code (with --pdb) will leave your browser window open in case there's a failure, which is possible if the web pages from the example change the data that's displayed on the page. (ipdb commands: 'c', 's', 'n' => continue, step, next). You may need the ``-s`` in order to see all console output.
-
-**Here are some other useful nosetest arguments for appending to your run commands:**
-
-```bash
---logging-level=INFO  # Hide DEBUG messages, which can be overwhelming.
--x  # Stop running the tests after the first failure is reached.
--v  # Prints the full test name rather than a dot for each test.
---with-id  # If -v is also used, will number the tests for easy counting.
-```
+The code above will leave your browser window open in case there's a failure. (ipdb commands: 'c', 's', 'n' => continue, step, next).
 
 #### **Pytest Reports:**
 
@@ -107,6 +106,15 @@ nosetests my_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.)
 
+Here are some other useful **nosetest**-specific arguments:
+
+```bash
+--logging-level=INFO  # Hide DEBUG messages, which can be overwhelming.
+-x  # Stop running the tests after the first failure is reached.
+-v  # Prints the full test name rather than a dot for each test.
+--with-id  # If -v is also used, will number the tests for easy counting.
+```
+
 #### **Using a Proxy Server:**
 
 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.
diff --git a/help_docs/webdriver_installation.md b/help_docs/webdriver_installation.md
