debug-rules.md

title	How to debug rules in AdGuard for Chrome MV3
sidebar_position	2

In AdGuard for Chrome MV3, the Filtering log only shows the approximate rules that were applied, which we call “assumed rules”. This is because the browser doesn’t provide details about which specific declarative rules were used unless the extension is in an “unpacked” format. To get precise information, you’ll need to install the unpacked version of the extension in your browser yourself.

These instructions are also meant for problematic cases where you want to modify the rules that are bundled with the extension statically. In most cases, using User rules in the extension should be sufficient.

Prerequisites

1. Git: Install Git

2. Node: Install Node.js

3. pnpm: Install pnpm

How to clone extension

1. Clone the repository:

   git clone git@github.com:AdguardTeam/AdguardBrowserExtension.git

2. Navigate to the directory:

   cd AdguardBrowserExtension

3. Install dependencies:

   pnpm install

How to build extension

1. Run the following command in the terminal:

   pnpm dev chrome-mv3

2. The built extension will be located in the directory:

   ./build/dev/chrome-mv3

How to install unpacked in the browser

1. Turn on developer mode:

   

2. Click Load unpacked:

   

3. Select the extension directory and click Select:

   

That’s it!

How to debug rules

1. First, build the extension (skip this step if you already did so in the How to build extension section):

   pnpm dev chrome-mv3

2. Convert filters to DNR rulesets automatically:

   To speed up the development of DNR rulesets, use the @adguard/dnr-rulesets watch command. This command automatically rebuilds rulesets whenever filter files change.

   Start watch mode with all required filters:

   npx @adguard/dnr-rulesets watch \
       # Enable rulesets with IDs 1 and 2
       --enable=1,2 \
       # Download filters from the server on the first run
       --load \
       # Path to the extension manifest
       ./build/dev/chrome-mv3/manifest.json \
       # Path to web-accessible-resources directory (needed for $redirect rules)
       ./Extension/web-accessible-resources

   The --load flag will download all filters from the server on the first run. For subsequent runs, you can omit this flag to use existing filters:

   npx @adguard/dnr-rulesets watch \
       # Enable rulesets with IDs 1 and 2
       --enable=1,2 \
       # Path to the extension manifest
       ./build/dev/chrome-mv3/manifest.json \
       # Path to web-accessible-resources directory (needs for $redirect rules)
       ./Extension/web-accessible-resources

   Now, whenever you modify filter files, the DNR rulesets will rebuild automatically, so you won’t have to rebuild the entire extension.

OR

2. Convert filters to DNR rulesets manually:

   If you do not want to use watch mode and only need a single run, you can do it directly via the @adguard/tsurlfilter CLI command convert — it will convert filters to DNR rulesets:

   npx @adguard/tsurlfilter convert \
       # Enable extended logging about rulesets
       --debug \
       # Path to the directory with raw txt filters
       ./build/dev/chrome-mv3/filters \
       # Path to web-accessible-resources directory (needed for $redirect rules)
       ./Extension/web-accessible-resources \
       # Destination path for converted DNR rulesets
       ./build/dev/chrome-mv3/filters/declarative

   After the conversion is done, you can manually update the ruleset information in manifest.json if needed: enable, add, or remove rulesets as required.

3. Reload the extension in the browser after conversion:

   

4. If you see an exclamation mark, it means the assumed rule (calculated by our tsurlfilter engine using MV2 rules) and the applied rule (converted to a DNR rule) are different. This can indicate a conversion problem.

   Otherwise, if the assumed and applied rules are the same, only the applied rule, in both raw text and declarative rule views, will be shown.