1. Motivation

When an automated end-to-end test (e.g., with Selenium WebDriver) fails, it can be challenging to discover the underlying error cause. A common strategy is to gather the browser console logs to discard problems on the client-side. The problem is the browser log gathering feature is not standard in the W3C WebDriver specification. The driver for Chrome (i.e., chromedriver) provides a custom implementation for log gathering using LoggingPreferences. Nevertheless, this feature is not available in other drivers such as geckodriver (i.e., the driver for Firefox). A standard solution is proposed in the new W3C WebDriver BiDi, but this approach is not yet widely adopted in all browsers.

What is BrowserWatcher?

BrowserWatcher is a browser extension designed to monitor web browsers such as Chrome, Firefox, or Edge. BrowserWatcher 1.x has been implemented using manifest version 2 (MV2), and its features are cross-browser console log gathering/displaying, video recording, Content Security Policy (CSP) disabling, and JavaScript/CSS injection. BrowserWatcher 2.x has been migrated to manifest version 3 (MV3), and the feature maintained is video recording.


2. Setup

BrowserWatcher can be used in two different ways. First, it can be installed as an extension in any browser implementing the browser extension API (such as Chrome, Firefox, Edge, etc.). You can use the following files to install BrowserWatcher in your browser:

  • BrowserWatcher 2 (MV3):

    • browserwatcher-2.0.0.crx: Chrome Extension (CRX), for Chromium-based browsers, such as Chrome or Edge. To install it, you can drag and drop this file into the extensions page (chrome://extensions/).

  • BrowserWatcher 1 (MV2):

Second, you can use BrowserWatcher automatically through WebDriverManager. See the section about WebDriverManager for a basic introduction to this use.

3. Features

Once BrowserWatcher is installed in a browser, you can see its logo in the browser navigation bar, as follows:

browserwatcher install v1
Figure 1. BrowserWatcher installed in Chrome

3.1. BrowserWatcher 2 (MV3)

3.1.1. Video recording

BrowserWatcher 2 also allows us to record the current browser tab. The recording can be started and stopped using the following popup:

The recording is stopped using the same button. The recording file will be a WEBM file, available in your Downloads folder.

This feature is based on the API tabCapture. Therefore, this feature is only available in Chromium-based browser.

There are some alternative ways to start and stop the recordings. First, by using the keyboard shortcut Alt+R (for starting the recording) and Alt+W (for stopping the recording). Second, by executing the following JavaScript commands:

  • window.postMessage({ type: "startRecording" }, "*"); : For starting the recording. The recording file name will be auto generated, composed by the system timestamp plus the prefix -browser-recording.webm.

  • window.postMessage({ type: "startRecording", name: "myrecording" }, "*");: For starting the recording and specifyng a custom file recording (myrecording.webm in this example).

  • window.postMessage({ type: "stopRecording" }, "*"); : For stopping the recording.

3.2. BrowserWatcher 1 (MV2)

3.2.1. Console Log Gathering

BrowserWatcher allows gathering the browser console following a cross-browser approach. Internally, it uses a monkey patching technique to override the JavaScript object console. In particular, the following methods are overridden: log, warn, error, info, dir, time, timeEnd, table, and count. In addition, it implements several JavaScript listeners for the following events: error (JavaScript error trace), unhandledrejection (when a JavaScript Promise with no rejection handler is rejected), securitypolicyviolation (when the content security policy is violated), and xhr-error (error response from XMLHttpRequest). This way, the gathered logs are accessible in the property _bwLogs in the console object. The following picture shows an example of the gathered logs of a the sample page:

gather console logs example v3
Figure 3. Console log gathering example

BrowserWatcher has a configuration page, displayed when clicked in its icon. This page has three toggle buttons to set up different features. The first one allows enabling (and disabling) the log gathering feature.

3.2.2. Console Log Displaying

In addition to log gathering, BrowserWatcher allows displaying the console logs (and listened events) as dialog notifications on the page. This feature can be enabled using the following button:

The following picture shows an example of these notifications:

display console logs example v3
Figure 6. Display logs example

3.2.3. Video recording

BrowserWatcher allows recording a browser tab. This feature requires a page loaded in the current tab (in other words, it cannot record empty or configuration pages). Then, it can be started using the following button:

The recording is stopped using the same button. The recording file will be a WEBM file, available in your Downloads folder.

This feature is based on the API tabCapture. Therefore, this feature is not available in Firefox since this API is not implemented in Firefox.

There are some alternative ways to start and stop the recordings. First, by using the keyboard shortcut Alt+R (for starting the recording) and Alt+W (for stopping the recording). Second, by executing the following JavaScript commands:

  • window.postMessage({ type: "startRecording" }); : For starting the recording. The recording file name will be auto generated, composed by the system timestamp plus the prefix -browser-recording.webm.

  • window.postMessage({ type: "startRecording", name: "myrecording" });: For starting the recording and specifyng a custom file recording (myrecording.webm in this example).

  • window.postMessage({ type: "stopRecording" }); : For stopping the recording.

3.2.4. Disabling CSP

Content Security Policy (CSP) is the name of an HTTP response header that browsers use to improve the security of web pages. CSP helps to protect from attacks such as cross-site scripting (XSS). Nevertheless, developers might want to disable the CSP headers received from the server for testing purposes. For this reason, BrowserWatcher allows bypassing these CSP headers. This feature (i.e., disabling CSP headers) is enabled by clicking the following button:

In addition, this feature can be enabled/disabled by executing the following JavaScript commands:

  • window.postMessage({ type: "disableCsp" }); : For disabling CSP.

  • window.postMessage({ type: "enableCsp" }); : For enabling CSP (as it was by default).

3.2.5. JavaScript and CSS injection

BrowserWatcher has an options page, available by clicking on the following menu option:

options v1
Figure 9. BrowserWatcher menu option

This options page allows injecting JavaScript code, libraries, and CSS stylesheets. The following screenshot shows an example that injects an online JavaScript library to highlight the mouse. The resulting mouse pointer is shown subsequently.

options saved v1
Figure 10. BrowserWatcher options page (example for highlighting mouse)
js css injection example v1
Figure 11. JavaScript and CSS injection page example (highlighting mouse)

Alternatively, this feature can be enabled by executing the following JavaScript commands:

  • window.postMessage({ type: "injectJavaScriptCode", js: "jsCode" });

  • window.postMessage({ type: "injectJavaScriptLibs", lib: "jsLib" });

  • window.postMessage({ type: "injectCssSheets", css: "cssSheet" });

4. WebDriverManager

WebDriverManager provides seamless integration with BrowserWatcher. In other words, WebDriverManager allows injecting BrowserWatcher in browsers controlled with Selenium WebDriver and created through WebDriverManager with the methods .watch() and .create(). For example, the following test shows some basic use of video recording using WebDriverManager and BrowserWatcher:

class RecordChromeTest {

    WebDriver driver;
    WebDriverManager wdm;

    @BeforeEach
    void setup() {
        wdm = WebDriverManager.chromedriver().watch();
        driver = wdm.create();
    }

    @AfterEach
    void teardown() {
        driver.quit();
    }

    @Test
    void test() throws InterruptedException {
        driver.get(
                "https://bonigarcia.dev/selenium-webdriver-java/slow-calculator.html");

        wdm.startRecording();

        // 1 + 3
        driver.findElement(By.xpath("//span[text()='1']")).click();
        driver.findElement(By.xpath("//span[text()='+']")).click();
        driver.findElement(By.xpath("//span[text()='3']")).click();
        driver.findElement(By.xpath("//span[text()='=']")).click();

        // ... should be 4, wait for it
        WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
        wait.until(ExpectedConditions.textToBe(By.className("screen"), "4"));

        wdm.stopRecording();

        Path recordingPath = wdm.getRecordingPath();
        assertThat(recordingPath).exists();
    }

}

Please visit its documentation page for further details.

5. Further Documentation

There are other resources related to automated testing you can find helpful. For instance, the following books:

Or the following papers:

6. About

BrowserWatcher (Copyright © 2021-2025) is an open-source project created and maintained by Boni García (@boni_gg), licensed under the terms of Apache 2.0 License. This documentation (also available in PDF) is released under the terms of CC BY-NC-SA 2.0.