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 relies on the system HTTP_PROXY and HTTPS_PROXY environment variables. Include username:password in the URL (e.g., http://USER:PASS@gw.knoxproxy.com:7000).
Yes. Set different HTTP_PROXY values in separate npm scripts or CI pipeline steps to route each suite through a different country.
Yes. Both cy.visit() and cy.request() respect the HTTP_PROXY environment variable, so all traffic flows through KnoxProxy.
Cypress does not natively support SOCKS5 proxies. Use the HTTP proxy on port 7000 instead, or route through a local HTTP-to-SOCKS5 bridge.
Free trial on rotating residential -- 5 minutes setup, no credit card.