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.

Practice

1. What does cy.screenshot({ capture: 'fullPage' }) do in Cypress testing?

easy

A. Clears all previous screenshots

B. Takes a screenshot of the entire webpage, including parts not visible on screen

C. Records a video of the test run

D. Takes a screenshot only of the visible part of the webpage

Solution

1. Step 1: Understand the capture option in cy.screenshot()

   The capture option controls what part of the page is captured. Setting it to 'fullPage' means the entire page, not just the visible viewport.

2. Step 2: Compare with other options

   By default, cy.screenshot() captures only the visible part. 'fullPage' extends this to the whole page including scrollable areas.

3. Final Answer:

   Takes a screenshot of the entire webpage, including parts not visible on screen -> Option B

4. Quick Check:

   Full-page screenshot = entire webpage [OK]

Hint: Remember 'fullPage' means capture everything, not just visible [OK]

Common Mistakes:

• Thinking it captures only visible viewport
• Confusing screenshot with video recording
• Assuming it clears previous screenshots

2. Which of the following is the correct syntax to take a full-page screenshot in Cypress?

easy

A. cy.fullPageScreenshot()

B. cy.screenshot('fullPage')

C. cy.screenshot({ capture: 'fullPage' })

D. cy.screenshot.capture('fullPage')

Solution

1. Step 1: Recall the correct method signature

   The cy.screenshot() command accepts an options object where capture: 'fullPage' is the correct way to specify full-page capture.

2. Step 2: Eliminate incorrect syntax

   Passing 'fullPage' as a string argument directly, using non-existent commands like cy.fullPageScreenshot(), or trying to chain .capture('fullPage') are not valid Cypress syntax for full-page screenshots.

3. Final Answer:

   cy.screenshot({ capture: 'fullPage' }) -> Option C

4. Quick Check:

   Correct syntax uses options object with capture key [OK]

Hint: Use curly braces and capture key for full-page screenshots [OK]

Common Mistakes:

• Passing 'fullPage' as a string argument directly
• Using non-existent commands like cy.fullPageScreenshot()
• Trying to chain .capture() method

3. Consider this Cypress test code snippet:

cy.visit('https://example.com')
cy.screenshot({ capture: 'fullPage' })

What will happen if the page is still loading when the screenshot is taken?

medium

A. The screenshot will capture the fully loaded page anyway

B. The test will fail with an error

C. Cypress will wait automatically until the page loads before screenshot

D. The screenshot may capture an incomplete or partially loaded page

Solution

1. Step 1: Understand Cypress behavior on page load

   Cypress does not automatically wait for all page content to load unless explicitly told. If cy.screenshot() runs immediately after cy.visit(), the page might still be loading.

2. Step 2: Effect on screenshot

   If the page is not fully loaded, the screenshot will capture whatever is visible at that moment, possibly incomplete content.

3. Final Answer:

   The screenshot may capture an incomplete or partially loaded page -> Option D

4. Quick Check:

   Screenshot timing affects completeness [OK]

Hint: Always wait for page load before screenshot to avoid partial capture [OK]

Common Mistakes:

• Assuming Cypress waits automatically for full load
• Expecting error if page not loaded
• Thinking screenshot always captures full content

4. You wrote this Cypress test:

cy.visit('https://example.com')
cy.screenshot({ capture: 'fullpage' })

Why does the full-page screenshot not work as expected?

medium

A. The option value 'fullpage' is case-sensitive and should be 'fullPage'

B. You must call cy.fullPageScreenshot() instead

C. The cy.screenshot() command does not support options

D. You need to add wait() before screenshot

Solution

1. Step 1: Check the option value spelling and case

   The correct option value is 'fullPage' with capital P. 'fullpage' is invalid and ignored.

2. Step 2: Understand Cypress option sensitivity

   Cypress options are case-sensitive. Using wrong case causes fallback to default behavior (visible viewport only).

3. Final Answer:

   The option value 'fullpage' is case-sensitive and should be 'fullPage' -> Option A

4. Quick Check:

   Option values are case-sensitive in Cypress [OK]

Hint: Check option spelling and case carefully [OK]

Common Mistakes:

• Ignoring case sensitivity in option values
• Using non-existent commands
• Assuming wait fixes option errors

5. You want to capture a full-page screenshot only after a dynamic content section finishes loading. Which Cypress code snippet correctly waits for the content and then takes a full-page screenshot?

hard

A. cy.get('#dynamic-section').should('be.visible')
.then(() => cy.screenshot({ capture: 'fullPage' }))

B. cy.screenshot({ capture: 'fullPage' })
cy.get('#dynamic-section').should('be.visible')

C. cy.wait(5000)
cy.screenshot({ capture: 'fullPage' })

D. cy.get('#dynamic-section').click()
cy.screenshot({ capture: 'fullPage' })

Solution

1. Step 1: Wait for dynamic content visibility

   Using cy.get('#dynamic-section').should('be.visible') waits until the dynamic section is visible, ensuring content is loaded.

2. Step 2: Take full-page screenshot after wait

   Chaining .then(() => cy.screenshot({ capture: 'fullPage' })) ensures the screenshot runs only after the wait condition passes.

3. Final Answer:

   cy.get('#dynamic-section').should('be.visible') .then(() => cy.screenshot({ capture: 'fullPage' })) -> Option A

4. Quick Check:

   Wait for content visible, then screenshot [OK]

Hint: Wait for element visible before screenshot using should('be.visible') [OK]

Common Mistakes:

• Taking screenshot before waiting for content
• Using fixed wait times instead of element checks
• Clicking element unnecessarily before screenshot