To capture a protected page in Percy, first get your test into the required logged-in page state, then provide the network request headers Percy needs to fetch protected content during asset discovery. Percy documents two placements: headers on an individual Cypress snapshot or shared headers in .percy.yml.
How Percy authentication headers work
Percy’s changelog documents sending the headers required by a protected server. In its example, the request includes an Authorization header. The change entry is dated October 8, 2019, and says the capability requires @percy/agent v0.18.0 or newer; that is the historical minimum in the entry, not verified current compatibility guidance. Percy authentication changelog
As an Amazon Associate I earn from qualifying purchases.
There are two separate parts to this workflow: your browser test must reach the page state you want to capture, and Percy may need request headers to access protected resources while discovering assets. Supplying a header does not itself perform a login interaction or establish that every authentication scheme is supported.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteChoose where to configure the headers
| Placement | When it fits | Documented syntax |
|---|---|---|
| One snapshot call | Use when the required headers belong to a particular capture. | requestHeaders option in the Cypress snapshot call |
| Shared Percy configuration | Use when you want headers in the shared asset-discovery configuration. | agent.asset-discovery.request-headers in .percy.yml |
Percy’s changelog does not establish precedence if both placements are set, nor does it document secret-management practices or syntax across every Percy SDK. Avoid assuming either behavior; consult the current official documentation for your SDK and configuration.
#1 Best Overall
Configure headers on a Cypress snapshot
After your Cypress test has navigated to the intended page state, pass the required headers to the snapshot call. Percy’s documented example is:
cy.percySnapshot('Home page', {
requestHeaders: {
Authorization: 'Basic dXNlcm5hbWU6cGFzc3dvcmQ='
}
})The Basic authorization value above is illustrative documentation text, not a usable credential. Replace it with the header value your application requires, and do not commit real credentials into source control.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Configure headers globally in .percy.yml
For shared asset-discovery configuration, Percy shows this YAML structure:
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →version: 1
agent:
asset-discovery:
request-headers:
Authorization: 'Basic dXNlcm5hbWU6cGFzc3dvcmQ='Notice that the snapshot option is spelled requestHeaders, while the YAML key is request-headers. Use the spelling that matches the configuration location. As with the Cypress example, the sample authorization value is not a real secret.
Rank #3
Run the visual test and verify the result
- Arrange for the browser test to reach the authenticated page state you want Percy to capture.
- Add the required request headers to that snapshot call, or place them in the shared
.percy.ymlasset-discovery configuration. - Run the Percy-enabled test and inspect the resulting snapshot in Percy. Percy’s Cypress guide describes adding snapshots in Cypress tests and supplying the Percy project token through the environment so uploads are associated with a project. Percy Cypress visual testing guide
The Percy project token and application authentication headers serve different purposes: the token associates a test run’s upload with a Percy project; the request headers let protected content requests authenticate to the application.
Troubleshoot common failures
The snapshot shows a login page or an access-denied state
Check that the test actually reached the desired page state before the snapshot. Then confirm that the configured request header name and value match what the protected server requires. The changelog documents required network headers but does not promise support for every authentication scheme.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
Protected images or other assets are missing
Review the asset requests that require authentication and ensure the headers are configured in the snapshot call or global asset-discovery configuration. A page can render in the test browser while asset discovery still needs credentials for protected resources.
Percy configuration appears to have no effect
Check the option spelling and nesting against the chosen placement: requestHeaders for the Cypress call, or agent.asset-discovery.request-headers in YAML. The 2019 changelog says the feature requires @percy/agent v0.18.0 or newer and suggests checking the installed package with npm ls @percy/agent. Treat v0.18.0 as the historical minimum stated there; verify present-day requirements in current Percy documentation.
The test uploads to the wrong Percy project or does not associate an upload
Check the Percy project token configuration separately from application authentication. The Cypress guide discusses the project token as the mechanism for associating uploads, while the authentication changelog’s headers address protected content access.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
For a one-off page image or PDF rather than a Percy visual-test snapshot, ScreenshotNeo is an alternative to try first: it removes known cookie banners, newsletter popups and chat widgets before capture, and only clean shots are billed. Its API returns screenshots or PDFs from one GET request. Learn about ScreenshotNeo.
For example, with a ScreenshotNeo API key:
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 request options. ScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits cost nothing, with response headers indicating the page verdict and billing status. An MCP server provides take_screenshot, get_page_info and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. This is a separate screenshot service, not a way to upload snapshots into Percy.
Recommended Free Tools
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Frequently Asked Questions
Does Percy’s project token authenticate me to the protected application?
No. The Percy project token associates test uploads with a Percy project; application request headers are for accessing protected content.
Can I use these exact header examples with every Percy SDK?
The cited authentication changelog shows a Cypress example and a global YAML example; it does not establish identical syntax for every SDK. Check the current official documentation for your SDK.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →
