Merge pull request #170 from seleniumbase/readme-updates

Update ReadMe files

Author: mdmintz

README.md

@@ -13,7 +13,7 @@ SeleniumBase simplifies Web-UI automation by extending Python's unittest framewo
 ### [**Get Started**](#seleniumbase_installation), or Learn More:
 
 **No more repetitive WebDriver code:**<br />
-SeleniumBase automatically handles common WebDriver actions such as spinning up web browsers, waiting for page objects to load, saving screenshots during test failures, and more. (<i>[Read about the command line interface](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/command_line.md).</i>)
+SeleniumBase automatically handles common WebDriver actions such as spinning up web browsers, waiting for page objects to load, saving screenshots during test failures, using a proxy server, and more. (<i>[Read about customizing test runs](https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/customizing_test_runs.md).</i>)
 
 **Simple Python syntax makes coding easy:**<br />
 
@@ -90,22 +90,22 @@ cd SeleniumBase
 
 If you're installing SeleniumBase from a cloned copy on your machine, use:
 ```
-pip install -U -r requirements.txt
+pip install -r requirements.txt
 
 python setup.py develop
 ```
 
 If you're installing SeleniumBase from the [Python Package Index](https://pypi.python.org/pypi/seleniumbase), use:
 ```bash
-pip install -U seleniumbase
+pip install seleniumbase
 ```
 
 If you're installing SeleniumBase directly from GitHub, use:
 ```bash
-pip install -U -e git+https://github.com/seleniumbase/SeleniumBase.git@master#egg=seleniumbase
+pip install -e git+https://github.com/seleniumbase/SeleniumBase.git@master#egg=seleniumbase
 ```
 
-(If you encounter permission errors during installation while not using a virtual environment, you may need to add ``--user`` to your ``pip`` command.)
+(If you encounter permission errors during installation while not using a virtual environment, you may need to add ``--user`` to your pip command. If you already have an older version of SeleniumBase installed, you may want to add ``--upgrade`` or ``-U`` to your pip command.)
 
 
 <a id="seleniumbase_basic_usage"></a>

examples/ReadMe.md

@@ -1,6 +1,6 @@
 ## Running SeleniumBase Scripts
 
