Full-page screenshots in Cypress - Deep Dive

Overview - Full-page screenshots

What is it?

Full-page screenshots capture the entire visible and scrollable area of a web page during automated tests. Unlike regular screenshots that only capture the visible viewport, full-page screenshots include content beyond what is immediately visible on the screen. This helps testers see the full layout and content of a page in one image.

Why it matters

Without full-page screenshots, testers might miss visual bugs hidden outside the visible screen area, such as layout breaks or missing elements below the fold. This can lead to undetected issues in user experience. Full-page screenshots provide a complete visual record, making debugging and reporting easier and more reliable.

Where it fits

Before learning full-page screenshots, you should understand basic Cypress commands and how to take simple screenshots. After mastering full-page screenshots, you can explore visual testing tools and advanced screenshot comparison techniques.

Mental Model

Core Idea

A full-page screenshot stitches together all parts of a web page, including areas you must scroll to see, into one complete image.

Think of it like...

Taking a full-page screenshot is like taking a panoramic photo of a tall building by moving your camera up and down and then combining all the pictures into one wide view.

┌─────────────────────────────┐
│        Viewport area         │
│  ┌───────────────────────┐  │
│  │ Visible screen content │  │
│  └───────────────────────┘  │
│                             │
│  ┌───────────────────────┐  │
│  │  Off-screen content    │  │
│  │  (requires scrolling)  │  │
│  └───────────────────────┘  │
└─────────────────────────────┘

Full-page screenshot = stitching viewport + off-screen content into one image

Build-Up - 6 Steps

1

Foundation

Basic screenshot command in Cypress

Concept: Learn how to take a simple screenshot of the visible viewport using Cypress.

In Cypress, you can take a screenshot of the current visible area by using cy.screenshot(). For example: cy.visit('https://example.com') cy.screenshot('homepage') This saves an image of what you see on the screen at that moment.

Result

A screenshot image file named 'homepage.png' is saved, showing only the visible part of the page.

Understanding how to capture the visible viewport is the first step before capturing the entire page.

2

Foundation

Understanding viewport vs full page

Concept: Distinguish between the visible viewport and the full scrollable page content.

The viewport is the part of the web page visible on your screen without scrolling. The full page includes everything, even content you must scroll to see. Regular screenshots capture only the viewport, missing content below or above.

Result

You realize that regular screenshots can miss important page areas, which might hide bugs.

Knowing the difference helps you understand why full-page screenshots are necessary for complete visual testing.

3

Intermediate

Using Cypress fullPage option for screenshots

🤔Before reading on: do you think Cypress takes full-page screenshots by default or do you need to enable a special option? Commit to your answer.

Concept: Cypress supports full-page screenshots by enabling the 'fullPage' option in the screenshot command.

To capture the entire page, use cy.screenshot() with the option { fullPage: true }: cy.visit('https://example.com') cy.screenshot('fullpage-homepage', { fullPage: true }) This tells Cypress to scroll through the page and stitch all parts into one image.

Result

A screenshot image named 'fullpage-homepage.png' is saved, showing the entire scrollable page content.

Knowing the 'fullPage' option unlocks the ability to capture complete page visuals, essential for thorough UI testing.

4

Intermediate

Handling dynamic content in full-page screenshots

🤔Before reading on: do you think dynamic content like animations or lazy-loaded images affect full-page screenshots? Commit to yes or no.

Concept: Dynamic content can cause inconsistencies in full-page screenshots if not handled properly during capture.

Pages with animations, lazy loading, or content that changes on scroll may cause parts of the screenshot to be missing or look different. To handle this, you can: - Wait for animations to finish using cy.wait() - Scroll manually to trigger lazy loading - Disable animations with CSS before screenshot Example: cy.visit('https://example.com') cy.wait(1000) // wait for animations cy.screenshot('fullpage-clean', { fullPage: true })

Result

A stable full-page screenshot that accurately represents the page without flickers or missing content.

Understanding how dynamic content affects screenshots helps you produce reliable visual tests.

5

Advanced

Customizing full-page screenshot behavior

🤔Before reading on: do you think you can customize how Cypress scrolls or stitches full-page screenshots? Commit to yes or no.

Concept: Cypress allows some customization of full-page screenshots, including disabling animations or adjusting viewport size before capture.

You can customize the viewport size with cy.viewport() to control how the page is rendered before screenshot. Also, you can inject CSS to hide elements or disable animations: cy.viewport(1280, 800) cy.visit('https://example.com') cy.document().then(doc => { const style = doc.createElement('style') style.innerHTML = '* { transition: none !important; animation: none !important; }' doc.head.appendChild(style) }) cy.screenshot('fullpage-custom', { fullPage: true })

Result

A full-page screenshot with controlled page rendering, reducing visual noise and improving consistency.

Customizing page state before capture improves screenshot quality and test reliability.

6

Expert

Limitations and alternatives to Cypress full-page screenshots

🤔Before reading on: do you think Cypress full-page screenshots always work perfectly on all web pages? Commit to yes or no.

Concept: Cypress full-page screenshots have limitations on very complex pages or those with fixed headers/footers; alternatives exist for advanced visual testing.

Cypress stitches screenshots by scrolling and capturing viewport slices. Pages with fixed position elements or complex scroll behaviors can cause artifacts or repeated elements in the screenshot. For these cases, consider: - Using dedicated visual testing tools like Percy or Applitools - Taking multiple partial screenshots and stitching externally - Using browser-specific APIs or plugins Example limitation: fixed header appears multiple times in stitched image.

Result

Awareness of when Cypress full-page screenshots may fail and knowing alternative tools to ensure visual test accuracy.

Knowing the limits of built-in tools prevents false confidence and guides you to better visual testing strategies.

Under the Hood

