Capturing assets protected with authentication

👍

Covered in this doc

• How to pass username/password auth to @percy/cli
• How to pass request headers to Percy

📘

You are viewing docs for the new @percy/cli. Most SDKs have been updated to utilize the new CLI, so check the appropriate SDK doc for instructions for your specific SDK!

If the app or website you're taking snapshots of is protected with authentication, you can configure Percy to pass the needed authentication headers. Without passing authentication to Percy, snapshots can be broken (since we won't be able to save the needed assets to render the page).

This can done as a per-snapshot option or added to your global Percy SDK config.

Basic auth username and password

You can pass your username/password as a snapshot option (or config option). This is much easier if your app only uses basic auth (and you don't need more advanced request headers).

As a snapshot option (in our Cypress SDK):

cy.percySnapshot('Home page', {
  authorization: {
    username: 'example-username',
    password: 'example-password'
  }
});

As a SDK config option:

version: 2
snapshot:
  authorization:
    username: example-username
    password: example-password

Request headers

You can pass any request headers as a snapshot option. For example, (in our Cypress SDK) using basic auth:

cy.percySnapshot('Home page', {
  requestHeaders: {
    Authorization: 'Basic dXNlcm5hbWU6cGFzc3dvcmQ='
  }
});

Or, as a SDK config option (as a .percy.yml file):

version: 2
snapshot:
  request-headers:
    Authorization: 'Basic dXNlcm5hbWU6cGFzc3dvcmQ='

version: 1
agent:
  asset-discovery:
    request-headers:
      Authorization: 'Basic dXNlcm5hbWU6cGFzc3dvcmQ='

You can pass any kind of header your website or application requires to properly authenticate.