Cross Reference: /external/chromium_org/chrome/test/chromedriver/

This file contains high-level info about how ChromeDriver works and how to
contribute.

ChromeDriver is an implementation of the WebDriver standard,
which allows users to automate testing of their website across browsers.

See the user site at https://sites.google.com/a/chromium.org/chromedriver/

=====Getting started=====
Build ChromeDriver by building the 'chromedriver' target. This will
create an executable binary in the build folder named
'chromedriver[.exe]'.

Once built, ChromeDriver can be used interactively with python.

$ export PYTHONPATH=<THIS_DIR>/server:<THIS_DIR>/client
$ python
>>> import server
>>> import chromedriver
>>> cd_server = server.Server('/path/to/chromedriver/executable')
>>> driver = chromedriver.ChromeDriver(cd_server.GetUrl())
>>> driver.Load('http://www.google.com')
>>> driver.Quit()
>>> cd_server.Kill()

ChromeDriver will use the system installed Chrome by default.

To use ChromeDriver2 with Chrome on Android pass the Android package name in the
chromeOptions.androidPackage capability when creating the driver. The path to
adb_commands.py and the adb tool from the Android SDK must be set in PATH. For
more detailed instructions see the user site.

=====Architecture=====
ChromeDriver is shipped separately from Chrome. It controls Chrome out of
process through DevTools. ChromeDriver is a standalone server which
communicates with the WebDriver client via the WebDriver wire protocol, which
is essentially synchronous JSON commands over HTTP. WebDriver clients are
available in many languages, and many are available from the open source
selenium/webdriver project: http://code.google.com/p/selenium. ChromeDriver
uses the webserver from net/server.

ChromeDriver has a main thread, called the command thread, an IO thread,
and a thread per session. The webserver receives a request on the IO thread,
which is sent to a handler on the command thread. The handler executes the
appropriate command function, which completes asynchronously. The create
session command may create a new thread for subsequent session-related commands,
which will execute on the dedicated session thread synchronously. When a
command is finished, it will invoke a callback, which will eventually make its
way back to the IO thread as a HTTP response for the server to send.

=====Code structure (relative to this file)=====
1) .
Implements chromedriver commands.

2) chrome/
A basic interface for controlling Chrome. Should not depend on or reference
WebDriver-related code or concepts.

3) js/
Javascript helper scripts.

4) net/
Code to deal with network communication, such as connection to DevTools.

5) client/
Code for a python client.

6) server/
Code for the chromedriver server.
A python wrapper to the chromedriver server.

7) extension/
An extension used for automating the desktop browser.

8) test/
Integration tests.

9) third_party/
Third party libraries used by chromedriver.

=====Testing=====
See the ChromeDriver waterfall at:
    http://build.chromium.org/p/chromium.chromedriver/waterfall
There are 4 test suites for verifying ChromeDriver's correctness:

1) chromedriver_unittests (chrome/chrome_tests.gypi)
This is the unittest target, which runs on the main waterfall on win/mac/linux
and can close the tree. It is also run on the commit queue and try bots by
default. Tests should take a few milliseconds and be very stable.

2) chromedriver_tests (chrome/chrome_tests.gypi)
This is a collection of C++ medium sized tests which can be run optionally
on the trybots.

3) python integration tests
Run test/run_py_tests.py --help for more info. These are only run on the
ChromeDriver waterfall.

4) WebDriver Java acceptance tests
These are integration tests from the WebDriver open source project which can
be run via test/run_java_tests.py. They are only run on the ChromeDriver
bots. Run with --help for more info.

=====Contributing=====
Find an open issue and submit a patch for review by an individual listed in
the OWNERS file in this directory. Issues are tracked in chromedriver's issue
tracker:
    https://code.google.com/p/chromedriver/issues/list