Cypress takes full-page screenshots by programmatically scrolling the page in increments equal to the viewport height. At each scroll position, it captures a viewport-sized screenshot. Then, it stitches these images vertically into one long image representing the entire page. This process handles pages taller than the viewport by combining multiple images into a seamless full-page screenshot.

Why designed this way?

Browsers do not provide a native API to capture the entire page in one shot. Scrolling and stitching is a practical workaround that works across browsers. This design balances compatibility and simplicity, avoiding complex browser-specific code. Alternatives like browser extensions or external tools exist but add complexity.

┌───────────────┐
│ Initial viewport│
│ screenshot     │
├───────────────┤
│ Scroll down    │
├───────────────┤
│ Next viewport │
│ screenshot     │
├───────────────┤
│ Repeat until   │
│ bottom reached │
├───────────────┤
│ Stitch images  │
│ vertically     │
└───────────────┘

Result: One full-page screenshot image

Myth Busters - 4 Common Misconceptions

Quick: Does cy.screenshot() capture the full page by default? Commit yes or no.

Common Belief: Many believe that cy.screenshot() automatically captures the entire page without extra options.

Reality: By default, cy.screenshot() only captures the visible viewport. You must specify { fullPage: true } to capture the entire page.

Why it matters: Assuming default full-page capture leads to missed bugs in off-screen content and incomplete test evidence.

Quick: Do full-page screenshots always perfectly capture pages with fixed headers? Commit yes or no.

Common Belief: Some think full-page screenshots handle fixed headers and footers without issues.

Reality: Fixed position elements can appear multiple times in stitched screenshots, causing visual artifacts.

Why it matters: Ignoring this causes misleading screenshots, wasting debugging time and causing false positives.

Quick: Can you rely on full-page screenshots to capture dynamic animations accurately? Commit yes or no.

Common Belief: People often believe full-page screenshots capture dynamic animations exactly as seen live.

Reality: Animations can cause flickering or inconsistent captures unless paused or disabled before screenshot.

Why it matters: Failing to handle animations leads to flaky tests and unreliable visual comparisons.

Quick: Is full-page screenshot stitching done by the browser natively? Commit yes or no.

Common Belief: Some assume browsers provide native full-page screenshot APIs.

Reality: Browsers lack native full-page screenshot APIs; Cypress simulates this by scrolling and stitching multiple images.

Why it matters: Understanding this explains why some pages cause stitching artifacts and why alternatives might be needed.

Expert Zone

1

Full-page screenshots can be affected by browser zoom level and device pixel ratio, subtly changing image quality and size.

2

Stitching artifacts often arise from CSS transforms or fixed elements; experts use CSS overrides to mitigate these before capture.

3

Timing is critical: capturing too early or during page load can produce incomplete screenshots; experts synchronize with page events carefully.

When NOT to use

Avoid relying solely on Cypress full-page screenshots for pages with complex fixed headers, heavy animations, or infinite scrolling. Instead, use specialized visual testing platforms like Applitools or Percy that handle these cases with AI-powered comparison and better rendering control.

Production Patterns

In real projects, teams combine Cypress full-page screenshots with visual diff tools to catch UI regressions. They customize viewport sizes and disable animations before capture. For flaky pages, they fallback to partial screenshots or external visual testing services integrated into CI pipelines.

Connections

Visual Regression Testing

Builds-on

Full-page screenshots provide the complete visual baseline images needed for automated visual regression testing to detect UI changes.

Browser Rendering Engine

Underlying mechanism

Understanding how browsers render and paint pages helps explain why scrolling and stitching is necessary for full-page screenshots.

Panoramic Photography

Similar pattern

Both full-page screenshots and panoramic photos combine multiple partial images into one seamless whole, illustrating a shared technique across domains.

Common Pitfalls

#1 Capturing full-page screenshots without disabling animations causes flickering images.

Wrong approach:

cy.visit('https://example.com')
cy.screenshot('fullpage-animated', { fullPage: true })

Correct approach:

cy.visit('https://example.com')
cy.document().then(doc => {
const style = doc.createElement('style')
style.innerHTML = '* { animation: none !important; transition: none !important; }'
doc.head.appendChild(style)
})
cy.screenshot('fullpage-static', { fullPage: true })

Root cause:

Animations change page content during scrolling, causing inconsistent stitched images.

#2 Assuming cy.screenshot() captures full page by default leads to incomplete screenshots.

Wrong approach:

cy.visit('https://example.com')
cy.screenshot('homepage')

Correct approach:

cy.visit('https://example.com')
cy.screenshot('homepage-full', { fullPage: true })

Root cause:

Default screenshot captures only visible viewport, missing content outside screen.

#3 Not handling fixed headers causes repeated header images in full-page screenshots.

Wrong approach:

cy.visit('https://example.com')
cy.screenshot('fullpage-with-fixed-header', { fullPage: true })

Correct approach:

cy.visit('https://example.com')
cy.document().then(doc => {
const style = doc.createElement('style')
style.innerHTML = 'header, .fixed-header { position: static !important; }'
doc.head.appendChild(style)
})
cy.screenshot('fullpage-no-fixed-header', { fullPage: true })

Root cause:

Fixed position elements appear in every viewport screenshot, causing duplication in stitched image.

Key Takeaways

Full-page screenshots capture the entire scrollable content of a web page, not just what is visible on screen.

In Cypress, you must enable the { fullPage: true } option to take full-page screenshots.

Dynamic content like animations and fixed headers can cause artifacts; disabling or adjusting them improves screenshot quality.

Cypress stitches multiple viewport screenshots by scrolling the page, as browsers lack native full-page screenshot APIs.

For complex pages, specialized visual testing tools may be better suited than Cypress full-page screenshots alone.