Testing

Integration testing for the Browser Ad-Filtering Solution.

Controlling ad filtering

You may use the example UI to control ad filtering settings.

Smoke testing

You may use these scenarios for quickly checking if ad-filtering works in your browser.

Scenario 1: Verify ads are blocked when ad filtering is ON and Acceptable Ads are OFF.

Given I have ad filtering enabled and AA disabled on eyeo Browser Ad-Filtering Solution .
When I open "https://www.ask.com"
And search for "laptops"
Then I verify that ads are not displayed

Scenario 2: Verify ads are blocked when ad filtering is ON and Acceptable Ads are ON.

Given I have ad filtering enabled and AA disabled on eyeo Browser Ad-Filtering Solution
When I open "https://www.ask.com"
And search for "laptops"
Then I verify that ads are displayed.

Scenario 3: Verify ads are displayed when ad filtering is OFF.

Given I have ad filtering disabled on eyeo Browser Ad-Filtering Solution
When I open "https://www.ask.com"
And search for "laptops"
Then I verify that ads are displayed.

Scenario 4: Verify allowlisting feature is working properly.

Given I have ad filtering enabled
When I add www.wikihow.com to allowlisted domains and
And open a subpage on www.wikihow.com
Then I verify that ads are displayed

Testing on ABP testpages

ABP testpages are designed to test the ad-filtering code against various types of html elements in a controlled environment.

You need to enable More Blocking Options in order to run these tests.

Scenario 1 : Testing ABP testpages using custom filter lists

1. On the More blocking options screen, select the option of Custom Filter lists.

2. Enter the URL https://abptestpages.org/en/abp-testcase-subscription.txt in the text field and tap on the + icon.

3. Navigate to Blocking - ABP Test Pages.

4. Verify that you see green boxes, according to the descriptions of the test cases

Scenario 2 : Testing ABP testpages using custom filters

Alternatively, you can try adding custom filters rather than a custom filter list. This takes more effort but avoids unexpected interplay between filters defined for different test cases.

1. Navigate to ABP Test Pages and click on the page you wish to test. For example: https://abptestpages.org/en/filters/blocking

2. Copy the filter mentioned on the testpage corresponding to the scenario under test.

3. On the More blocking options screen, select the option of Custom Filters.

4. Paste the filter to the custom filter field and refresh the page under test.

5. Verify the test state matches the test case description, typically by showing a green box.

Filter lists

The eyeo Browser Ad-Filtering Solution needs filter lists in order to filter ads. Filter lists define which web resources should be blocked or hidden.

Default filter lists

On first run, the browser will attempt to download and install the following default filter lists:

• Easylist,

• Acceptable Ads (assuming Acceptable Ads is enabled by default),

• Anti-Circumvention

The Solution attempts to select a language-specific variant of Easylist, for example Easylist+spanish if the device's language is Spanish. Not all languages have such variants.

It will take a couple of seconds to download and install these lists. The user is free to browse the web while this is happening, and the Solution falls back to built-in, preloaded variants of the default lists to provide some level of ad-filtering.

Downloading a filter list

The Solution downloads filter lists when:

• The browser starts for the first time and the default lists are installed

• The user selects a new list in the Language Filters menu

• The user adds a new custom filter list in the More Blocking Options menu

• A filter list expires and needs to be updated

Every filter list download is a GET request to the URL of the filter list with a set of extra GET parameters.

GET parameters

The Solution reports some information to eyeo via GET parameters added to the URL of each filter list.

This information is designed to preserve the user's anonymity and is used to:

• Count how many active users your browser attributes to the Acceptable Ads program

• Collect insights about what platforms eyeo should focus development efforts on

Parameter	Value
addonName	eyeo-chromium-sdk
addonVersion	1.0
application	The name of for your product.
applicationVersion	Follows Chromium's versioning by default, but can be overridden to reflect your product's version.
platform	Windows, MacOSX, Linux or Android, depending on the operating system.
platformVersion	1.0
lastVersion	Version of the filter list that is being updated, for example 202111101251. Version is normally parsed from the filter list's "! Version: 202111101251" header comment. 0 if it's a new download or when a filter list doesn't declare a version.
disabled	true when Acceptable Ads is disabled in settings, false if it's enabled.
downloadCount	Total number of successful update downloads of the subscription. For anonymity reasons, clamped between 0 and 4+.

An example:

https://easylist-downloads.adblockplus.org/exceptionrules.txt?addonName=eyeo-chromium-sdk&addonVersion=1.0&application=Chromium&applicationVersion=110.0.5476.3&platform=Linux&platformVersion=1.0&lastVersion=202301021041&disabled=false&downloadCount=3