-(NOTE: If you didn't install SeleniumBase properly, these scripts won't work. Installation steps include "``pip install seleniumbase``" and/or "``python setup.py develop``" from the top-level directory.)
+(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 makes things easier, here's a simple GUI program that allows you to kick off a few example scripts by pressing a button:
 
@@ -10,7 +10,7 @@ python gui_test_runner.py
 
 (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.)
 
-(NOTE: You can interchange ``nosetests`` with ``pytest`` in most of these examples.)
+(NOTE: You can interchange ``pytest`` with ``nosetests`` in most of these examples.)
 
 <img src="https://cdn2.hubspot.net/hubfs/100006/images/The_GUI_Runner.png" title="GUI Test Runner" height="400">
 
@@ -35,12 +35,12 @@ pytest my_first_test.py --browser=chrome --demo_mode
 
 Run the example test suite in Chrome and generate an html report: (nosetests-only)
 ```bash
-nosetests my_test_suite.py --browser=chrome --report
+nosetests my_test_suite.py --browser=chrome --report --show_report
 ```
 
 Run the example test suite in Firefox and generate an html report: (nosetests-only)
 ```bash
-nosetests my_test_suite.py --browser=firefox --report
+nosetests my_test_suite.py --browser=firefox --report --show_report
 ```
 
 Run a test with configuration specifed by a config file:
@@ -50,17 +50,19 @@ nosetests my_first_test.py --config=example_config.cfg
 
 Run a test demonstrating the use of Python decorators available:
 ```bash
-nosetests rate_limiting_test.py
+pytest rate_limiting_test.py
 ```
 
 Run a failing test with pdb mode enabled: (If a test failure occurs, test enters pdb mode)
 ```bash
-nosetests test_fail.py --browser=chrome --pdb --pdb-failures
+pytest test_fail.py --browser=chrome --pdb --pdb-failures
 ```
 
 Run a failing test (and then look into the ``latest_logs`` folder afterwards:
 ```bash
 pytest test_fail.py --browser=chrome
 ```
 
+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)
+
 (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.)

help_docs/command_line.md renamed to help_docs/customizing_test_runs.md

@@ -1,4 +1,4 @@
-### The Command Line Interface
+### Customizing test runs from the command line
 
 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:
 
@@ -21,7 +21,7 @@ pytest my_first_test.py
 
 pytest my_first_test.py --demo_mode --browser=chrome
 
-nosetests my_first_test.py --browser=firefox
+pytest my_first_test.py --browser=firefox
 
 pytest basic_script.py -s --pdb --pdb-failures
 
@@ -49,15 +49,15 @@ pytest my_test_suite.py --browser=chrome
 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:
 
 ```bash
-nosetests my_first_test.py --browser=chrome --demo_mode
+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
-nosetests my_first_test.py --browser=chrome --demo_mode --demo_sleep=1.2
+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:**
@@ -73,7 +73,7 @@ You may also want to have your test sleep in other situations where you need to
 **If you need to debug things on the fly (in case of errors), use this:**
 
 ```bash
-nosetests my_first_test.py --browser=chrome --pdb --pdb-failures -s
+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.

integrations/google_cloud/ReadMe.md

@@ -11,7 +11,7 @@
 
 ![](http://cdn2.hubspot.net/hubfs/100006/images/gcp_cloud_launcher_jenkins_3.png "Finding Jenkins")
 
-* Under "Cloud Launcher", Click on "Jenkins"
+* Under "Cloud Launcher", Click on "Jenkins Certified by Bitnami"
 * Click on "Launch on Compute Engine"
 * Give the instance a name
 * Give the instance a zone
@@ -76,7 +76,7 @@ sudo pip install -r requirements.txt --upgrade
 #### Step 12. Install SeleniumBase (Make sure you already installed the requirements above)
 
 ```bash
-sudo python server_setup.py develop
+sudo python setup.py develop
 ```
 
 #### Step 13. Run an [example test](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/my_first_test.py) in Chrome to verify installation (Takes ~10 seconds)

integrations/katalon/ReadMe.md

@@ -0,0 +1 @@
+## This page has been moved to: [../selenium_ide/ReadMe.md](https://github.com/seleniumbase/SeleniumBase/blob/master/integrations/selenium_ide/ReadMe.md)

integrations/selenium_ide/ReadMe.md

@@ -1,14 +1,14 @@
-## Converting Selenium IDE recordings into SeleniumBase test scripts
+## Converting Katalon-based Selenium IDE recordings into SeleniumBase test scripts
 
-[Selenium IDE](http://docs.seleniumhq.org/projects/ide/) is a tool that allows you to record and playback actions performed inside a web browser. It's available as a [downloadable Firefox extension](https://addons.mozilla.org/en-US/firefox/addon/selenium-ide/). Selenium IDE comes with an option to export recordings as various WebDriver test scripts, one of which is ``Python2/unittest/WebDriver``. Unfortunately, these natively-exported scripts tend to be very messy and don't run reliably. The purpose of this converter is to clean up and improve the scripts so that they can be used in production-level environments.
+[Katelon Recorder / Selenium IDE](https://www.katalon.com/resources-center/blog/katalon-automation-recorder/) (<i>the successor to the [old Selenium IDE](http://docs.seleniumhq.org/projects/ide/)</i>) is a tool that allows you to record and playback actions performed inside a web browser. It's available as a [downloadable Chrome extension](https://chrome.google.com/webstore/detail/katalon-recorder-selenium/ljdobmomdgdljniojadhoplhkpialdid) and a [downloadable Firefox extension](https://addons.mozilla.org/en-US/firefox/addon/katalon-automation-record/). Katelon Recorder comes with an option to export recordings as various WebDriver test scripts, one of which is ``Python 2 (WebDriver + unittest)``. Unfortunately, these natively-exported scripts can be very messy and don't always run reliably. The purpose of this converter is to clean up and improve the scripts so that they can be used in production-level environments.
 
-#### Step 1: Make a recording with Selenium IDE
+#### Step 1: Make a recording with Katelon Recorder
 
-![](https://cdn2.hubspot.net/hubfs/100006/selenium_ide_example_b.png "Selenium IDE example")
+![](https://cdn2.hubspot.net/hubfs/100006/images/katalon_recorder_2.png "Katelon Recorder example")
 
 #### Step 2: Export your recording as a Python 2 Webdriver script
 
-* ``File`` => ``Export Test Case As`` => ``Python 2 / unittest / WebDriver``
+* ``{} Export`` => ``Python 2 (WebDriver + unittest)`` => ``Save As File``
 
 #### Step 3: Drop your exported file into the ``selenium_ide`` folder