diff --git a/docs/index.html b/docs/index.html index 9ecf5168b..d6adb5082 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,184 +1,184 @@ - - - - - - -SeleniumLibrary - - - - -
-

SeleniumLibrary

- - -
-

Introduction

-

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.

-

SeleniumLibrary currently works with Selenium 4. It supports Python 3.8 through 3.11. -In addition to the normal Python interpreter, it works also -with PyPy.

-

SeleniumLibrary is based on the "old SeleniumLibrary" that was forked to -Selenium2Library and then later renamed back to SeleniumLibrary. -See the VERSIONS.rst for more information about different versions and the -overall project history.

- -https://img.shields.io/pypi/v/robotframework-seleniumlibrary.svg?label=version - - -https://img.shields.io/pypi/dm/robotframework-seleniumlibrary.svg - - -https://img.shields.io/pypi/l/robotframework-seleniumlibrary.svg - - -https://github.com/robotframework/SeleniumLibrary/actions/workflows/CI.yml/badge.svg?branch=master - -
-
-

Keyword Documentation

-

See keyword documentation for available keywords and more information -about the library in general.

-
-
-

Installation

-

The recommended installation method is using pip:

-
pip install --upgrade robotframework-seleniumlibrary
-

Running this command installs also the latest Selenium and Robot Framework -versions, but you still need to install browser drivers separately. -The --upgrade option can be omitted when installing the library for the -first time.

-

It is possible to install directly from the GitHub repository. To install -latest source from the master branch, use this command:

-
pip install git+https://github.com/robotframework/SeleniumLibrary.git
-

Please note that installation will take some time, because pip will -clone the SeleniumLibrary project to a temporary directory and then -perform the installation.

-

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.

-

Alternatively, you can use a tool called WebdriverManager which can -find the latest version or when required, any version of appropriate -webdrivers for you and then download and link/copy it into right -location. Tool can run on all major operating systems and supports -downloading of Chrome, Firefox, Opera & Edge webdrivers.

-

Here's an example:

-
pip install webdrivermanager
-webdrivermanager firefox chrome --linkpath /usr/local/bin
-
-
-

Usage

-

To use SeleniumLibrary in Robot Framework tests, the library needs to -first be imported using the Library setting as any other library. -The library accepts some import time arguments, which are documented -in the keyword documentation along with all the keywords provided -by the library.

-

When using Robot Framework, it is generally recommended to write as -easy-to-understand tests as possible. The keywords provided by -SeleniumLibrary is pretty low level, though, and often require -implementation-specific arguments like element locators to be passed -as arguments. It is thus typically a good idea to write tests using -Robot Framework's higher-level keywords that utilize SeleniumLibrary -keywords internally. This is illustrated by the following example -where SeleniumLibrary keywords like Input Text are primarily -used by higher-level keywords like Input Username.

-
*** Settings ***
-Documentation     Simple example using SeleniumLibrary.
-Library           SeleniumLibrary
-
-*** Variables ***
-${LOGIN URL}      http://localhost:7272
-${BROWSER}        Chrome
-
-*** Test Cases ***
-Valid Login
-    Open Browser To Login Page
-    Input Username    demo
-    Input Password    mode
-    Submit Credentials
-    Welcome Page Should Be Open
-    [Teardown]    Close Browser
-
-*** Keywords ***
-Open Browser To Login Page
-    Open Browser    ${LOGIN URL}    ${BROWSER}
-    Title Should Be    Login Page
-
-Input Username
-    [Arguments]    ${username}
-    Input Text    username_field    ${username}
-
-Input Password
-    [Arguments]    ${password}
-    Input Text    password_field    ${password}
-
-Submit Credentials
-    Click Button    login_button
-
-Welcome Page Should Be Open
-    Title Should Be    Welcome Page
-

The above example is a slightly modified version of an example in a -demo project that illustrates using Robot Framework and SeleniumLibrary. -See the demo for more examples that you can also execute on your own -machine. For more information about Robot Framework test data syntax in -general see the Robot Framework User Guide.

-
-
-

Extending SeleniumLibrary

-

Before creating your own library which extends the SeleniumLibrary, please consider would -the extension be also useful also for general usage. If it could be useful also for general -usage, please create a new issue describing the enhancement request and even better if the -issue is backed up by a pull request.

-

If the enhancement is not generally useful, example solution is domain specific, then the -SeleniumLibrary offers public APIs which can be used to build its own plugins and libraries. -Plugin API allows us to add new keywords, modify existing keywords and modify the internal -functionality of the library. Also new libraries can be built on top of the -SeleniumLibrary. Please see extending documentation for more details about the -available methods and for examples how the library can be extended.

-
-
-

Community

-

