diff --git a/INSTALL.rst b/INSTALL.rst deleted file mode 100644 index 8cd55209b..000000000 --- a/INSTALL.rst +++ /dev/null @@ -1,137 +0,0 @@ -Selenium2Library Installation -============================= - - -This document is currently out of date. If you need to install the latest -stable version, then run:: - - pip install robotframework-selenium2library - -If you need the alpha release, which supports Python 2 and 3, then run:: - - pip install -U --pre robotframework-seleniumlibrary - -The documentation will be fixed when the robotframework-seleniumlibrary -is released. - -Preconditions -------------- - -Selenium2Library supports almost all Python interpreters supported by the -Robot Framework and the `Selenium Python Bindings`_. The Selenium2Library -requires Python 2.7 or Python 3.3+. String from release 3.0.0, the Python -2.6 is not anymore supported. - -Selenium2Library depends on Robot Framework and Selenium. All dependencies are -declared in `requirements.txt`_ with their minimum required versions. With the -Selenium it might be possible that the Selenium2Library supports older versions, -but older Selenium version are not tested by the development team. - -Selenium needs a browser specific driver to downloaded and placed in the -operating system PATH variable. For more details about supported drivers and -their downloads can be found from the selenium documentation: -https://seleniumhq.github.io/selenium/docs/api/py/index.html#drivers - -Installing using pip --------------------- - -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 - -The main benefit of using `pip` is that it automatically installs all -dependencies needed by the library. Other nice features are easy upgrading -and support for un-installation:: - - pip install --upgrade robotframework-selenium2library - pip uninstall robotframework-selenium2library - -Notice that using ``--upgrade`` above updates both the library and all -its dependencies to the latest version. If you want, you can also install -a specific version or upgrade only the Selenium tool used by the library:: - - pip install robotframework-selenium2library==1.8.0 - pip install --upgrade selenium - pip install selenium==3.4.2 - -Once installation is completed, you should verify proper installation of -Selenium2Library and it's dependencies. See `Verifying Installation` section -below. - -Proxy configuration -------------------- - -If you are behind a proxy, you can use ``--proxy`` command line option -or set ``http_proxy`` and/or ``https_proxy`` environment variables to -configure ``pip`` to use it. If you are behind an authenticating NTLM proxy, -you may want to consider installing `CNTML `__ -to handle communicating with it. - -For more information about ``--proxy`` option and using pip with proxies -in general see: - -- https://pip.pypa.io/en/stable/ -- http://stackoverflow.com/questions/9698557/how-to-use-pip-on-windows-behind-an-authenticating-proxy -- http://stackoverflow.com/questions/14149422/using-pip-behind-a-proxy - - -Installing from source ----------------------- - -The source code can be retrieved either as a source distribution or as a clone -of the main source repository. The installer requires Python version 2.7 or -Python 3.3+. Install by running:: - - python setup.py install - -Or, if you'd like to automatically install dependencies, run:: - - python setup.py develop - -Note: In most linux systems, you need to have root privileges for installation. - -Uninstallation is achieved by deleting the installation directory and its -contents from the file system. The default installation directory is -`[PythonLibraries]/site-packages/Selenium2Library`. - -With resent versions of `pip` it is possible to perform the installation -directly from the Selenium2Library GitHub repository. For more details about -the `pip` vcs support, please refer to the pip documentation: -https://pip.pypa.io/en/stable/reference/pip_install/#vcs-support - -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:: - - pip install robotframework - -Similarly if you receive "No module named ..." error message then you have another missing dependency. To correct, use pip to install the missing package. - - -.. _Selenium Python Bindings: https://github.com/SeleniumHQ/selenium/wiki/Python-Bindings -.. _PyPI: https://pypi.python.org/pypi -.. _pip: http://www.pip-installer.org -.. _easy_install: http://pypi.python.org/pypi/setuptools -.. _requirements.txt: https://github.com/robotframework/Selenium2Library/blob/master/requirements.txt diff --git a/README.rst b/README.rst index c65bf0b53..b7d4c7a7e 100644 --- a/README.rst +++ b/README.rst @@ -7,17 +7,18 @@ SeleniumLibrary Introduction ------------ -SeleniumLibrary_ is a web testing library for `Robot Framework`_ -that utilizes the Selenium_ tool internally. See `keyword documentation`_ +SeleniumLibrary_ is a web testing library for `Robot Framework`_ that +utilizes the Selenium_ tool internally. The project is hosted on GitHub_ +and downloads can be found from PyPI_. See `keyword documentation`_ for available keywords and more information about the library in general. -SeleniumLibrary requires Selenium 2.53.6 or newer. It works with Python 2.7 -as well as with Python 3.3 or newer. +SeleniumLibrary works with Selenium 2.53.6 or newer, including Selenium 3. +It supports Python 2.7 as well as Python 3.3 or newer. SeleniumLibrary is based on the `old SeleniumLibrary`_ that was forked to Selenium2Library_ and then later renamed back to SeleniumLibrary. -See the `History`_ section below for more information about different -versions. +See the Versions_ and History_ sections below for more information about +different versions and the overall project history. The new SeleniumLibrary is currently in pre-release phase. The final SeleniumLibrary 3.0 release is planned for early September. @@ -38,6 +39,8 @@ The recommended installation method is using pip_:: pip install --pre --upgrade robotframework-seleniumlibrary +Running this command installs also the latest Selenium and Robot Framework +versions, but you still need to install `browser drivers`_ separately. Notice that the ``--pre`` option is needed to get the current SeleniumLibrary, not the `old SeleniumLibrary`_, until the final SeleniumLibrary 3.0 is released. The ``--upgrade`` option can be omitted when installing the @@ -57,7 +60,36 @@ To install the last legacy Selenium2Library_ version, use this command instead:: pip install robotframework-selenium2library==1.8.0 -See `INSTALL.rst`_ for more details about installation. +An alternative to using ``pip`` is getting the project source code either +from a source distribution at PyPI_ or by cloning the GitHub_ repository, +and installing the code using ``python setup.py install``. This approach +does not install Selenium or other dependencies, so they need to be installed +separately. + +See `Robot Framework installation instructions`_ for detailed information +about installing Python and Robot Framework itself. For more details about +using ``pip`` see `its own documentation `__. + +Browser drivers +--------------- + +After installing the library, you still need to install browser and +operating system specific browser drivers for all those browsers you +want to use in tests. These are the exact same drivers you need to use with +Selenium also when not using SeleniumLibrary. More information about +drivers can be found from `Selenium documentation`__. + +The general approach to install a browser driver is downloading a right +driver, such as ``chromedriver`` for Chrome, and placing it into +a directory that is in PATH__. Drivers for different browsers +can be found via Selenium documentation or by using your favorite +search engine with a search term like ``selenium chrome browser driver``. +New browser driver versions are released to support features in +new browsers, fix bug, or otherwise, and you need to keep an eye on them +to know when to update drivers you use. + +__ https://seleniumhq.github.io/selenium/docs/api/py/index.html#drivers +__ https://en.wikipedia.org/wiki/PATH_(variable) Usage ----- @@ -136,6 +168,26 @@ available: requests - `Other support forums`_ including paid support +Versions +-------- + +SeleniumLibrary has over the years lived under SeleniumLibrary and +Selenium2Library names and different library versions have supported +different Selenium and Python versions. This is summarized in the table +below and the History_ section afterwards explains the project history +a bit more. + +================================== ================ =================== =============== + Project Selenium Version Python Version Comment +================================== ================ =================== =============== +SeleniumLibrary 2.9.2 and earlier Selenium 1 and 2 Python 2.5-2.7 The original SeleniumLibrary using Selenium RC API. +Selenium2Library 1.8.0 and earlier Selenium 2 and 3 Python 2.6-2.7 Fork of SeleniumLibrary using Selenium WebDriver API. +SeleniumLibrary 3.0 and newer Selenium 2 and 3 Python 2.7 and 3.3+ Selenium2Library renamed and with Python 3 support and new architecture. +Selenium2Library 3.0 and newer Selenium 2 and 3 Python 2.7 and 3.3+ Thin wrapper for SeleniumLibrary 3.0 to ease transition. +================================== ================ =================== =============== + +The only project that is developed further is SeleniumLibrary 3. + History ------- @@ -181,11 +233,12 @@ project. .. _Selenium2Library: https://github.com/robotframework/Selenium2Library .. _Old SeleniumLibrary: https://github.com/robotframework/OldSeleniumLibrary .. _pip: http://pip-installer.org +.. _PyPI: https://pypi.python.org +.. _GitHub: https://github.com/robotframework/SeleniumLibrary .. _Keyword Documentation: http://robotframework.org/SeleniumLibrary/SeleniumLibrary.html -.. _INSTALL.rst: https://github.com/robotframework/SeleniumLibrary/blob/master/INSTALL.rst -.. _BUILD.rst: https://github.com/robotframework/SeleniumLibrary/blob/master/BUILD.rst .. _demo project: https://bitbucket.org/robotframework/webdemo .. _Robot Framework User Guide: http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html +.. _Robot Framework installation instructions: https://github.com/robotframework/robotframework/blob/master/INSTALL.rst .. _robotframework-users: http://groups.google.com/group/robotframework-users .. _Slack community: https://robotframework-slack-invite.herokuapp.com .. _issue tracker: https://github.com/robotframework/SeleniumLibrary/issues