adblockplus
1.0.0
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.
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 should come installed with npm. If it doesn't, you can
download npm here.
node-gyp error?If you're using an apple machine with apple silicon (arm64 CPU), you may
encounter an error where node-gyp fails to build during npm install. In that
case you need to run arch -x86_64 zsh before any other commands, and make sure
you are not using nvm to run the node version.
Another possible cause is that node-gyp cannot find the binary online,
then tries to build the binary locally and fails because of Python 3.12 being
installed, which does not work work with some versions of node-gyp.
That could be solved by installing Python 3.11 locally, and
pyenv could be used for that.
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.
These are pages that are dedicated to a specific feature and can be accessed via UI pages.
These are pages that cannot be accessed via UI pages. They are either directly or indirectly opened by the extension under certain conditions.
These are pages that are part of another page. They are not meant to be shown on their own.
These are parts of the extension logic which are running alongside the other extension code in the extension's background process.
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.
The ./test/unit folder contains various mocha unit tests files
which can be run via npm run $ unit.legacy. For .ts files we have jest
unit tests that can be run via npm run $ unit.standard.
Those can be run together via npm test.
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.
To run the end-to-end tests locally:
Example:
cp .env.e2e.template .env.e2e
npm run build:release {chrome|firefox} -- --manifest-version {2|3}
MANIFEST_VERSION={2|3} BROWSER={chrome|firefox|edge} npm run test:end-to-end-local allTo run the end-to-end tests using LambdaTest:
npm run test:end-to-end all or
npm run test:end-to-end-mv3 all.You can replace all tests with a specific test suite (e2e, integration,
smoke).
If you only want to execute a single test file, you can replace the value of the
all property in suites.js
to an array containing only the path
to the test(s) you want to run. Example:
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.
Screenshots of failing tests get saved to test/end-to-end/screenshots
Compliance tests run on a local version of testpages to assure compliance between Adblock Plus and other eyeo adblocking solutions. They run the tests from the testpages project using a local build of the Adblock Plus extension.
Prerequisites:
To run the tests:
EXTENSION=dist/release/<build file> MANIFEST={mv2|mv3} ./test/compliance.shOptional environment variables:
You can lint all files via npm run lint or lint only specific file types:
npm run eslint
npm run $ lint.css
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
The project uses Gitlab CI to run pipelines which contain build and test jobs.
Nightly builds for feature and release branches can be found as artifacts from this page.
Pipeline jobs use self-managed runners from Google Cloud Platform (GCP). The the setup of the runner is defined in the devops runner project, and the runner status can be checked here. Access to GCP resources like the GCloud console can be granted by devops as well.
Copy the .env.defaults file in the root directory to a .env file and fill in
the variables accordingly. This step can be skipped, and is only required if
you wish to enable the sending of CDP data.
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:sourceTargets:
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:
build:source: Creates the following source archive file in dist/release/
that can be provided to extension stores for review purposes:
--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.
We use Sentry to report the errors. In order to initialize it
during the build one has to pass ADBLOCKPLUS_SENTRY_DSN and ADBLOCKPLUS_SENTRY_ENVIRONMENT
variables in either .env file or as environment variable during the (CI) build. If not
initialized, console warning is shown. By default ADBLOCKPLUS_SENTRY_ENVIRONMENT=production.
User emails are cut on client side and data scrubbing on
server side is
configured by default.
Extension releases (since 3.11)
Extension releases (prior to 3.11)
This project follows the typical GitLab process:
