event_listener.md

DevTools Event Listener

Each DevToolsClientImpl object contains a list of event listeners. These listeners are called when certain DevTools events occur, and can run additional code in response to those events. For example, a listener can listen for page navigation events in order to keep track of navigation status, while another listener can keep track of opening and closing of JavaScript dialog boxes, and so on.

(See Chrome Connection for more information about DevToolsClientImpl object.)

An event listener must be an object that implements the interface class DevToolsEventListener. Each listener is called in the following situations:

• When the DevTools Client connects to Chrome. (ConnectIfNecessary -> EnsureListenersNotifiedOfConnect -> DevToolsEventListener::OnConnected)
• When an event is received from Chrome. (ProcessEvent -> EnsureListenersNotifiedOfEvent -> DevToolsEventListener::OnEvent)
• When a command response is received from Chrome. (ProcessCommandResponse -> EnsureListenersNotifiedOfCommandResponse -> DevToolsEventListener::OnCommandSuccess)

The DevTools Client has three lists to keep track of listeners that still need to be notified of these three situations: DevToolsClientImpl::unnotified_connect_listeners_, DevToolsClientImpl::unnotified_event_listeners_, and DevToolsClientImpl::unnotified_cmd_response_listeners_. These lists are necessary because while a listener processes one event, it can trigger the generation of additional events.

The listeners are not notified of commands sent from ChromeDriver to DevTools.

Listener Registration

Each instance of DevToolsClientImpl stores a list of listeners in field DevToolsClientImpl::listeners_. Listeners can be added by calling DevToolsClientImpl::AddListener.

• For the browser-wide DevTools client, this is done by CreateBrowserwideDevToolsClientAndConnect shortly after Chrome starts.
• For other DevTools clients, this happens in ChromeImpl::UpdateWebViews and WebViewImpl constructor.

Most listeners are added indirectly by WebViewImpl constructor. The constructor instantiates several listener objects, and the constructors for those listener objects are responsible for calling DevToolsClientImpl::AddListener to add themselves.

Details of Listeners

ChromeDriver has the following event listeners:

• CastTracker
• ConsoleLogger
• DevToolsEventsLogger
• DomTracker
• DownloadDirectoryOverrideManager
• FedCmTracker
• FrameTracker
• GeolocationOverrideManager
• HeapSnapshotTaker
• JavaScriptDialogManager
• MobileEmulationOverrideManager
• NavigationTracker
• NetworkConditionsOverrideManager
• PerformanceLogger

The listener description below is still incomplete. More will be added in the future.

Navigation Tracker

The NavigationTracker implements the wait for navigation to complete algorithm defined by the WebDriver standard. It is used when the page loading strategy is normal (the default) or eager. (When the page loading strategy is none, ChromeDriver uses NonBlockingNavigationTracker, which is not a DevTools event listener.)

NavigationTracker keeps track of the loading state of the current browsing context (either a window/tab or a frame). The loading state is represented by enum LoadingState, and can be one of three values: kUnknown, kLoading, and kNotLoading. NavigationTracker moves the loading state between these values based on the events it receives from Chrome DevTools. Most ChromeDriver commands wait for the loading state to become kNotLoading before returning.

FedCM Tracker

The FedCmTracker listens to FedCM dialog events and stores the parameters for later use.

Since the WebDriver protocol does not support events, we instead provide accessors that the client can periodically check to detect when a dialog has been shown.