Merge pull request robotframework#113 from emanlove/rf-s2l-documentation

Looks good to me. THanks guys. :)

Author: j1z0

BUILD.rst

@@ -64,6 +64,96 @@ To run just the unit tests, run::
 python test/run_unit_tests.py
 
 
+Testing Third-Party Packages
+----------------------------
+
+Sometimes in the process of developing and testing Selenium2Library
+one needs to determine whether or not an issue is within Selenium2Library
+or if it lies within a third-party package like Selenium or Robot Framework.
+Here are some hints for writing quick, short unit tests against Selenium
+and Robot Framework.
+
+Testing Selenium
+~~~~~~~~~~~~~~~~
+First create a test directory and create an isolated Python environment
+using virtualenv::
+
+~$ mkdir se-bug
+~$ cd se-bug
+~/se-bug$ virtualenv -p /usr/bin/python2.6 --no-site-packages clean-python26-env
+
+Activate the virtual environment::
+
+ ~/se-bug$ source clean-python26-env/bin/activate
+
+Install the version of Selenium for which you wish to test. In the following
+case we are going to check Selenium version 2.25.0.
+
+(clean-python26-env) ~/se-bug$ easy_install selenium==2.25.0
+
+Create a test file, in this case ~/se-bug/testExeJS.py::
+
+import unittest
+from selenium import webdriver
+
+class ExecuteJavascriptTestCase(unittest.TestCase):
+
+ def setUp(self):
+ self.driver = webdriver.Firefox()
+
+ def test_exe_javascript(self):
+ driver = self.driver
+ driver.get("http://www.google.com")
+ url = driver.execute_script("return [ document.location ];")
+ print('Finished')
+self.assertEqual(url[0]['href'], u"http://www.google.com/")
+
+ def tearDown(self):
+ self.driver.close()
+ 
+if __name__ == "__main__":
+ unittest.main()
+
+Breaking down this example test case we see in the setUp and tearDown
+methods we initiate and close the Firefox webdriver, respectively.
+In the one test, text_exe_javascript, we perform steps to verify or
+disprove the issue we are experiencing is with Selenium only. (In
+`this case`_ the browser was hanging after the execute_script call and
+not returning; thus I printed 'Finished' to help show where the test
+progressed to.)
+
+An important part of the above test case, and all unit tests, is the
+line "self.assertEqual(...". This is one example of the method's
+available to check for errors or failures. For example, you can check
+for trueness or falseness of a stament by using assertTrue() and
+assertFalse(). Or you can for inclusiveness and exclussiveness by using
+assertIn() and assertNotIn(), respectively. For more information about
+unittest see `Python's unittest documentation`_. The last two lines
+allow this test to be run from the command line.
+
+To run the unittest type::
+
+	(clean-python26-env) ~/se-bug$ python testExeJS.py
+
+In this example I removed the troubled selenium version and reinstalled a
+previous version, re-running the test case to verfiy selenium was the
+problem and not Selenium2Library::
+
+(clean-python26-env) ~/se-bug$ rm -Rf clean-python26-env/lib/python2.6/site-packages/selenium-2.25.0-py2.6.egg
+(clean-python26-env) ~/se-bug$ easy_install selenium==2.24.0
+(clean-python26-env) ~/se-bug$ python testExeJS.py
+Finished
+.
+----------------------------------------------------------------------
+Ran 1 test in 6.198s
+
+OK
+(clean-python26-env) ~/se-bug$
+
+If you discover an issue with Selenium it is helpful to `report it`_ to
+the Selenium developers.
+
+
 Pushing Code to GitHub
 ----------------------
 
@@ -187,3 +277,6 @@ are parsed by the reStructuredText parser. To build them, run::
 .. _downloads section on GitHub: https://github.com/rtomac/robotframework-selenium2library/downloads
 .. _PyPI: http://pypi.python.org
 .. _.pypirc file: http://docs.python.org/distutils/packageindex.html#the-pypirc-file
+.. _this case: http://code.google.com/p/selenium/issues/detail?id=4375
+.. _report it: http://code.google.com/p/selenium/issues/list
+.. _Python's unittest documentation: http://docs.python.org/library/unittest.html

INSTALL.rst

@@ -11,22 +11,35 @@ are the most restrictive, and as of now require Python 2.6 or Python 2.7.
 
 Selenium2Library depends on a few other Python libraries, including
 of course Robot Framework and Selenium. All dependencies are declared
-in setup.py. If you use pip or easy_install to install this library, the
-dependencies will be installed for you (this is recommended).
+in setup.py.
 
 
-Installing from PyPI (recommended)
-----------------------------------
+Installing using pip (recommended) or easy_install
+--------------------------------------------------
 
-Selenium2Library is available in the Python Package Index (PyPI_). To install,
-you need to have `pip`_ installed. Then run::
+Selenium2Library is available in the Python Package Index (PyPI_). It is
+recommended that you use `pip`_ to install. Using pip will ensure that
+both Selenium2Library **and** it's dependiences are installed.
+To install using pip, run::
 
 pip install robotframework-selenium2library
 
 Or alternately, if you only have `easy_install`_,::
 
 easy_install robotframework-selenium2library
 
