[nightt5879]

What?

Adds a proxy option to browser context options so callers can configure Chromium context-level proxy settings with:

const context = await browser.newContext({
  proxy: {
    server: 'http://proxy.test:8080',
    bypass: 'localhost,127.0.0.1',
  },
});

The option is wired to CDP Target.createBrowserContext through proxyServer and proxyBypassList, and invalid proxy options now fail early when proxy.server is missing.

Why?

Browser traffic currently cannot be routed through a proxy via the browser API. Environment proxy variables only affect k6's DevTools WebSocket connection, and global Chromium launch args are not equivalent to a browser context option.

This makes proxy configuration explicit in browser context options and keeps the behavior scoped to the created browser context.

Checklist

• I have performed a self-review of my code.
• I have commented on my code, particularly in hard-to-understand areas.
• I have added tests for my changes.
• I have run linter and tests locally (make check) and all pass.

Targeted tests run locally:

go test ./internal/js/modules/k6/browser/common ./internal/js/modules/k6/browser/browser

Checklist: Documentation (only for k6 maintainers and if relevant)

Please do not merge this PR until the following items are filled out.

• I have added the correct milestone and labels to the PR.
• I have updated the release notes: link
• I have updated or added an issue to the k6-documentation: grafana/k6-docs#NUMBER if applicable
• I have updated or added an issue to the TypeScript definitions: grafana/k6-DefinitelyTyped#NUMBER if applicable

Related PR(s)/Issue(s)

Closes #4432

[cla-assistant]

All committers have signed the CLA.

[Copilot]

Pull request overview

Adds support for configuring a Chromium context-level proxy via the k6 browser API by introducing a proxy option on browser.newContext() / browser.newPage() context options and wiring it to CDP Target.createBrowserContext parameters.

Changes:

• Introduces proxy configuration (server, bypass) on BrowserContextOptions, including early validation that proxy.server is required when proxy is provided.
• Wires proxyServer and proxyBypassList into the CDP Target.createBrowserContext call when creating a new browser context.
• Adds unit tests covering proxy mapping/parsing, CDP parameter wiring, and validation errors.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
internal/js/modules/k6/browser/common/browser.go	Validates proxy options and forwards proxy settings to CDP context creation.
internal/js/modules/k6/browser/common/browser_test.go	Adds unit tests ensuring proxy fields are sent (and omitted) correctly and invalid proxy config fails early.
internal/js/modules/k6/browser/common/browser_context_options.go	Extends context options with ProxyOptions and adds validation for required server.
internal/js/modules/k6/browser/browser/browser_mapping.go	Validates parsed proxy options when mapping JS values into Go options.
internal/js/modules/k6/browser/browser/browser_context_options_test.go	Adds JS-side parsing tests for proxy and integrates it into the “all options” test.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[inancgumus]

Thanks for your contribution 🙇 Current tests only verify internals. Please remove all current tests and instead add an integration test in the tests/ pkg that runs a fake proxy server to test the behavior of using a proxy server + the data transferred with and without the proxy options set. LMK if you have any questions.

[inancgumus]

Please use t.Context() in all tests.

[nightt5879]

Addressed in 38d0792.

Changes:

• removed the proxy-specific internal unit tests
• added TestBrowserContextProxy under internal/js/modules/k6/browser/tests
• the new integration test runs a fake HTTP proxy and verifies both direct and proxied browser context requests, including the request data forwarded through the proxy

Ran:

• go test ./internal/js/modules/k6/browser/tests -run TestBrowserContextProxy -count=1 -v -timeout 90s
• go test ./internal/js/modules/k6/browser/common ./internal/js/modules/k6/browser/browser -count=1
• go test ./internal/js/modules/k6/browser/tests -run 'TestBrowserContextProxy|TestBrowserContextOptions' -count=1 -timeout 120s

[inancgumus]

Same: require.NoError in handler goroutine.

[inancgumus]

Missing validation error test. Old unit tests covered "proxy without server" — now untested. Add a case: browser.newContext({ proxy: { bypass: 'foo' } }) asserting the error.

[nightt5879]

Addressed the latest review feedback in b81ec5c. The review threads are resolved now; could you take another look when you have a chance?

[inancgumus]

Thanks, @nightt5879. Please check if the test errors are introduced by your changes or not.

[nightt5879]

I checked the failing CI jobs to confirm whether they look related to this PR.

The previous red jobs were the Test workflow test-tip matrix jobs on Ubuntu/ARM/Windows. They were running Go tip:

go version go1.27-devel_d7a37379 Tue Jun 2 11:49:53 2026 -0700

The failures I found were in existing HTTP/TLS/HTTP2-related tests, for example:

• TestForceHTTP1Feature in go.k6.io/k6/v2/internal/js
• TestLoad in go.k6.io/k6/v2/internal/loader
• TestTLS13Support and cookie-related cases in go.k6.io/k6/v2/js/modules/k6/http
• TestHTTP2ConnectionError, TestHTTP2GoAwayError, TestX509HostnameError, and TestHTTP2StreamError in go.k6.io/k6/v2/lib/netext/httpext

The common error pattern was around TLS/HTTP2 behavior under gotip, e.g. remote error: tls: no application protocol, or different HTTP2 error strings/codes than the tests expected.

This PR only changes the browser context proxy implementation/tests, and in the same failed job the browser packages themselves passed, for example:

ok go.k6.io/k6/v2/internal/js/modules/k6/browser/browser
ok go.k6.io/k6/v2/internal/js/modules/k6/browser/chromium
ok go.k6.io/k6/v2/internal/js/modules/k6/browser/common
ok go.k6.io/k6/v2/internal/js/modules/k6/browser/storage

So from the logs, I don't think those CI failures were introduced by this PR. They look like gotip / Go HTTP-TLS behavior changes affecting existing tests outside the browser proxy changes.

Update after syncing with current master: the PR head is now 004f004ea6206c287cbef04ede2c3268c96630b6. The new GitHub Actions runs for Test, Browser tests, Build, Lint, etc. are currently action_required with no jobs started, so there are no fresh failure logs yet. The checks that did run on the updated head are passing:

• license/cla
• semgrep-cloud-platform/scan

Once the Actions workflows are approved/rerun, I can re-check the new CI result.

[inancgumus]

cc: @szkiba I've approved this PR.