Periodic pings of Acceptable Ads filter list

To not lose track of users that have disabled Acceptable Ads, the SDK performs periodic pings .

A ping is a HEAD-type filter list download request, very similar to ordinary filter list download requests. Because it's a HEAD (and not GET) request, the server will not respond with filter list content and the browser will not download Acceptable Ads. However the server will be made aware of the user's existence.

Pings are sent every 24 hours while Acceptable Ads is disabled. They are visible as HEAD requests to:

https://easylist-downloads.adblockplus.org/exceptionrules.txt?addonName=eyeo-chromium-sdk&...&disabled=true

Periodic updates

The browser updates the filter lists according to their expiry times - typically every 24 hours. In order to check if filter lists are updated upon expiration, do the following:

1. Let all the default filter lists download successfully.

2. On Android, force stop the application

3. Navigate to phone settings to advance the time by 25 hours.

4. Launch the application.

5. Filter lists download requests should be sent to the server with an increased downloadCount in request parameter.

6. If you have enabled VLOGs, you should see relevant logs in the system console, for example:

... [eyeo] Running update check
... [eyeo] Updating expired subscription https://easylist-downloads.adblockplus.org/abp-filters-anti-cv.txt
... [eyeo] Downloading https://easylist-downloads.adblockplus.org/abp-filters-anti-cv.txt?addonName=eyeo-chromium-sdk&...&downloadCount=4+
... [eyeo] Finished downloading https://easylist-downloads.adblockplus.org/abp-filters-anti-cv.txt, starting conversion
... [eyeo] Finished converting https://easylist-downloads.adblockplus.org/abp-filters-anti-cv.txt successfully
... [eyeo] Updated subscription https://easylist-downloads.adblockplus.org/abp-filters-anti-cv.txt, current version 202301121221

Verifying Eyeometery

To learn about Eyeometry refer to: user counting

1. The browser sends an Eyeometry ping every 12 hours. You should see it in browser logs if you have enabled VLOGs

... [eyeo] Telemetry request for https://eyeo-chromium.telemetry.eyeo.com/topic/eyeochromium_activeping/version/1 is due
... [eyeo] Telemetry request for https://eyeo-chromium.telemetry.eyeo.com/topic/eyeochromium_activeping/version/1 starting now
... [eyeo] Sending request to: https://eyeo-chromium.telemetry.eyeo.com/topic/eyeochromium_activeping/version/1
... [eyeo] Telemetry ping succeeded

2. If you see this line in the logs, your product wasn't built with a valid client id

[eyeo] Using default Telemetry server since a Telemetry client ID was not provided. Users will not be counted correctly by eyeo. Please set an ID via "eyeo_telemetry_client_id" gn argument.`

3. If you see this line in the logs, your product wasn't built with a valid auth token

[eyeo] No Telemetry authentication token defined. Users will not be counted correctly by eyeo. Please set a token via "eyeo_telemetry_activeping_auth_token" gn argument.

Logging

eyeo Chromium SDK uses the following levels of logging:

1. LOG(INFO/WARNING/ERROR) - these logs appear in all builds. These are emitted relatively rarely, to avoid clutter.

2. DLOG(INFO/WARNING/ERROR) - these logs appear in debug build only

3. VLOG(1/2/3/...) - these logs appear in all builds if vmodule flag is set

4. DVLOG(1/2/3/...) - same as VLOG but only in debug builds

The browser writes these logs to the system console, also known as standard output. Do not confuse this with the Developer Tools console within the Inspector window.

See also Chromium's instructions on logging

Steps to enable VLOG/DVLOG

Android

1. Ensure Enable command line on non-rooted devices in chrome://flags is enabled

2. Run the following command:

adb shell 'echo _ --enable-logging=stderr --vmodule="*subscription*=1,*activeping*=1,*adblock*=1,*converter*=1,*filtering_configuration*=1" > /data/local/tmp/chrome-command-line'

Note: the flag persists until it is cleared

1. Launch the app now, manually, by tapping the icon on phone

2. Run adb logcat to view logs

Note: To check the currently set command line flags, run the command:

adb shell 'cat /data/local/tmp/chrome-command-line'

To clear the currently set flags:

adb shell 'rm /data/local/tmp/chrome-command-line'

Desktop

Run the browser executable with following arguments: --enable-logging=stderr --vmodule="*subscription*=1,*activeping*=1,*adblock*=1,*converter*=1,*filtering_configuration*=1