Name	Date	Size
..	12-Mar-2015	4 KiB
alert_commands.cc	12-Mar-2015	3 KiB
alert_commands.h	12-Mar-2015	1.7 KiB
archive.py	12-Mar-2015	2.9 KiB
basic_types.cc	12-Mar-2015	1,008
basic_types.h	12-Mar-2015	822
capabilities.cc	12-Mar-2015	20.4 KiB
capabilities.h	12-Mar-2015	4 KiB
capabilities_unittest.cc	12-Mar-2015	20.2 KiB
chrome/	12-Mar-2015	4 KiB
chrome_launcher.cc	12-Mar-2015	30.4 KiB
chrome_launcher.h	12-Mar-2015	1.6 KiB
chrome_launcher_unittest.cc	12-Mar-2015	7.8 KiB
chrome_paths.py	12-Mar-2015	1.2 KiB
client/	12-Mar-2015	4 KiB
command.h	12-Mar-2015	714
command_listener.h	12-Mar-2015	711
command_listener_proxy.cc	12-Mar-2015	729
command_listener_proxy.h	12-Mar-2015	928
command_listener_proxy_unittest.cc	12-Mar-2015	1.1 KiB
commands.cc	12-Mar-2015	9.3 KiB
commands.h	12-Mar-2015	1.9 KiB
commands_unittest.cc	12-Mar-2015	21.8 KiB
cpp_source.py	12-Mar-2015	2.2 KiB
DEPS	12-Mar-2015	275
element_commands.cc	12-Mar-2015	16.5 KiB
element_commands.h	12-Mar-2015	5.7 KiB
element_util.cc	12-Mar-2015	20.7 KiB
element_util.h	12-Mar-2015	3.8 KiB
embed_extension_in_cpp.py	12-Mar-2015	1.1 KiB
embed_js_in_cpp.py	12-Mar-2015	1.5 KiB
embed_mobile_devices_in_cpp.py	12-Mar-2015	1.4 KiB
embed_user_data_dir_in_cpp.py	12-Mar-2015	981
embed_version_in_cpp.py	12-Mar-2015	1.1 KiB
extension/	12-Mar-2015	4 KiB
js/	12-Mar-2015	4 KiB
key_converter.cc	12-Mar-2015	11.8 KiB
key_converter.h	12-Mar-2015	1.4 KiB
key_converter_unittest.cc	12-Mar-2015	15.9 KiB
keycode_text_conversion.h	12-Mar-2015	1.5 KiB
keycode_text_conversion_mac.mm	12-Mar-2015	3.7 KiB
keycode_text_conversion_ozone.cc	12-Mar-2015	923
keycode_text_conversion_unittest.cc	12-Mar-2015	5.7 KiB
keycode_text_conversion_win.cc	12-Mar-2015	2.1 KiB
keycode_text_conversion_x.cc	12-Mar-2015	7.6 KiB
logging.cc	12-Mar-2015	9.4 KiB
logging.h	12-Mar-2015	2.8 KiB
logging_unittest.cc	12-Mar-2015	5.6 KiB
net/	12-Mar-2015	4 KiB
OWNERS	12-Mar-2015	81
performance_logger.cc	12-Mar-2015	10.4 KiB
performance_logger.h	12-Mar-2015	3.7 KiB
performance_logger_unittest.cc	12-Mar-2015	12.8 KiB
README.txt	12-Mar-2015	4 KiB
run_buildbot_steps.py	12-Mar-2015	18.8 KiB
server/	12-Mar-2015	4 KiB
session.cc	12-Mar-2015	3.4 KiB
session.h	12-Mar-2015	2.9 KiB
session_commands.cc	12-Mar-2015	21.2 KiB
session_commands.h	12-Mar-2015	4.9 KiB
session_commands_unittest.cc	12-Mar-2015	4.9 KiB
session_thread_map.h	12-Mar-2015	517
session_unittest.cc	12-Mar-2015	3.1 KiB
test/	12-Mar-2015	4 KiB
test_util.cc	12-Mar-2015	2 KiB
test_util.h	12-Mar-2015	1.6 KiB
third_party/	12-Mar-2015	4 KiB
util.cc	12-Mar-2015	14 KiB
util.h	12-Mar-2015	1.7 KiB
util.py	12-Mar-2015	4.8 KiB
util_unittest.cc	12-Mar-2015	1.9 KiB
VERSION	12-Mar-2015	5
window_commands.cc	12-Mar-2015	27.1 KiB
window_commands.h	12-Mar-2015	8.2 KiB