Cypress is a developer-friendly E2E testing framework that runs directly in the browser. Pair it with KnoxProxy to run geo-targeted test suites, verify region-locked content, and validate localized experiences from any country without leaving your desk.
Add Cypress to your project as a dev dependency.
npm install --save-dev cypress
npx cypress openCypress uses system HTTP_PROXY and HTTPS_PROXY environment variables. Set them before launching.
export HTTP_PROXY=http://USER:PASS@gw.knoxproxy.com:7000
export HTTPS_PROXY=http://USER:PASS@gw.knoxproxy.com:7000Add proxy-aware settings to your Cypress configuration file.
import { defineConfig } from 'cypress';
export default defineConfig({
e2e: {
baseUrl: 'https://httpbin.org',
setupNodeEvents(on, config) {
// Proxy env vars are inherited automatically
},
},
// Increase timeouts for proxied connections
defaultCommandTimeout: 15000,
pageLoadTimeout: 30000,
});Append the country code to the username for geo-targeted tests.
export HTTP_PROXY=http://USER-country-gb:PASS@gw.knoxproxy.com:7000
export HTTPS_PROXY=http://USER-country-gb:PASS@gw.knoxproxy.com:7000API requests via cy.request() also flow through the proxy when env vars are set.
cy.request('https://httpbin.org/ip').then((response) => {
expect(response.status).to.eq(200);
cy.log('Exit IP:', response.body.origin);
});Launch Cypress with proxy variables active.
HTTP_PROXY=http://USER:PASS@gw.knoxproxy.com:7000 \
HTTPS_PROXY=http://USER:PASS@gw.knoxproxy.com:7000 \
npx cypress run --browser chromedescribe('Geo-targeted test via KnoxProxy', () => {
it('should exit from the proxy IP', () => {
cy.visit('https://httpbin.org/ip');
cy.get('pre').should('exist');
});
it('should verify geo-located content', () => {
cy.request('https://httpbin.org/ip').then((resp) => {
expect(resp.status).to.eq(200);
expect(resp.body).to.have.property('origin');
cy.log('Exit IP: ' + resp.body.origin);
});
});
it('should load localized page', () => {
cy.visit('https://example.com');
cy.title().should('not.be.empty');
});
});Each Cypress test run uses the IP assigned at connection time. For sticky sessions, use USER-session-{id} in the proxy username. For a new IP per spec file, restart the proxy env between runs.
| Problem | Fix |
|---|---|
| CypressError: cy.visit() failed -- ECONNREFUSED | Verify HTTP_PROXY and HTTPS_PROXY are exported in the same shell session. Confirm port 7000 is open. |
| Timed out retrying after 15000ms | Increase defaultCommandTimeout and pageLoadTimeout in cypress.config.ts to 20000-30000ms. |
| SSL certificate error | Set NODE_TLS_REJECT_UNAUTHORIZED=0 for testing environments only, or add the proxy CA to your trust store. |
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.
Cypress has no built-in proxy authentication dialog, so it relies entirely on the system HTTP_PROXY and HTTPS_PROXY environment variables you export before launching. Include USER:PASS credentials directly in that URL, for example http://USER:PASS@gw.knoxproxy.com:7000, and Cypress passes them through automatically for both cy.visit() and cy.request() calls.
Yes, set a different HTTP_PROXY and HTTPS_PROXY value in separate npm scripts, or as separate steps in your CI pipeline, one per test suite. Each script can point to a different country username, for example USER-country-gb for one suite and USER-country-us for another, so suites run against different regional exit IPs.
Yes, both cy.visit() and cy.request() respect the same HTTP_PROXY and HTTPS_PROXY environment variables, since Cypress applies them at the process level rather than per command. That means browser navigation and direct API assertions inside a spec all flow through KnoxProxy together, exiting from the same proxy IP.
Cypress does not natively support SOCKS5 proxies through its HTTP_PROXY environment variable mechanism. Use the standard KnoxProxy HTTP endpoint on port 7000 instead, which covers the same country and session targeting, or route SOCKS5 traffic through a local HTTP-to-SOCKS5 bridge process if your workflow specifically requires the SOCKS5 protocol.
Rotating residential proxies -- 5 minutes setup, instant activation, 14-day money-back guarantee.