How to Capture Screenshots of a Website Behind a Corporate Proxy
Configure Playwright to reach a website through your corporate proxy, capture a viewport, full page, or element, and troubleshoot common network issues.
To capture a website behind a corporate proxy, configure the proxy on a Playwright browser or browser context, navigate to the site, and save a viewport, full-page, or element screenshot. You will need your organization’s proxy address, protocol, authentication details, and certificate instructions from IT. Playwright supports HTTP(S) and SOCKSv5 proxies, and proxy settings can apply to a whole browser or an individual context. Playwright’s network documentation describes both approaches.
1. Get the proxy details from your organization
Ask your IT or browser administrator for the values that apply to your environment:
- Proxy server address and port.
- Supported protocol: HTTP(S) or SOCKSv5.
- Whether the proxy requires credentials, and which authentication format to use.
- Whether the browser or automation runtime needs an organization root certificate.
- Whether the target website must be on an allowlist, or whether automation is restricted by managed-browser policy.
There is no universal corporate proxy URL or credential. Do not substitute the target site’s username and password for proxy credentials: proxy authentication belongs in Playwright’s proxy configuration, while a site login is handled separately by the page.
2. Install Playwright and its browser
The example below uses Node.js and Playwright’s bundled Chromium. In a project directory, install Playwright and its browser:
npm init -y
npm install playwright
npx playwright install chromiumIf your organization requires a proxy for browser downloads, set HTTPS_PROXY before the install command. See Playwright’s browser installation guide for the documented download proxy and certificate settings.
3. Configure the proxy and capture a screenshot
Save this as capture.mjs. Replace the proxy endpoint and target URL with values approved for your network. Set credentials through environment variables rather than committing them to source control.
import { chromium } from 'playwright';
const proxy = {
server: process.env.PROXY_SERVER, // e.g. http://proxy.example.com:8080
...(process.env.PROXY_USERNAME ? { username: process.env.PROXY_USERNAME } : {}),
...(process.env.PROXY_PASSWORD ? { password: process.env.PROXY_PASSWORD } : {}),
};
if (!proxy.server) {
throw new Error('Set PROXY_SERVER to the proxy URL provided by your organization.');
}
const browser = await chromium.launch({ proxy });
try {
const context = await browser.newContext();
const page = await context.newPage();
const response = await page.goto('https://example.com', {
waitUntil: 'domcontentloaded',
timeout: 60_000,
});
if (!response) {
throw new Error('Navigation returned no main-document response. Check redirects, network access, and proxy policy.');
}
if (!response.ok()) {
throw new Error(`Target returned HTTP ${response.status()}`);
}
await page.screenshot({ path: 'screenshot.png' });
console.log(`Saved screenshot.png (HTTP ${response.status()})`);
} finally {
await browser.close();
}Run it with the proxy values supplied by your administrator:
PROXY_SERVER='http://proxy.example.com:8080' \
PROXY_USERNAME='your-proxy-user' \
PROXY_PASSWORD='your-proxy-password' \
node capture.mjsFor a proxy that does not use authentication, omit the username and password variables. The example records the main document’s HTTP response and fails explicitly when navigation returns a non-success status. Some sites intentionally respond with a login, access-denied, or challenge page; inspect the captured page and your organization’s access policy when that happens.
Set the proxy on a browser context instead
If different contexts need different network routes, configure the proxy when creating each context. Playwright documents proxy settings at browser or context scope:
const browser = await chromium.launch();
const context = await browser.newContext({
proxy: {
server: 'http://proxy.example.com:8080',
username: process.env.PROXY_USERNAME,
password: process.env.PROXY_PASSWORD,
},
});
const page = await context.newPage();Use one scope consistently for a capture. A browser-level proxy is convenient when every page uses the same gateway; a context-level proxy is useful when a process creates separate sessions with different proxy settings. Check the API documentation for the Playwright version pinned in your project.
4. Choose what to capture
Playwright’s default screenshot is the visible viewport. Choose the scope that matches the task:
| Capture | Use it for | Example |
|---|---|---|
| Viewport | A quick visual check of the currently visible area. | await page.screenshot({ path: 'viewport.png' }); |
| Full page | A record of the entire scrollable document. | await page.screenshot({ path: 'full-page.png', fullPage: true }); |
| Element | Documentation or review focused on one component. | await page.locator('main article').screenshot({ path: 'article.png' }); |
For a full-page capture, lazy-loaded content may not be present until it enters the viewport. If content is missing, scroll through the page before taking the screenshot, or wait for the relevant elements to appear. For an element capture, use a selector that identifies a single visible element and wait for it before capturing:
const article = page.locator('main article');
await article.waitFor({ state: 'visible', timeout: 15_000 });
await article.screenshot({ path: 'article.png' });For more screenshot options and locator behavior, see Playwright’s screenshot guide.
5. Handle browser downloads and corporate certificates
Proxy configuration for the browser’s website traffic and configuration for downloading the browser binary are separate concerns. If installation fails because downloads cannot reach the Playwright host, the official browser guide documents these environment variables:
HTTPS_PROXYroutes browser downloads through a proxy.NODE_EXTRA_CA_CERTSpoints Node.js at a custom root CA when an organization’s intercepting proxy requires it.PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUTincreases the browser download connection timeout when the archive connection is slow.
Use only the certificate supplied or approved by your organization. These variables address browser installation; they do not replace the proxy settings needed for the browser to reach the target website. Consult the browser installation documentation for current instructions and version-specific details.
6. Managed Chrome and Edge considerations
Organizations can enforce enterprise policies in managed Google Chrome and Microsoft Edge. Playwright warns that such policies can affect its ability to launch and control these browsers and can limit browser capabilities or proxy settings. If a managed browser refuses automation or behaves differently from bundled Chromium, confirm your organization’s policy and approved browser channel with IT. Do not assume automation can override enterprise restrictions. See Playwright’s Chrome and Edge guidance.
7. Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| Browser downloads fail during installation | The download host is unreachable directly, the proxy is missing, or the proxy certificate is not trusted by Node.js. | Ask IT for the approved download route; set HTTPS_PROXY and, if instructed, NODE_EXTRA_CA_CERTS. Increase PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT for a slow archive connection. |
| Proxy authentication fails | Credentials are missing, incorrect, expired, or supplied in the wrong place. | Confirm the required authentication method and use the proxy’s username and password fields in Playwright’s proxy configuration. Keep target-site credentials separate. |
| Navigation times out | The proxy cannot reach the destination, a firewall or allowlist blocks it, DNS is unavailable from that route, or the page never reaches the selected load condition. | Confirm the endpoint and protocol with IT, check the allowlist and DNS route, and use a suitable navigation condition such as domcontentloaded. A longer timeout cannot fix a blocked route. |
| Certificate or TLS error | An intercepting proxy uses an organization certificate that the browser runtime does not trust. | Follow the organization’s certificate instructions for the browser/runtime in use. Do not disable TLS verification as a workaround. |
| The screenshot shows a denial or challenge page | The proxy, destination, or site policy denies the request, or the site requires an approved sign-in flow. | Inspect the response and visible page, then ask the network or site administrator about access. A screenshot does not bypass access controls. |
| Managed Chrome or Edge will not launch or is missing capabilities | Enterprise browser policy restricts automation or settings. | Check local policy with IT and use only an administrator-approved browser channel. |
| Image is blank or content is missing | The capture ran before rendering completed, content is lazy-loaded, or the selected element is hidden. | Wait for a meaningful selector, scroll to trigger lazy loading, and capture after the content is visible. |
8. Performance, reliability, and cost
- Wait for what you need. Waiting for the whole page to become network-idle can hang on pages with persistent connections. Prefer a meaningful readiness condition, such as a visible selector or
domcontentloaded, followed by a targeted wait. - Reuse a browser for multiple captures. When processing a batch, launch the browser once and create pages or contexts as needed. Close pages and contexts when finished to release resources.
- Keep proxy latency in mind. Each navigation and page resource goes through the configured route. Large pages and slow gateways can take longer; set a bounded timeout and log navigation status so failures can be distinguished from slow responses.
- Make failures observable. Record the destination, timestamp, response status, and error category. Avoid logging proxy passwords, authorization headers, or other secrets.
- Account for environment-specific costs. Playwright is software, but browser execution consumes the compute and network resources of the machine or CI runner where it runs. This research does not establish a universal runtime cost or speed; measure against your own pages, proxy, and runner.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. Its one-call API can return a screenshot without installing or configuring a local browser:
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webpSee the ScreenshotNeo API documentation for options and supported formats. Cookie banners, newsletter popups, and chat widgets are removed before the shot; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. An MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Every feature is on every plan. Create a free ScreenshotNeo account.
FAQ
Can I use a proxy URL that includes credentials?
Use the proxy format and authentication method documented for your organization and Playwright version. Playwright’s proxy configuration has separate username and password fields for HTTP proxy authentication; confirm locally supported formats rather than assuming every gateway accepts the same URL syntax.
Does a corporate proxy let Playwright access a restricted website?
No. The proxy routes network traffic according to organizational and destination policies. Ask the relevant administrator for access if the route or site is restricted.
Does the proxy setting affect only the screenshot request?
It configures the browser’s network route, so page navigation and browser resource requests use that configuration. Browser download settings are configured separately.
Which screenshot scope should I choose?
Use viewport capture for what is visible now, full-page capture for the scrollable document, and locator capture for one component.
