WebdriverIO is a next-generation browser and mobile automation framework for Node.js. Connect it to KnoxProxy to run geo-distributed E2E tests, validate region-specific pricing, and test localized content behind geographic restrictions.
Set up a new WDIO project with the CLI wizard.
npm init wdio@latest .
# Select local runner, mocha/jasmine, chromedriverAdd proxy capabilities to the browser configuration.
export const config: WebdriverIO.Config = {
capabilities: [{
browserName: 'chrome',
'goog:chromeOptions': {
args: [
'--proxy-server=http://gw.knoxproxy.com:7000',
],
},
}],
};Use a WDIO service or extension to supply proxy credentials.
// In wdio.conf.ts beforeSession hook
beforeSession(config, capabilities) {
process.env.HTTP_PROXY = 'http://USER:PASS@gw.knoxproxy.com:7000';
process.env.HTTPS_PROXY = 'http://USER:PASS@gw.knoxproxy.com:7000';
},Change the proxy username to target a specific country.
'goog:chromeOptions': {
args: [
'--proxy-server=http://gw.knoxproxy.com:7000',
],
},
// Set env: HTTP_PROXY=http://USER-country-br:PASS@gw.knoxproxy.com:7000For Firefox, use the proxy capability object.
capabilities: [{
browserName: 'firefox',
proxy: {
proxyType: 'manual',
httpProxy: 'gw.knoxproxy.com:7000',
sslProxy: 'gw.knoxproxy.com:7000',
},
}],Execute the WDIO test suite through the proxy.
HTTP_PROXY=http://USER:PASS@gw.knoxproxy.com:7000 \
npx wdio run wdio.conf.tsdescribe('Geo test via KnoxProxy', () => {
it('should show proxy exit IP', async () => {
await browser.url('https://httpbin.org/ip');
const body = await $('pre');
const text = await body.getText();
console.log('Exit IP:', text);
expect(text).toContain('origin');
});
it('should load localized content', async () => {
await browser.url('https://example.com');
const title = await browser.getTitle();
expect(title).not.toBe('');
});
});Each WDIO session gets a new browser instance and proxy connection. Use USER-session-{id} for sticky sessions across page navigations within a test. New test files get new IPs by default.
| Problem | Fix |
|---|---|
| ERR_PROXY_CONNECTION_FAILED in Chrome | Verify --proxy-server argument format. Ensure gw.knoxproxy.com:7000 is reachable. Check firewall rules. |
| WebDriverError: unknown error: net::ERR_TUNNEL_CONNECTION_FAILED | Confirm USER and PASS are correct. Use HTTP_PROXY env var with credentials for Chrome proxy auth. |
| Session creation timeout | Increase connectionRetryTimeout in wdio.conf.ts. Verify proxy is responsive with curl first. |
USER-country-de-city-berlin-session-profile07Order matters -- geo flags before the session flag. The session name is free text; use the profile ID so the mapping is self-documenting. Password stays as issued; no flags belong there. HTTP on :7000, SOCKS5 on :7001, same credentials.
Chrome does not support proxy authentication directly through WebDriver capabilities, since the "goog:chromeOptions" proxy-server argument accepts only host and port. Set HTTP_PROXY and HTTPS_PROXY environment variables with USER:PASS credentials in the beforeSession hook instead, or install a browser extension that handles the authentication prompt for you.
Yes, define multiple capabilities in wdio.conf.ts, each with a different --proxy-server argument or a different USER-country-{cc} value set via environment variables inside the beforeSession hook. WebdriverIO then launches a separate browser session per capability, so parallel sessions can exit through different KnoxProxy country IPs at once.
No, not through the same settings. Mobile testing with Appium requires device-level proxy configuration set through the device Wi-Fi settings or an Appium proxy capability, since the WDIO --proxy-server and Chrome capability options shown here apply only to desktop browser sessions and have no effect on real or emulated mobile devices.
The local runner works best with the wdio.conf.ts capability and beforeSession hook approach shown here, since it launches browsers directly on the machine running the tests. For the Selenium Grid runner, configure the proxy at the Grid node level instead, using HTTP_PROXY environment variables on each node.
Rotating residential proxies -- 5 minutes setup, instant activation, 14-day money-back guarantee.