PlaywrightPHP

Network configuration

Scope headers and proxies deliberately without hiding environment dependencies inside a test.

Headers and proxies both change how traffic reaches the application, but they belong at different levels:

  • headers describe a request or a browser context;
  • a proxy describes the network path used by the browser process.

Use the narrowest scope that matches the behaviour. Broad configuration is convenient, but it can silently affect navigation, assets, API calls, frames, and popups.

Set headers at the right level

Context headers apply to every page in that session:

php
$context = Playwright::chromium();
$context->setExtraHTTPHeaders([
    'X-Test-Suite' => 'browser',
]);

Use context headers when the whole scenario needs the same locale, feature flag, or test marker. Use per-call headers for one API setup request. Use a route handler when only matching browser traffic must change.

Need Scope
Header for the complete user session browser context
Header for one setup or verification call API request
Modify matching browser requests route handler
Inspect returned metadata response

Do not print authorization headers, cookies, session IDs, or internal routing values in CI logs.

Use a proxy for infrastructure

Proxy configuration belongs to browser launch:

php
$client = PlaywrightFactory::create();

$browser = $client->chromium()
    ->withProxy([
        'server' => 'http://proxy.example.test:8080',
        'bypass' => 'localhost,127.0.0.1',
    ])
    ->launch();

Use a proxy for controlled egress, private services, traffic recording, or a CI network requirement. Use routing when the test needs to mock or modify one endpoint.

Keep proxy settings in explicit project configuration or CI variables. A hidden local proxy is a reliable way to create “works on my machine” failures.

Common mistakes

  • Setting context headers after the first request.
  • Applying an auth header to more traffic than intended.
  • Routing localhost through a corporate proxy.
  • Committing proxy credentials.
  • Debugging a route handler while the proxy is the failing layer.
  • Assuming proxy and certificate behaviour is identical in every engine.

Go next