This directory contains a component of ChromeDriver that allows developers to “replay” ChromeDriver sessions using a ChromeDriver log file.
For full usage information, run ./client_replay.py --help.
In general, this component is used by generating a ChromeDriver log from a session of interest (or getting the log from an bug report, etc.), and then replaying that log using this component. For example, to replay ChromeDriver tests from chromedriver/test/run_py_tests.py:
# Generate the log test/run_py_tests.py --log-path=<desired path to log> --replayable=true # Replay the log ./client_replay.py <chromedriver binary> <path to log> --devtools-replay=true
For more usage information, run ./client_replay.py --help.
The code has two main components: the client-side replay written in Python and the DevTools-side replay written in C++.
The client-side replay module is written in Python and exists separately from the ChromeDriver binary. It re-uses the same logic to launch the ChromeDriver binary as test/run_py_tests.py (this code is in the chromedriver/server directory).
The entry point for the client-side replay is client_replay.py. This file contains code that parses client-side commands out of the log file and interprets them back into the corresponding WebDriver requests. When there are session, window, or element IDs in the log, the CommandSequence class substitutes them to match the new session so that the logged commands have valid references to sessions, windows, and elements.
This entry point also launches ChromeDriver (which in turn launches Chrome), and has a programmatic interface for retrieving commands from a log file using the CommandSequence class. The command-line interface uses the Replayer class to interface with a CommandSequence.
The DevTools-side replay module is written in C++ and is built as part of ChromeDriver binary, enabled by running ChromeDriver (or client_replay.py) with the --devtools-replay=true flag.
DevToolsLogReader (in devtools_log_reader.h) parses out DevTools commands, responses, and events out of the log file. Depending on the DevTools command type (HTTP or WebSocket), the responses are read directly into ChromeDriver by either the ReplayHTTPClient or the LogReplaySocket classes.
ReplayHTTPClient subclasses DevToolsHTTPClient, which is responsible for all of the HTTP communication between ChromeDriver and DevTools, and it overrides one method to communicate with the DevToolsLogReader instead of the actual Chrome instance. LogReplaySocket subclasses SyncWebSocket (see chromedriver/net/) and is used to redirect WebSocket communication from DevToolsClientImpl to the DevToolsLogReader instead of getting the WebSocket events and responses from Chrome.
Between these two classes, all of the communication between ChromeDriver and Chrome is replicated, so when DevTools replay is enabled, no Chrome instance even needs to be launched. Note that the DevTools replay component can be run without running the client-side replay, but this doesn't make much sense as the same client-side commands would have to be called in the same order as in the logged session to replicate the same DevTools commands, and at that point you may as well replay the client side as well as the DevTools side.
The C++ unit tests for devtools_log_reader.cc are integrated into the chromedriver_unittests target. Python unit tests for the client-replay are standalone in the file client_replay_unittest.py but are integrated into the Chromium CQ.
client_replay_tests.py runs the end-to-end tests for both the client side and DevTools side (with the --devtools-replay=true flag) replay functions.
There are a few places in this directory that need to be maintained based on external code. On changes in command names, the _COMMANDS list in client_replay.py will need to be updated (see https://crbug.com/chromedriver/2511 ).
When there is significant changes to the format of logging (at spots marked with comments in the ChromeDriver code), the log reading will need to be updated accordingly, on both the DevTools side (devtools_log_reader.cc), and the client side (_Parser class in client_replay.py).
If log formats change, it may be necessary to update the unit test data files (in test_data/) to match the new logging format. These are small sample log entries used only for unit tests; the end-to-end tests auto-generate the needed logs.