How to Test a Website Behind Login with Happo

To test a website behind login with Happo, authenticate in your existing Playwright test, navigate to the protected page, wait until the intended logged-in UI is ready, and then call Happo’s screenshot helper on the page or locator you want to compare. Happo documents capturing from a Playwright test; it does not document a separate Happo login API. Authentication is part of your app’s browser flow.

This approach fits a visual regression test that needs to reproduce a real authenticated route. The example below is a framework-neutral sketch: replace the URL, selectors, and login steps with those supported by your application. It has not been run against a particular app or identity provider.

1. Install and configure Happo

Use Happo’s Playwright integration, provide its API credentials through environment variables, and run the test suite with Happo’s wrapper. The current official integration guide is the source for setup details: Happo Playwright documentation.

npm install --save-dev happo

Add a configuration file such as happo.config.ts:

import { defineConfig } from 'happo';

export default defineConfig({
  apiKey: process.env.HAPPO_API_KEY,
  apiSecret: process.env.HAPPO_API_SECRET,
  integration: { type: 'playwright' },
  targets: {
    chrome: { type: 'chrome', viewport: '1024x768' },
  },
});

Store HAPPO_API_KEY and HAPPO_API_SECRET in your CI secret store or local environment. Do not commit them or print them in test logs. Put application test credentials in the same kind of secret store, under separate names.

2. Log in, assert the protected state, then capture it

Import test from happo/playwright. Log in using the application’s supported flow, confirm that the protected content is present, and capture a meaningful element. Asserting the page state before capture prevents a successful screenshot job from silently comparing a login form.

import { test } from 'happo/playwright';

test('authenticated dashboard', async ({ page, happoScreenshot }) => {
  const loginUrl = process.env.APP_LOGIN_URL;
  const email = process.env.TEST_USER_EMAIL;
  const password = process.env.TEST_USER_PASSWORD;

  if (!loginUrl || !email || !password) {
    throw new Error('Set APP_LOGIN_URL, TEST_USER_EMAIL, and TEST_USER_PASSWORD');
  }

  await page.goto(loginUrl);
  await page.getByLabel('Email').fill(email);
  await page.getByLabel('Password').fill(password);
  await page.getByRole('button', { name: /sign in/i }).click();

  const heading = page.getByRole('heading', { name: /dashboard/i });
  await heading.waitFor();
  await page.locator('main').waitFor();

  await happoScreenshot(page.locator('main'), {
    component: 'Dashboard',
    variant: 'authenticated',
    snapshotStrategy: 'clip',
  });
});

The labels, button name, and heading are examples, not universal selectors. Use locators that identify your app’s real controls. For multi-factor authentication, SSO, or an identity provider that requires special handling, use your team’s approved test setup and confirm the flow is supported in CI.

Choose what Happo captures

Capture a locator: useful for a dashboard panel or component whose appearance matters independently.
Use snapshotStrategy: 'clip' when context matters: Happo’s default hoist strategy renders the selected element in isolation. If the element depends on parent layout or inherited styling, clipping it in place can preserve that context.
Wait for meaning, not just navigation: wait for an application-ready element or state. A route change alone may happen before data, fonts, or images have settled.

3. Select browser and viewport coverage

Choose browser targets and viewport sizes based on your product’s support commitments and the visual risks of the page. Happo’s Playwright integration supports configured targets and dynamic targets for an individual screenshot; consult its current guide for the accepted target names and syntax. Avoid multiplying combinations without a reason: each extra browser or viewport adds comparison cases to inspect.

The example configuration uses one Chrome target at 1024x768. Adapt it to the browsers and dimensions your team actually supports. For a responsive dashboard, for example, cover the viewport widths where layout changes, rather than selecting arbitrary sizes.

4. Run the suite through Happo

Run Playwright through Happo’s command wrapper:

npx happo -- playwright test

Without the wrapper, Happo is disabled for the suite according to its integration guide. Happo records snapshot information during test execution and takes screenshots asynchronously outside the test run. This means the test’s successful completion and the finished visual report are separate steps.

