extension

Documentation

Overview

Command extension is a chromedp example demonstrating how to install a browser extension, uBlock Origin Lite, into the browser that chromedp starts, and how to show that it blocks the ads of a page. The program loads a news page twice in one browser, first without the extension and then with it. It prints the number of ad slots that a reader can see, the requests that the extension blocked, the height of the page, and it writes the screenshots news-before.png and news-after.png.

Chrome 154 refuses an extension of Manifest V2, so the classic uBlock Origin does not load. The program loads uBlock Origin Lite, which is the Manifest V3 build of the same project. It has fewer features than the classic build. It blocks with the static rules of the declarativeNetRequest API and not with code that runs for each request, and the filter lists are fixed when the extension is built. The release that the author tested, 2026.930.1227, has custom filters, but the lists of the build cannot change at run time. The extension is not in this repository, because uBlock Origin is under the license GPLv3 and this repository is under the MIT license. The program never downloads it. Put it on disk yourself. See the error that the program prints when it finds no extension. Use -ext for the path of the unpacked directory, or of the ZIP file of the release. A ZIP file goes to a temporary directory that the program removes at the end. Without -ext, the program looks at the variable UBLOCK_EXTENSION, at the directory ublock in the current directory, and at the directory chromedp-examples/ublock in the configuration directory of the user.

The program installs the extension with the protocol command Extensions.loadUnpacked. Chrome runs this command only when the program starts it with the flag --enable-unsafe-extension-debugging, and only over the pipe that chromedp uses by default for its connection. The command works on the browser and not on a tab, so the program calls it with CallBrowser. The default options of chromedp hold the flag --disable-extensions, so the program turns it off. Chrome 154 runs extensions in the new headless mode, which the flag --headless starts, so the program needs no other flag. The flag --load-extension does not work, because branded Chrome 137 and later ignores it. Because the command needs the pipe, the option KeepOpen of chromedp does not work with this program, as KeepOpen uses a websocket.

A profile is the user data directory of the browser. The flag -profile names one, and the program creates it if it does not exist. Without the flag, the program makes a temporary profile, prints its name and removes it at the end. A profile keeps what the extension saves in its storage. The program switches the extension to the complete filtering mode, which also hides the generic ad elements, and the profile keeps that choice for the next run. The profile does not keep the installation. The command loadUnpacked loads the extension for this browser session only, so each start must load it again. Chrome makes the identifier of an unpacked extension from its path, so the next run finds the storage only when the extension is in the same directory. A ZIP file goes to a new temporary directory in each run, so use an unpacked directory with a profile that you keep.

The test site serves the page. The page asks for scripts, images and a tracking pixel of the real hosts of ad networks, such as pagead2.googlesyndication.com and ad.doubleclick.net. The program never sends a request to these hosts. In the first run, it answers each request with the Fetch domain and a small response of its own, so that the page shows its ads without internet. In the second run, the same interception stays on. The extension decides first. It stops some requests before the Fetch domain sees them, and the page reports them as failed with net::ERR_BLOCKED_BY_CLIENT. It redirects other requests to a harmless script of its own, and the program does not match that address. So in the second run the program answers no request, and the page shows no ad. It starts a local server and needs no internet, but the extension must be on disk. Use -url to read another site with the same structure. Use -v to print the protocol messages and -visible to show the browser window. A visible browser closes when you close its window, because the program waits for you and then ends. Use -visible-on-terminal to draw the page in the terminal with terminal graphics. The program loads both runs in one tab, so the drawing follows the page through both runs.