How to Take Full-Page Screenshots with Percy

For a full-page screenshot in Percy with Automate, wait until the page is ready, then call Percy’s screenshot function with fullPage: true in the options. If content loads only after scrolling, scroll through the page before capturing. Percy Web differs: its projects take full-page screenshots by default. Native App Percy uses a separate scroll-and-stitch setup with its own limits.

1. Identify which Percy workflow you use

Percy has distinct workflows for browser automation, Percy Web, and native apps. The option and defaults are not interchangeable.

Workflow	Full-page behavior	Use this guidance
Percy with Automate	A viewport or single tile is the default in the documented Playwright integration. Set the full-page option explicitly.	Use the browser automation examples below.
Percy Web	Full-page screenshots are the default for projects created on Percy Web.	Do not add Automate-specific setup unless your integration requires it.
App Percy	Captures native app screens by scrolling and stitching; setup uses fullPage and can set screenLengths.	See the App Percy section; these settings do not apply to a web page in a browser.

BrowserStack’s documentation states that full-page screenshots are the default for Percy Web projects. That statement applies to Percy Web, not Automate. BrowserStack Docs: Full-page screenshot and the Automate Playwright integration describe the distinction.

2. Capture a full page with Percy Automate

The core sequence is: load the page, make the rendered state stable, and take a uniquely named Percy snapshot with the full-page option enabled. Exact setup for the browser driver and Percy SDK depends on your project; the following shows the documented screenshot call for JavaScript and Python.

JavaScript

const options = { fullPage: true };
await percyScreenshot(driver, 'Product page — full page', options);

Call this after your test has navigated to the target page and waited for the state you intend to compare. Ensure percyScreenshot is the screenshot function provided by your Percy Automate integration.

Python

options = {'fullPage': True}
percy_screenshot(driver, 'Product page — full page', options)

The option spelling differs by language conventions: the documented JavaScript and Python examples use fullPage, with a lowercase true in JavaScript and capitalized True in Python. Other SDKs may represent options differently; use the example for the integration in your project.

Java and C#

BrowserStack’s guide also provides Java and C# Automate examples. In both, add the full-page setting to the options collection passed to the Percy screenshot call. Use the types and call signatures from your installed SDK’s example rather than translating JavaScript syntax literally. See the official full-page guide.

Page readiness and lazy-loaded content

1. Navigate to the page and wait for the specific content your test needs, such as a heading or results container.
2. If images or sections load as they approach the viewport, scroll down through the page so the site’s normal lazy-load behavior runs. Percy attempts to handle lazy loading, but BrowserStack recommends scrolling to the bottom first if content is missing.
3. Pause or neutralize animations, video, and carousels where they can change between runs.
4. Handle consent dialogs, modals, and other popups in the test before taking the snapshot.
5. Call the Percy screenshot function with fullPage: true and a stable, descriptive snapshot name.

Prefer waiting for meaningful page conditions over adding an arbitrary long sleep. A fixed delay can be too short on a slow run and unnecessarily long on a fast one.

3. Check capture limits and scope

For the documented Percy with Automate full-page feature, BrowserStack lists a maximum desktop capture length of 10,000 pixels or 10 tiles, whichever is lower, and a limit of 10 tiles on mobile. Confirm the current limit for your project type and integration before relying on very long pages. The guide also says custom ignore regions and custom consider regions do not function with full-page screenshots.

If you need to validate just one section, an element-scoped snapshot may be a better fit than the whole document. Percy’s snapshot workflows also include CLI captures of files, directories, and sitemap URLs; those are separate from the Automate browser screenshot call. See Percy snapshot documentation.

4. Fix clipped or incomplete full-page captures

Capture stops at a container

Check the page CSS for a parent element that clips its contents with overflow: hidden or another overflow rule. BrowserStack documents targeted Percy CSS as a remedy; for example, if inspection identifies .container as the clipping element:

.container {
  overflow: unset !important;
}

Apply a targeted override to the specific clipping element and verify that it does not change the layout under test. Avoid a broad site-wide override: overflow rules can be intentional for menus, carousels, and other components. See BrowserStack’s clipping troubleshooting guide.

Lazy-loaded images or sections are absent

Trigger the page’s regular scroll behavior before capture, then wait for the expected content or image to appear. If the site loads content only after a particular interaction, reproduce that interaction in the test. A full-page option cannot show content the page has not rendered.

Snapshots vary between runs

Pause animations, video, and carousels or place them in a predictable test state. Dismiss or accept popups consistently. Wait for the page state that matters rather than capturing during ongoing updates.

Ignore or consider regions have no effect

BrowserStack documents that custom ignore and consider regions do not work with the full-page screenshot feature. For a comparison that depends on those regions, check the integration’s current supported options and consider whether a scoped capture is appropriate.

5. Native app screenshots with App Percy

App Percy is for native app screens, not browser pages. Its guide describes a scroll-and-stitch capture controlled with fullPage, optionally including screenLengths. The documented default is four screen lengths; values above 10 are reset to 10. The feature is described as beta, supported on BrowserStack devices, and does not restore the original scroll position after capture.

The cited guide specifies Appium server versions greater than 1.19 for Android and iOS 15 or newer for iOS. It also describes a limitation in detecting scroll progress when a single large text element reports the same visible-viewport position after scrolling; in that case the screenshot may fail. Splitting the content across multiple elements may help when feasible. Check the current App Percy full-page guide for the setup and support details that match your device and SDK.

6. Performance, reliability, and cost considerations

Full-page captures render and compare more page content than viewport captures. Very long pages can take longer to prepare and are subject to the documented Automate capture limits. Lazy loading, animation, network-dependent content, and popups can all change what is present at capture time, so stable readiness conditions usually help make snapshots repeatable.

Keep the snapshot name stable for the same page and test state, and make it distinct when the state or scenario changes. Before adopting full-page capture across a large test suite, account for the extra page content and the limits of your Percy project and plan. Pricing and billing depend on your BrowserStack account and are not specified in the cited full-page documentation; check your account’s current plan terms rather than assuming a per-screenshot rate.

7. Or skip the browser setup

If you need a screenshot file rather than a Percy visual-testing snapshot, ScreenshotNeo is a website screenshot API and MCP server. One GET request captures a URL as PNG, JPEG, WebP, or PDF. This example saves a screenshot response:

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 authentication and capture options. ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, with the result identified in response headers. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. For stable visual regression comparisons, Percy remains the workflow described above; ScreenshotNeo provides a direct screenshot capture.

Sign up for 1,000 free screenshots a month, with no card required.

FAQ

Does Percy always capture the full page?

No. Percy Web takes full-page screenshots by default, while Percy Automate requires the full-page option in the screenshot call. Native App Percy has a separate setup.

Why is the bottom of my page missing?

Common causes are lazy-loaded content that never entered the viewport, a CSS overflow rule clipping a container, or the capture reaching its documented length limit. Scroll to trigger lazy loading, inspect the clipping element, and confirm the relevant integration’s limits.

Can I use full-page capture with custom ignore regions?

The cited Automate full-page guide says custom ignore and consider regions do not function with full-page screenshots.

Does App Percy return the app to its original scroll position?

No. The cited App Percy guide says the scroll-and-stitch capture does not restore the starting scroll position.