OLD | NEW |
1 This file contains high-level info about how ChromeDriver works and how to | 1 This file contains high-level info about how ChromeDriver works and how to |
2 contribute. | 2 contribute. |
3 | 3 |
4 ChromeDriver is an implementation of the WebDriver standard, | 4 ChromeDriver is an implementation of the WebDriver standard, |
5 which allows users to automate testing of their website across browsers. | 5 which allows users to automate testing of their website across browsers. |
6 | 6 |
7 =====Getting started===== | 7 =====Getting started===== |
8 Build ChromeDriver by building the 'chromedriver2' target. This will create | 8 Build ChromeDriver by building the 'chromedriver2_server' target. This will |
9 a shared library in the build folder named 'chromedriver2.dll' (win), | 9 create an executable binary in the build folder named 'chromedriver2_server.exe' |
10 'chromedriver2.so' (mac), or 'libchromedriver2.so' (linux). | 10 on Windows or 'chromedriver2_server' on Mac and Linux. |
11 | 11 |
12 Once built, ChromeDriver can be used interactively with python. | 12 Once built, ChromeDriver can be used interactively with python. |
13 This can be easily done by running python in this directory (or including | |
14 this directory in your PYTHONPATH). | |
15 | 13 |
| 14 $ export PYTHONPATH=<THIS_DIR>/server:<THIS_DIR>/client |
16 $ python | 15 $ python |
| 16 >>> import server |
17 >>> import chromedriver | 17 >>> import chromedriver |
18 >>> driver = chromedriver.ChromeDriver('/path/to/chromedriver2/library') | 18 >>> cd_server = server.Server('/path/to/chromedriver2_server/executable') |
| 19 >>> driver = chromedriver.ChromeDriver(cd_server.GetUrl()) |
19 >>> driver.Load('http://www.google.com') | 20 >>> driver.Load('http://www.google.com') |
| 21 >>> driver.Quit() |
| 22 >>> cd_server.Kill() |
20 | 23 |
21 ChromeDriver will use the system installed Chrome by default. | 24 ChromeDriver will use the system installed Chrome by default. |
22 | 25 |
23 To use ChromeDriver2 with Chrome on Android pass the Android package name in the | 26 To use ChromeDriver2 with Chrome on Android pass the Android package name in the |
24 chromeOptions.androidPackage capability when creating the driver. The path to | 27 chromeOptions.androidPackage capability when creating the driver. The path to |
25 adb_commands.py and the adb tool from the Android SDK must be set in PATH. For | 28 adb_commands.py and the adb tool from the Android SDK must be set in PATH. For |
26 more detailed instructions see the wiki: | 29 more detailed instructions see the wiki: |
27 https://code.google.com/p/chromedriver/wiki/ChromeDriver2forAndroid | 30 https://code.google.com/p/chromedriver/wiki/ChromeDriver2forAndroid |
28 | 31 |
29 NOTE: on 64-bit OSX machines (most modern ones, including laptops) it is | |
30 necessary to set the environment variable VERSIONER_PYTHON_PREFER_32_BIT=yes, | |
31 because the 'chromedriver2.so' library is 32-bit, while on 64-bit OSX machines | |
32 (most modern ones including laptops), python starts as a 64-bit binary by | |
33 default and would not be able to load the library. | |
34 | |
35 =====Architecture===== | 32 =====Architecture===== |
36 ChromeDriver is shipped separately from Chrome. It controls Chrome out of | 33 ChromeDriver is shipped separately from Chrome. It controls Chrome out of |
37 process through DevTools (WebKit Inspector). ChromeDriver is a shared library | 34 process through DevTools (WebKit Inspector). ChromeDriver is a standalone server |
38 which exports a few functions for executing WebDriver-standard commands, which | 35 executable which communicates via the WebDriver JSON wire protocol. This can be |
39 are packaged in JSON. For internal use, a custom python client for ChromeDriver | 36 used with the open source WebDriver client libraries. |
40 is available in chromedriver.py, which works on desktop (win/mac/linux) with | |
41 the shared library ChromeDriver. | |
42 | 37 |
43 The ChromeDriver shared library runs commands on the same thread that calls | 38 When a new session is created, a new thread is started that is dedicated to the |
44 ExecuteCommand. It doesn't create any additional threads except for the IO | 39 session. All commands for the session runs on this thread. This thread is |
45 thread. The IO thread is used to keep reading incoming data from Chrome in the | 40 stopped when the session is deleted. Besides, there is an IO thread and it is |
46 background. | 41 used to keep reading incoming data from Chrome in the background. |
47 | |
48 ChromeDriver is also available as a standalone server executable which | |
49 communicates via the WebDriver JSON wire protocol. This can be used with the | |
50 open source WebDriver client libraries. | |
51 | 42 |
52 =====Code structure===== | 43 =====Code structure===== |
53 Code under the 'chrome' subdirectory is intended to be unaware of WebDriver and | 44 Code under the 'chrome' subdirectory is intended to be unaware of WebDriver and |
54 serve as a basic C++ interface for controlling Chrome remotely via DevTools. | 45 serve as a basic C++ interface for controlling Chrome remotely via DevTools. |
55 As such, it should not have any WebDriver-related dependencies. | 46 As such, it should not have any WebDriver-related dependencies. |
56 | 47 |
57 1) chrome/test/chromedriver | 48 1) chrome/test/chromedriver |
58 Implements chromedriver commands. | 49 Implements chromedriver commands. |
59 | 50 |
60 2) chrome/test/chromedriver/chrome | 51 2) chrome/test/chromedriver/chrome |
61 Code to deal with chrome specific stuff, like starting Chrome on different OS | 52 Code to deal with chrome specific stuff, like starting Chrome on different OS |
62 platforms, controlling Chrome via DevTools, handling events from DevTools, etc. | 53 platforms, controlling Chrome via DevTools, handling events from DevTools, etc. |
63 | 54 |
64 3) chrome/test/chromedriver/js | 55 3) chrome/test/chromedriver/js |
65 Javascript helper scripts. | 56 Javascript helper scripts. |
66 | 57 |
67 4) chrome/test/chromedriver/net | 58 4) chrome/test/chromedriver/net |
68 Code to deal with network communication, such as connection to DevTools. | 59 Code to deal with network communication, such as connection to DevTools. |
69 | 60 |
70 5) chrome/test/chromedriver/server | 61 5) chrome/test/chromedriver/client |
| 62 Code for a python client. |
| 63 |
| 64 6) chrome/test/chromedriver/server |
71 Code for the chromedriver server. | 65 Code for the chromedriver server. |
| 66 A python wrapper to the chromedriver server. |
72 | 67 |
73 6) chrome/test/chromedriver/third_party | 68 7) chrome/test/chromedriver/extension |
| 69 An extension used for automating the desktop browser. |
| 70 |
| 71 8) chrome/test/chromedriver/third_party |
74 Third party libraries used by chromedriver. | 72 Third party libraries used by chromedriver. |
75 | 73 |
76 =====Testing===== | 74 =====Testing===== |
77 There are 4 test suites for verifying ChromeDriver's correctness: | 75 There are 4 test suites for verifying ChromeDriver's correctness: |
78 | 76 |
79 1) chromedriver2_unittests (chrome/chrome_tests.gypi) | 77 1) chromedriver2_unittests (chrome/chrome_tests.gypi) |
80 This is the unittest target, which runs on the main waterfall on win/mac/linux | 78 This is the unittest target, which runs on the main waterfall on win/mac/linux |
81 and can close the tree. It is also run on the commit queue and try bots by | 79 and can close the tree. It is also run on the commit queue and try bots by |
82 default. Tests should take a few milliseconds and be very stable. | 80 default. Tests should take a few milliseconds and be very stable. |
83 | 81 |
84 2) chromedriver2_tests (chrome/chrome_tests.gypi) | 82 2) chromedriver2_tests (chrome/chrome_tests.gypi) |
85 This is a collection of C++ medium sized tests which can be run optionally | 83 This is a collection of C++ medium sized tests which can be run optionally |
86 on the trybots. | 84 on the trybots. |
87 | 85 |
88 3) python tests | 86 3) python tests |
89 These are integration tests which can be found in run_py_tests.py. They are | 87 These are integration tests which can be found in run_py_tests.py. They are |
90 run on the chromium QA bots: | 88 run on the chromium QA bots: |
91 http://build.chromium.org/p/chromium.pyauto/waterfall | 89 http://build.chromium.org/p/chromium.pyauto/waterfall |
92 | 90 |
93 4) WebDriver Java acceptance tests | 91 4) WebDriver Java acceptance tests |
94 These are integration tests from the WebDriver open source project which can | 92 These are integration tests from the WebDriver open source project which can |
95 be run via run_java_tests.py. They are also run on the chromium QA bots. | 93 be run via run_java_tests.py. They are also run on the chromium QA bots. |
96 See http://src.chromium.org/viewvc/chrome/trunk/deps/third_party/webdriver | 94 See http://src.chromium.org/viewvc/chrome/trunk/deps/third_party/webdriver |
97 | 95 |
98 =====Contributing===== | 96 =====Contributing===== |
99 Find an open issue and submit a patch for review by an individual listed in | 97 Find an open issue and submit a patch for review by an individual listed in |
100 the OWNERS file in this directory. Issues are tracked in chromedriver's issue | 98 the OWNERS file in this directory. Issues are tracked in chromedriver's issue |
101 tracker: | 99 tracker: |
102 https://code.google.com/p/chromedriver/issues/list | 100 https://code.google.com/p/chromedriver/issues/list |
OLD | NEW |