Home | History | Annotate | Download | only in chromedriver 
      1 This file contains high-level info about how ChromeDriver works and how to
      2 contribute.
      3 
      4 ChromeDriver is an implementation of the WebDriver standard,
      5 which allows users to automate testing of their website across browsers.
      6 
      7 See the user site at http://code.google.com/p/chromedriver.
      8 
      9 =====Getting started=====
     10 Build ChromeDriver by building the 'chromedriver2_server' target. This will
     11 create an executable binary in the build folder named
     12 'chromedriver2_server[.exe]'.
     13 
     14 Once built, ChromeDriver can be used interactively with python.
     15 
     16 $ export PYTHONPATH=<THIS_DIR>/server:<THIS_DIR>/client
     17 $ python
     18 >>> import server
     19 >>> import chromedriver
     20 >>> cd_server = server.Server('/path/to/chromedriver2_server/executable')
     21 >>> driver = chromedriver.ChromeDriver(cd_server.GetUrl())
     22 >>> driver.Load('http://www.google.com')
     23 >>> driver.Quit()
     24 >>> cd_server.Kill()
     25 
     26 ChromeDriver will use the system installed Chrome by default.
     27 
     28 To use ChromeDriver2 with Chrome on Android pass the Android package name in the
     29 chromeOptions.androidPackage capability when creating the driver. The path to
     30 adb_commands.py and the adb tool from the Android SDK must be set in PATH. For
     31 more detailed instructions see the wiki:
     32     https://code.google.com/p/chromedriver/wiki/ChromeDriver2forAndroid
     33 
     34 =====Architecture=====
     35 ChromeDriver is shipped separately from Chrome. It controls Chrome out of
     36 process through DevTools. ChromeDriver is a standalone server which
     37 communicates with the WebDriver client via the WebDriver wire protocol, which
     38 is essentially synchronous JSON commands over HTTP. WebDriver clients are
     39 available in many languages, and many are available from the open source
     40 selenium/webdriver project: http://code.google.com/p/selenium. ChromeDriver
     41 uses the webserver from net/server.
     42 
     43 ChromeDriver has a main thread, called the command thread, an IO thread,
     44 and a thread per session. The webserver receives a request on the IO thread,
     45 which is sent to a handler on the command thread. The handler executes the
     46 appropriate command function, which completes asynchronously. The create
     47 session command may create a new thread for subsequent session-related commands,
     48 which will execute on the dedicated session thread synchronously. When a
     49 command is finished, it will invoke a callback, which will eventually make its
     50 way back to the IO thread as a HTTP response for the server to send.
     51 
     52 =====Code structure (relative to this file)=====
     53 1) .
     54 Implements chromedriver commands.
     55 
     56 2) chrome/
     57 A basic interface for controlling Chrome. Should not depend on or reference
     58 WebDriver-related code or concepts.
     59 
     60 3) js/
     61 Javascript helper scripts.
     62 
     63 4) net/
     64 Code to deal with network communication, such as connection to DevTools.
     65 
     66 5) client/
     67 Code for a python client.
     68 
     69 6) server/
     70 Code for the chromedriver server.
     71 A python wrapper to the chromedriver server.
     72 
     73 7) extension/
     74 An extension used for automating the desktop browser.
     75 
     76 8) test/
     77 Integration tests.
     78 
     79 9) third_party/
     80 Third party libraries used by chromedriver.
     81 
     82 =====Testing=====
     83 See the ChromeDriver waterfall at:
     84     http://build.chromium.org/p/chromium.chromedriver/waterfall
     85 There are 4 test suites for verifying ChromeDriver's correctness:
     86 
     87 1) chromedriver2_unittests (chrome/chrome_tests.gypi)
     88 This is the unittest target, which runs on the main waterfall on win/mac/linux
     89 and can close the tree. It is also run on the commit queue and try bots by
     90 default. Tests should take a few milliseconds and be very stable.
     91 
     92 2) chromedriver2_tests (chrome/chrome_tests.gypi)
     93 This is a collection of C++ medium sized tests which can be run optionally
     94 on the trybots.
     95 
     96 3) python integration tests
     97 Run test/run_py_tests.py --help for more info. These are only run on the
     98 ChromeDriver waterfall.
     99 
    100 4) WebDriver Java acceptance tests
    101 These are integration tests from the WebDriver open source project which can
    102 be run via test/run_java_tests.py. They are only run on the ChromeDriver
    103 bots. Run with --help for more info.
    104 
    105 =====Contributing=====
    106 Find an open issue and submit a patch for review by an individual listed in
    107 the OWNERS file in this directory. Issues are tracked in chromedriver's issue
    108 tracker:
    109     https://code.google.com/p/chromedriver/issues/list
    110