Welcome to the repository for the Adblock Plus extension!

The main project is hosted on GitLab and, in addition to the user interface and the web extension code, the Adblock Plus extension also includes static filter lists, eyeo's Web Extension Ad Blocking Toolkit (EWE) and eyeo's snippets.

• About Adblock Plus
• Prerequisites
• UI elements
• Testing
• Building
• Contributing

Adblock Plus is a free extension that allows users to customize their web experience. Users can block annoying ads, disable tracking and lots more. It’s available for all major desktop browsers and for mobile devices.

Adblock Plus is an open source project licensed under GPLv3 and subject to its Terms of Use. eyeo GmbH is the parent company of Adblock Plus.

To contribute to this project, you'll need:

• Node >= 18.17.1; <19
• npm 9

Node should come installed with npm. If it doesn't, you can download npm here.

Important: On Windows, you need a Linux environment running on WSL and run the commands from within Bash.

Tip: If you're installing node in ArchLinux, please remember to install npm, too.

After cloning this repository, open its folder and run npm install.

Specifications for Adblock Plus elements can be found in eyeo's spec repository.

These are pages that users primarily interact with because they are exposed to them via the browser's UI.

• Bubble UI (popup)
• Developer tools panel (devtools-panel)
• Options
  • Desktop (desktop-options)
  • Mobile (Firefox) (mobile-options)

These are pages that are dedicated to a specific feature and can be accessed via UI pages.

• Filter composer (composer)
• Issue reporter (issue-reporter)

These are pages that cannot be accessed via UI pages. They are either directly or indirectly opened by the extension under certain conditions.

• Day 1 (day1)
• First run (first-run)
• Problem (problem)
• Updates (updates)

These are pages that are part of another page. They are not meant to be shown on their own.

• Bubble UI dummy (popup-dummy)
• Proxy (proxy)

These are parts of the extension logic which are running alongside the other extension code in the extension's background process.

• Notifications
• Preferences

If you don't want to build the entire extension, you can open UI pages in a test environment using a local web server. This can be done by running npm start, which allows you to access the HTML pages under the URL shown in the terminal, e.g. http://127.0.0.1:8080.

Various aspects of the pages can be tested by setting parameters in the URL (see list of URL parameters).

Note: You need to create the bundles for the UI page(s) that you want to test.

Nightly builds for feature and release branches can be found as artifacts from this page.

The ./test/unit folder contains various unit tests files. Those can be run together with other tests via npm test or separately via npm $ test.unit.

The ./test/integration folder contains various integration tests files. Those can be run together with other tests via npm test or separately via npm $ test.integration.

The ./test/end-to-end/tests folder contains various end-to-end tests. These tests can be executed locally, (in the latest stable Chrome, Firefox and Edge browsers) or they can be executed using LambdaTest.

a) To run the end-to-end tests locally, the unpacked development builds of the extension should be generated. After generating the required extension builds for Chrome, and Firefox,

• Run the test:end-to-end-local npm script npm run test:end-to-end-local

NOTE: If you only want to execute a single test file, you can replace the value of the specs constant in the local-test.conf.js to an array containing only the path to the test(s) you want to run

e.g

const specs = ["./tests/test-options-page-dialog-links.js"];

b) To run the end-to-end tests using LambdaTest, the release builds of the extension should be generated. After generating the required builds, take the following steps:

• Create a new .env file with your Lambda credentials. You can use the .env.e2e.template provided as a guide.

• Run the test:end-to-end npm script npm run test:end-to-end all, or replace the all part with the desired test suite (e2e, integration, smoke).

NOTE: If you only want to execute a single test file, you can replace the value of the all property in the base.conf.js to an array containing only the path to the test(s) you want to run. e.g

all: ["./tests/test-options-page-dialog-links.js"],

Allure reporter is used for displaying the results after the execution has been completed. The report can be generated and opened using the npm run test:generate-and-open-report command.

You can lint all files via npm run lint or lint only specific file types:

• JavaScript/TypeScript: npm run eslint
• CSS: npm run $ lint.css
• Translation files: npm run $ lint.locale

Note: Both eslint and stylelint can help fix issues via --fix flag. You can try the example below via npx which should be automatically included when you install npm.

npx stylelint --fix css/real-file-name.css

In order to build the extension you need to first update its dependencies. You can then run the following command for the type of build you'd like to generate:

npm run build:{dev|release} {chrome|firefox|local} [-- <options>]

or

npm run build:source

Targets:

• chrome: Chromium-based browsers
• firefox: Firefox
• local: Local test environment

build:dev: Creates unpacked extension in dist/devenv/<target>/. It can be loaded under chrome://extensions/ in Chromium-based browsers, and under about:debugging in Firefox.

build:release: Creates the following extension build files in dist/release/ that can be published to the various extension stores:

• adblockpluschrome-*.zip
• adblockplusfirefox-*.xpi

build:source: Creates the following source archive file in dist/release/ that can be provided to extension stores for review purposes:

• adblockplus-*.tar.gz

--config <*.js file path>: Specify a path to a new configuration file relative to adblockpluschrome/gulpfile.js (see examples in adblockpluschrome/build/config/).

--manifest-path <*.json file path>: Specify a path to a new manifest.json file relative to adblockpluschrome/gulpfile.js (see examples in adblockpluschrome/build/tasks/manifest.js).

--manifest-version 3 or -m 3: Generate a build that's compatible with WebExtensions Manifest version 3. If omitted, it will generate a build for Manifest version 2.

--partial true: Run a build that will not re-build the icons, the rules and the UI. This is useful if your new changes do not touch any of the beforementioned parts of the extension, and you can benefit from the faster build time. Note that you must have a run a full build once before you can succesfully run a partial build.

Install the required npm packages:

npm install

Rerun the above commands when the dependencies might have changed, e.g. after checking out a new revision.

Various files need to be generated before using the UI. When building the UI for inclusion in the extension, this is achieved using npm run dist.

For usage in the test environment, run the build:dev script to generate the various bundles for all UI elements.

Beyond that, this repository contains various utilities that we rely on across our development process.

Extension releases (since 3.11)

Extension releases (prior to 3.11)

This project follows the typical GitLab process:

1. Fork it.
2. Create your feature branch.
3. Commit your changes.
4. Push to the branch.
5. Create a new merge request.