Proxy Testing

Proxy Testing

This skill provides a JS library to run autoconsent via regional proxies in Playwright. It is the default for regional testing.

Oxylabs remote browsers are available too, through the oxylabs-testing skill. They get past most bot walls (captchas, challenge pages, "access denied" pages) that some sites show to our proxies, but they cost money per session, so use them only for the regions where our proxies don't get you the real site.

Rule changes are verified with a two-level regional policy. The core region set (default for detection, iteration, and verification) covers us (CCPA), gb (UK GDPR), de (EEA GDPR), plus the reported region from the task when specified (if the reported region is not a supported proxy region, use the closest supported one, e.g. es for pt). Iterate in the single most relevant region; run the full core set once when the fix is stable.

Escalate to the expanded set (us, gb, de, fr, nl, pl, au, ca, jp) if any of these is true:

• core results diverge
• the rule contains region-dependent logic
• the fix relies on language-specific or brittle structural selectors
• the change touches a widely-used generic rule (as final pre-PR validation)
• a non-core region named in the report behaves differently.

The remaining GDPR/EEA regions (ch, no, it, es, se, dk) are optional even in an expanded pass: test them only when named in the report or clearly relevant (e.g. the site's ccTLD).

Important! Autoconsent results can have false positives. When testing, always inspect the screenshots and confirm that opt-out was successful.

Prerequisites

npm run prepublish # builds dist/autoconsent.playwright.js and rules/rules.json

Environment variables:

• REGIONAL_PROXY_<TWO_LETTER_REGION_CODE> (for example, REGIONAL_PROXY_US, REGIONAL_PROXY_GB, REGIONAL_PROXY_AU, etc.) - a complete proxy URL with an http://, https://, or socks5:// scheme. Examples: socks5://usc-socks-tr-cluster.duckduckgo.com:80, https://proxy.example.com:443.
• REGIONAL_PROXY_USERNAME and REGIONAL_PROXY_PASSWORD (optional) - shared credentials, passed to Playwright for https:// proxies only. They are ignored for http:// and socks5:// proxies.

Never embed credentials in a proxy URL.

Usage

Test one URL:

import { formatResult, testUrl } from './.agents/skills/proxy-testing/scripts/regional-proxy.mjs';

const result = await testUrl('https://www.wohnen.de/', 'de');
console.log(formatResult(result));

Test multiple regions:

import { formatResult, testRegions } from './.agents/skills/proxy-testing/scripts/regional-proxy.mjs';

const results = await testRegions('https://www.wohnen.de/', ['us', 'de', 'fr']);
for (const result of results) {
    console.log(formatResult(result));
}

Use an existing page:

import { launchRegionalProxyBrowser, testPage } from './.agents/skills/proxy-testing/scripts/regional-proxy.mjs';

const browser = await launchRegionalProxyBrowser('de');
const page = await browser.newPage();
const result = await testPage(page, 'https://www.wohnen.de/', 'de');
await browser.close();

Get proxy config for Playwright Test:

import { defineConfig } from '@playwright/test';
import { buildProxyConfig } from './.agents/skills/proxy-testing/scripts/regional-proxy.mjs';

export default defineConfig({
    use: {
        proxy: buildProxyConfig('us'),
    },
});

API

• testUrl(url, regionKey, options?) — test one URL in a single region; launches a proxied browser, runs autoconsent, returns a TestResult.
• testRegions(url, regions?, options?) — test one URL across several regions (defaults to CORE_REGIONS), a fresh browser per region; returns TestResult[]. Remember to include the reported region when not already covered.
• CORE_REGIONS — the core region set (default); add the reported region when not already covered.
• EXPANDED_REGIONS — the expanded region set used on escalation.
• ALL_REGIONS — all supported regions.
• testPage(page, url, regionKey, options?) — run a full test on a page you created yourself (you own the browser/context); returns a TestResult.
• injectAutoconsent(page, options?) — set up isolated-world injection; call before page.goto(). Returns a context (received, hasMessage, waitForCompletion, waitForMessage, collectResult).
• buildProxyConfig(regionKey) — build the Playwright proxy object for a region from its env vars; returns { server, username, password } for https:// proxies when credentials are set, otherwise { server }.
• launchRegionalProxyBrowser(regionKey, options?) — launch a Chromium browser routed through the region's proxy.
• formatResult(result) — format a TestResult as a human-readable summary line.

Options (all optional):

• action — 'optOut' (default), 'optIn', or null to only detect (no opt-out/opt-in performed).
• screenshotsDir — directory for the final screenshots (default: test-results/regional-proxy).
• navigationTimeout — page.goto timeout in ms (default 45000).
• completionTimeout — max wait for autoconsent to finish opt-out/opt-in in ms (default 45000).
• detectionTimeout — max wait for cmpDetected before giving up (default: completionTimeout).
• headless — run Chromium headless (default true).
• launchOptions — extra options merged into chromium.launch() (e.g. args); the regional proxy is always applied on top.