Use your existing Playwright test to open the Next.js route, wait until the JavaScript-rendered state you want to check is visible, and then call Percy’s Playwright snapshot function. The key distinction: the test browser runs your app’s JavaScript before Percy captures its current DOM; Percy then renders that captured snapshot separately, with JavaScript disabled by default. You do not need a special Percy mode for Next.js.
How Percy handles JavaScript-rendered pages
There are two browser stages, and JavaScript behavior differs between them. First, Playwright visits the running app. Next.js and client-side scripts execute there, so Percy can capture the DOM after the page reaches the state your test intends to verify. Percy then renders the serialized snapshot in its own environment for visual comparison. That separate renderer has JavaScript disabled by default. BrowserStack Docs describes this capture and rendering workflow in its Percy SDK and screenshot capture workflow.
For a page whose content appears after hydration or a client-side request, wait in the Playwright test for that content before taking the snapshot. Turning on JavaScript in Percy’s renderer is a separate configuration choice; it is not required merely because the app used JavaScript to produce the captured DOM.
Set up the Playwright snapshot
This example assumes the project already has a working Next.js app and Playwright test setup. Use the project’s existing test command and app startup arrangement. Install the Percy Playwright SDK in the project:
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 →#1 Best Overall
npm install --save-dev @percy/playwrightAdd a visual test alongside your existing Playwright tests. Replace the route, expected content, and test import path to match the project. The assertion is an example of an app-specific readiness check; it ensures the intended state has appeared before Percy captures it.
import { test, expect } from '@playwright/test';
import percySnapshot from '@percy/playwright';
test('account page visual snapshot', async ({ page }) => {
await page.goto('http://localhost:3000/account');
// Wait for the client-rendered state that this snapshot is meant to cover.
await expect(page.getByRole('heading', { name: 'Your account' })).toBeVisible();
await percySnapshot(page, 'Account page - signed-out - desktop');
});Choose a snapshot name that identifies the route and meaningful state. If the page has different logged-in, empty, error, or populated states, capture them as separate snapshots after arranging each state in the test. Avoid names that change on every run, such as timestamps, because they make builds harder to compare.
Configure the Percy project token
Create or select a Percy project using the Percy Web workflow or Percy with Automate, then provide that project’s token to the test process as an environment variable. Keep the token out of source control. The exact method for setting environment variables depends on the shell and CI provider; Percy’s Playwright guide covers the project token and integration workflow: Integrate Percy with Playwright and Javascript.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Run the visual test through Percy
Wrap the project’s existing test command with npx percy exec --. For example, if the Playwright script is named test:e2e in package.json:
npx percy exec -- npm run test:e2eThe app must be available to the browser when the test navigates to it. Start it using the project’s current local or CI setup, or use the project’s existing Playwright web-server configuration. Percy’s documented example likewise navigates with Playwright, calls percySnapshot, and runs the test command through percy exec.
Choose a readiness condition that matches the page
A successful navigation does not prove that a client-rendered page is ready for visual capture. Pick a condition tied to the exact state under test, such as a visible heading, a loaded result count, or the disappearance of a loading indicator. If content depends on a specific request, the test can also wait for the relevant response and then assert the resulting UI.
Rank #3
- Prefer a locator assertion such as
toBeVisible()ortoHaveText()over an arbitrary fixed delay when the target state can be identified. - Use a delay only when the page behavior genuinely requires a settling period that cannot be represented by an observable condition.
- Do not assume
networkidleis universally appropriate. Pages with polling, streaming, analytics, or other continuing requests may never become idle, while an idle network does not necessarily mean hydration or the relevant UI update has finished. - For animations or changing data, make the test state repeatable and stable before capture. Dynamic content and motion can create visual differences unrelated to a code change.
Decide what Percy should render and compare
Keep Percy renderer JavaScript off unless the snapshot needs it
For ordinary client-rendered Next.js content, the test browser has already executed the JavaScript before serialization. Percy’s renderer can therefore display the captured DOM without re-running the app’s scripts. BrowserStack documents enable-javascript as disabled by default; enabling JavaScript in the rendering stage may introduce side effects such as redirects or animation, or interfere with serialized state. See Percy configuration options. Enable it only when the page’s rendering requirements call for it, and validate the result against the captured state.
Make assets available to the separate renderer
The Percy rendering environment is separate from the Playwright session. If images, fonts, stylesheets, or other assets require authentication, the renderer may not be able to fetch them using the test browser’s existing session automatically. Percy’s SDK documentation describes discovery configuration options for request headers, authorization, and cookies. Configure only the access the snapshot needs, and avoid exposing credentials in test output or source control.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Select responsive widths intentionally
Percy can render snapshots at selected responsive widths. Each requested width counts as a separate screenshot toward monthly usage, so choose widths that represent layouts the team actually needs to protect, such as a narrow mobile layout and a desktop layout, rather than every possible width. The exact width selection and accounting are described in Responsive Visual Testing.
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
Choose browser coverage based on risk
Percy’s Playwright integration offers Percy Web and Percy with Automate paths. Where the browser runs and how browser selection is controlled differ by workflow; consult the integration guide for the project path you choose. A single browser can be sufficient when the goal is to protect one agreed rendering environment. Cross-browser coverage is more useful when browser-specific layout behavior is a requirement. Do not add browsers or widths without a concrete coverage need, since each captured configuration expands the snapshots to review.
Review snapshots and baselines
After a run, inspect the captured snapshots and compare visual differences in Percy. Approve a change only after deciding it is an intended design update; otherwise fix the underlying change and run the test again. The Playwright integration guide says the previous build is the default comparison baseline and that base-build selection is configurable. Make sure a branch or CI run is comparing against the appropriate approved build rather than treating an unrelated build as the expected appearance.
Troubleshoot common problems
| Symptom | Likely cause | What to check or change |
|---|---|---|
| The snapshot is missing content that appears later in the browser | The snapshot call ran before hydration, async data, or a client-side state update completed. | Wait for a locator or assertion tied to the target content, then call percySnapshot. |
| The page works in Playwright but styles or assets are missing in Percy | The separate renderer cannot access a protected asset with the test browser’s session credentials. | Review Percy’s asset discovery configuration and provide required headers, authorization, or cookies through the documented configuration options. |
| The page behaves differently when renderer JavaScript is enabled | Percy is re-running JavaScript after capturing the DOM; scripts may redirect, animate, or change serialized state. | Leave renderer JavaScript disabled unless necessary. If it is required, test the setting against the specific page and state. |
| Snapshots differ on every run | Changing data, timestamps, animation, or other dynamic UI is entering the captured state. | Use controlled test data and stabilize motion or changing content before capture; configure supported Percy options where appropriate. |
| The test hangs waiting for the page to be idle | Ongoing requests prevent a network-idle condition from being reached. | Wait for the specific user-visible result instead of using network idle as a blanket readiness signal. |
| Unexpected screenshots or noisy diffs appear across widths | The selected responsive widths do not correspond to the layouts the team intends to check. | Reduce or revise the width set to cover the target breakpoints and layouts. |
| A build is compared with an unexpected appearance | The selected or default base build is not the approved baseline intended for this run. | Check the build relationship and configure base-build selection as needed. |
Or skip the browser setup
If your goal is to capture a URL rather than maintain a Percy visual-test workflow, ScreenshotNeo offers a one-request screenshot API. It can remove cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. It also provides an MCP server for AI agents. See ScreenshotNeo and its API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpFree includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Does Percy need JavaScript enabled to capture a Next.js page rendered in the browser?
No. Playwright runs the page JavaScript before Percy captures the DOM; enabling JavaScript in Percy’s separate renderer is a different setting.
Is there a special Percy integration mode for Next.js?
The documented setup is the general Percy Playwright integration; use it with the project’s existing Next.js and Playwright configuration.
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.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problems