For pull requests, Happo documents comparison against the main branch; main-branch builds create reports. To show results in GitHub, configure the Happo GitHub app as described in Happo’s documentation.

5. Understand authentication and data boundaries

The browser test establishes the session before it requests the snapshot. However, Happo’s reviewed Playwright documentation does not specify a universal handoff for every cookie, local-storage, session-storage, or SSO arrangement through asynchronous remote rendering. Do not assume a particular authentication mechanism will be preserved in every setup; verify with Happo when the mechanism or page sensitivity makes that important.

Happo’s security policy says screenshots and related repository or pull-request metadata are confidential and access controlled per account: Happo Security Policy. The policy cited here does not explicitly define how application session tokens are handled by this integration. Prefer a dedicated least-privilege test account and non-production data, and confirm the data path before capturing sensitive content.

External assets may need to be publicly accessible to Happo workers unless configured for downloading. If screenshots miss styles or images, check asset reachability and Happo’s asset configuration.

6. Common problems and fixes

Symptom	Likely cause	What to check
The screenshot shows the login page	The login did not complete, the route redirected, or the test captured too early.	Assert the protected heading or another authenticated-only element before calling `happoScreenshot`. Check the test account, redirect URL, and CI secrets.
No Happo screenshot or report appears	Credentials are missing, or the suite did not use the Happo wrapper.	Confirm both Happo API variables are set and run `npx happo -- playwright test`. Check console output prefixed with `[HAPPO]`.
The selected element looks unstyled	The default `hoist` strategy isolates the selected element from styles or layout supplied by its ancestors.	Try `snapshotStrategy: 'clip'` when the element needs its on-page context, or capture a larger container.
Images, fonts, or styles are missing	Assets are unavailable to the remote worker, or the screenshot was requested before they loaded.	Check external asset accessibility and download configuration. Wait for the app’s ready state and any required assets before capture.
Cookie or storage-based login behaves differently	The reviewed Happo guide does not define a general storage-state transfer guarantee.	Reproduce authentication in the documented browser-test flow and ask Happo about your exact cookie, storage, or SSO setup. Lighthouse’s authenticated-page guidance describes its own behavior, not Happo’s: default Lighthouse runs start without previous session or storage data (Google Lighthouse guide).
Visual results vary between runs	The page may contain changing data, animations, delayed requests, or content that has not reached a stable state.	Use stable test data, wait for the specific UI state that matters, and avoid capturing transient content. If the project’s existing setup offers a supported way to control animations or data, apply it consistently.

7. Playwright or Cypress?

Use whichever end-to-end runner your project already uses if its login flow can run reliably in CI. Happo documents both a Playwright integration and a Cypress integration. For Cypress, the corresponding integration is happo/cypress and the wrapper runs cypress run. Choose based on your existing auth automation, the browsers and viewports you need, and whether you need an isolated element or its surrounding page context. The reviewed sources establish no head-to-head cost or feature winner.

If the same authenticated states can be represented in a component catalog without logging into the live site, that may be another option, but it depends on how your application supplies authenticated data and is not prescribed by Happo’s cited integration material.

Or skip the browser setup

If you need a screenshot of a public page or a URL your capture setup can access, ScreenshotNeo returns an image or PDF from one request. For pages behind login, do not send credentials or assume the API can inherit your Playwright session; use an access arrangement supported by your application and ScreenshotNeo.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation for request options. Its clean-shot flow removes cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. ScreenshotNeo also provides an MCP server so AI agents can take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.

FAQ

The cited Playwright integration documents requesting screenshots from a Playwright test, not a separate Happo login API. Perform authentication in your test flow.

Can I use a pre-authenticated Playwright storage state?

The reviewed Happo material does not establish a universal storage-state handoff for remote screenshot rendering. Check the exact setup with Happo before relying on it, especially for SSO or sensitive pages.

Why does the visual report arrive after the tests?

Happo processes screenshots asynchronously outside the test run. The test records snapshot information; screenshot processing and reporting happen separately.

Can I capture a whole page or just one component?

The workflow supports capturing a page or locator. Pick the target and snapshot strategy that represent the UI behavior you want to protect.