If the provided documentation is not enough, there are various community channels -available:

- -
-
- - + + + + + + +SeleniumLibrary + + + + +
+

SeleniumLibrary

+ + +
+

Introduction

+

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.

+

SeleniumLibrary currently works with Selenium 4. It supports Python 3.8 through 3.11. +In addition to the normal Python interpreter, it works also +with PyPy.

+

SeleniumLibrary is based on the "old SeleniumLibrary" that was forked to +Selenium2Library and then later renamed back to SeleniumLibrary. +See the VERSIONS.rst for more information about different versions and the +overall project history.

+ +https://img.shields.io/pypi/v/robotframework-seleniumlibrary.svg?label=version + + +https://img.shields.io/pypi/dm/robotframework-seleniumlibrary.svg + + +https://img.shields.io/pypi/l/robotframework-seleniumlibrary.svg + + +https://github.com/robotframework/SeleniumLibrary/actions/workflows/CI.yml/badge.svg?branch=master + +
+
+

Keyword Documentation

+

See keyword documentation for available keywords and more information +about the library in general.

+
+
+

Installation

+

The recommended installation method is using pip:

+
pip install --upgrade robotframework-seleniumlibrary
+

Running this command installs also the latest Selenium and Robot Framework +versions, but you still need to install browser drivers separately. +The --upgrade option can be omitted when installing the library for the +first time.

+

It is possible to install directly from the GitHub repository. To install +latest source from the master branch, use this command:

+
pip install git+https://github.com/robotframework/SeleniumLibrary.git
+

Please note that installation will take some time, because pip will +clone the SeleniumLibrary project to a temporary directory and then +perform the installation.

+

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.

+

Alternatively, you can use a tool called WebdriverManager which can +find the latest version or when required, any version of appropriate +webdrivers for you and then download and link/copy it into right +location. Tool can run on all major operating systems and supports +downloading of Chrome, Firefox, Opera & Edge webdrivers.

+

Here's an example:

+
pip install webdrivermanager
+webdrivermanager firefox chrome --linkpath /usr/local/bin
+
+
+

Usage

+

To use SeleniumLibrary in Robot Framework tests, the library needs to +first be imported using the Library setting as any other library. +The library accepts some import time arguments, which are documented +in the keyword documentation along with all the keywords provided +by the library.

+

When using Robot Framework, it is generally recommended to write as +easy-to-understand tests as possible. The keywords provided by +SeleniumLibrary is pretty low level, though, and often require +implementation-specific arguments like element locators to be passed +as arguments. It is thus typically a good idea to write tests using +Robot Framework's higher-level keywords that utilize SeleniumLibrary +keywords internally. This is illustrated by the following example +where SeleniumLibrary keywords like Input Text are primarily +used by higher-level keywords like Input Username.

+
*** Settings ***
+Documentation     Simple example using SeleniumLibrary.
+Library           SeleniumLibrary
+
+*** Variables ***
+${LOGIN URL}      http://localhost:7272
+${BROWSER}        Chrome
+
+*** Test Cases ***
+Valid Login
+    Open Browser To Login Page
+    Input Username    demo
+    Input Password    mode
+    Submit Credentials
+    Welcome Page Should Be Open
+    [Teardown]    Close Browser
+
+*** Keywords ***
+Open Browser To Login Page
+    Open Browser    ${LOGIN URL}    ${BROWSER}
+    Title Should Be    Login Page
+
+Input Username
+    [Arguments]    ${username}
+    Input Text    username_field    ${username}
+
+Input Password
+    [Arguments]    ${password}
+    Input Text    password_field    ${password}
+
+Submit Credentials
+    Click Button    login_button
+
+Welcome Page Should Be Open
+    Title Should Be    Welcome Page
+

The above example is a slightly modified version of an example in a +demo project that illustrates using Robot Framework and SeleniumLibrary. +See the demo for more examples that you can also execute on your own +machine. For more information about Robot Framework test data syntax in +general see the Robot Framework User Guide.

+
+
+

Extending SeleniumLibrary

+

Before creating your own library which extends the SeleniumLibrary, please consider would +the extension be also useful also for general usage. If it could be useful also for general +usage, please create a new issue describing the enhancement request and even better if the +issue is backed up by a pull request.

+

If the enhancement is not generally useful, example solution is domain specific, then the +SeleniumLibrary offers public APIs which can be used to build its own plugins and libraries. +Plugin API allows us to add new keywords, modify existing keywords and modify the internal +functionality of the library. Also new libraries can be built on top of the +SeleniumLibrary. Please see extending documentation for more details about the +available methods and for examples how the library can be extended.

+
+
+

Community

+

If the provided documentation is not enough, there are various community channels +available:

+ +
+
+ +