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 auth via capabilities directly. Set HTTP_PROXY env vars with credentials, or use a browser extension for auth.
Yes. Define multiple capabilities with different --proxy-server arguments or env vars per session in the beforeSession hook.
Mobile proxy requires device-level proxy config. WDIO proxy settings apply to desktop browsers only.
The local runner works best. For the Selenium Grid runner, configure proxy at the Grid node level instead.
Free trial on rotating residential -- 5 minutes setup, no credit card.