README.rst
1======================
2Selenium Client Driver
3======================
4
5Introduction
6============
7
8Python language bindings for Selenium WebDriver.
9
10The `selenium` package is used to automate web browser interaction from Python.
11
12+-----------+--------------------------------------------------------------------------------------+
13| **Home**: | http://www.seleniumhq.org |
14+-----------+--------------------------------------------------------------------------------------+
15| **Docs**: | `selenium package API <https://seleniumhq.github.io/selenium/docs/api/py/api.html>`_ |
16+-----------+--------------------------------------------------------------------------------------+
17| **Dev**: | https://github.com/SeleniumHQ/Selenium |
18+-----------+--------------------------------------------------------------------------------------+
19| **PyPI**: | https://pypi.org/project/selenium/ |
20+-----------+--------------------------------------------------------------------------------------+
21| **IRC**: | **#selenium** channel on freenode |
22+-----------+--------------------------------------------------------------------------------------+
23
24Several browsers/drivers are supported (Firefox, Chrome, Internet Explorer), as well as the Remote protocol.
25
26Supported Python Versions
27=========================
28
29* Python 2.7, 3.4+
30
31Installing
32==========
33
34If you have `pip <https://pip.pypa.io/>`_ on your system, you can simply install or upgrade the Python bindings::
35
36 pip install -U selenium
37
38Alternately, you can download the source distribution from `PyPI <https://pypi.org/project/selenium/#files>`_ (e.g. selenium-3.141.0.tar.gz), unarchive it, and run::
39
40 python setup.py install
41
42Note: You may want to consider using `virtualenv <http://www.virtualenv.org/>`_ to create isolated Python environments.
43
44Drivers
45=======
46
47Selenium requires a driver to interface with the chosen browser. Firefox,
48for example, requires `geckodriver <https://github.com/mozilla/geckodriver/releases>`_, which needs to be installed before the below examples can be run. Make sure it's in your `PATH`, e. g., place it in `/usr/bin` or `/usr/local/bin`.
49
50Failure to observe this step will give you an error `selenium.common.exceptions.WebDriverException: Message: 'geckodriver' executable needs to be in PATH.`
51
52Other supported browsers will have their own drivers available. Links to some of the more popular browser drivers follow.
53
54+--------------+-----------------------------------------------------------------------+
55| **Chrome**: | https://sites.google.com/a/chromium.org/chromedriver/downloads |
56+--------------+-----------------------------------------------------------------------+
57| **Edge**: | https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/ |
58+--------------+-----------------------------------------------------------------------+
59| **Firefox**: | https://github.com/mozilla/geckodriver/releases |
60+--------------+-----------------------------------------------------------------------+
61| **Safari**: | https://webkit.org/blog/6900/webdriver-support-in-safari-10/ |
62+--------------+-----------------------------------------------------------------------+
63
64Example 0:
65==========
66
67* open a new Firefox browser
68* load the page at the given URL
69
70.. code-block:: python
71
72 from selenium import webdriver
73
74 browser = webdriver.Firefox()
75 browser.get('http://seleniumhq.org/')
76
77Example 1:
78==========
79
80* open a new Firefox browser
81* load the Yahoo homepage
82* search for "seleniumhq"
83* close the browser
84
85.. code-block:: python
86
87 from selenium import webdriver
88 from selenium.webdriver.common.keys import Keys
89
90 browser = webdriver.Firefox()
91
92 browser.get('http://www.yahoo.com')
93 assert 'Yahoo' in browser.title
94
95 elem = browser.find_element_by_name('p') # Find the search box
96 elem.send_keys('seleniumhq' + Keys.RETURN)
97
98 browser.quit()
99
100Example 2:
101==========
102
103Selenium WebDriver is often used as a basis for testing web applications. Here is a simple example using Python's standard `unittest <http://docs.python.org/3/library/unittest.html>`_ library:
104
105.. code-block:: python
106
107 import unittest
108 from selenium import webdriver
109
110 class GoogleTestCase(unittest.TestCase):
111
112 def setUp(self):
113 self.browser = webdriver.Firefox()
114 self.addCleanup(self.browser.quit)
115
116 def testPageTitle(self):
117 self.browser.get('http://www.google.com')
118 self.assertIn('Google', self.browser.title)
119
120 if __name__ == '__main__':
121 unittest.main(verbosity=2)
122
123Selenium Server (optional)
124==========================
125
126For normal WebDriver scripts (non-Remote), the Java server is not needed.
127
128However, to use Selenium Webdriver Remote or the legacy Selenium API (Selenium-RC), you need to also run the Selenium server. The server requires a Java Runtime Environment (JRE).
129
130Download the server separately, from: http://selenium-release.storage.googleapis.com/3.141/selenium-server-standalone-3.141.0.jar
131
132Run the server from the command line::
133
134 java -jar selenium-server-standalone-3.141.0.jar
135
136Then run your Python client scripts.
137
138Use The Source Luke!
139====================
140
141View source code online:
142
143+-----------+-------------------------------------------------------+
144| official: | https://github.com/SeleniumHQ/selenium/tree/master/py |
145+-----------+-------------------------------------------------------+
146