+If you install Selenium2Library under Windows **and** you use easy_install, 
+you will need to install Selenium2Library's dependencies seperately.
+To install the dependencies, run::
+
+easy_install robotframework
+ easy_install selenium
+ easy_install decorator
+ easy_install docutils
+
+Once installation is completed, you should verify proper installation of
+Selenium2Library and it's dependencies. See `Verifying Installation` section
+below.
 
 Installing from source
 ----------------------
@@ -52,11 +65,40 @@ Using Windows installer
 -----------------------
 
 Currently, Windows installer is the only available binary installer. Just
-double-click the installer and follow the instructions.
+double-click the installer and follow the instructions. The installer is missing 
+decorator module. It must be installed either via pip or easy install, or from
+http://pypi.python.org/pypi/decorator/
 
 Selenium2Library can be uninstalled using the Programs and Features utility from
 Control Panel (Add/Remove Programs on older versions of Windows).
 
+Verifying Installation
+----------------------
+
+Once you have installed Selenium2Library it is a good idea to verify the installation. To verify installation start python::
+
+ C:\> python
+
+and then at the Python prompt type::
+
+>> import Selenium2Library
+>>
+
+If the python command line interpretor returns with another prompt ('>>' as shown above) then your installation was successful.
+
+Troubleshooting Installation
+----------------------------
+
+The most common issue with installing Selenium2Library is missing dependencies. An error like::
+
+ ImportError: No module named robot.variables
+
+indicates that you are missing the Robot Framework package. To correct this problem try typing at the prompt::
+
+ easy_install robotframework
+
+Similarly if you receive "No module named ..." error message then you have another missing dependency. To correct, use easy_install to install the missing package.
+
 
 .. _Selenium Python Bindings: http://code.google.com/p/selenium/wiki/PythonBindings
 .. _PyPI: http://code.google.com/p/selenium/wiki/PythonBindings

README.rst

@@ -17,6 +17,14 @@ but re-implemented to use Selenium 2 and WebDriver technologies.
 - Developer information is found in `BUILD.rst` file.
 
 
+Installation
+------------
+
+You can install Selenium2Library using pip, with the following command
+
+ pip install robotframework-selenium2library
+
+
 Directory Layout
 ----------------
 

demo/rundemo.py

@@ -32,9 +32,10 @@
 
 try:
  import Selenium2Library
-except ImportError:
- print 'Importing Selenium2Library module failed.'
- print 'Please make sure you have SeleniumLibrary installed.'
+except ImportError, e:
+ print 'Importing Selenium2Library module failed (%s).' % e
+ print 'Please make sure you have Selenium2Library properly installed.'
+ print 'See INSTALL.rst for troubleshooting information.'
  sys.exit(1)
 
 

src/Selenium2Library/__init__.py

@@ -94,7 +94,11 @@ def __init__(self, timeout=5.0, implicit_wait=0.0, run_on_failure='Capture Page
 
  'implicit_wait' is the implicit timeout that Selenium waits when
  looking for elements.
- It can be later set with 'Set Selenium Implicit Wait'.
+ It can be later set with `Set Selenium Implicit Wait`.
+ See `WebDriver: Advanced Usage`__ section of the SeleniumHQ documentation
+ for more information about WebDriver's implicit wait functionality.
+
+ __ http://seleniumhq.org/docs/04_webdriver_advanced.html#explicit-and-implicit-waits
 
  `run_on_failure` specifies the name of a keyword (from any available
  libraries) to execute when a Selenium2Library keyword fails. By default
@@ -104,9 +108,11 @@ def __init__(self, timeout=5.0, implicit_wait=0.0, run_on_failure='Capture Page
  functionality.
 
  Examples:
- | Library `|` Selenium2Library `|` 15 | # Sets default timeout to 15 seconds |
- | Library `|` Selenium2Library `|` 5 `|` Log Source | # Sets default timeout to 5 seconds and runs `Log Source` on failure |
- | Library `|` Selenium2Library `|` timeout=10 `|` run_on_failure=Nothing | # Sets default timeout to 10 seconds and does nothing on failure |
+ | Library `|` Selenium2Library `|` 15 | # Sets default timeout to 15 seconds |
+ | Library `|` Selenium2Library `|` 0 `|` 5 | # Sets default timeout to 0 seconds and default implicit_wait to 5 seconds |
+ | Library `|` Selenium2Library `|` 5 `|` run_on_failure=Log Source | # Sets default timeout to 5 seconds and runs `Log Source` on failure |
+ | Library `|` Selenium2Library `|` implicit_wait=5 `|` run_on_failure=Log Source | # Sets default implicit_wait to 5 seconds and runs `Log Source` on failure |
+ | Library `|` Selenium2Library `|` timeout=10 `|` run_on_failure=Nothing | # Sets default timeout to 10 seconds and does nothing on failure |
  """
  for base in Selenium2Library.__bases__:
  base.__init__(self)