Cypress - screenshot() Method

Last Updated : 24 Oct, 2024

The screenshot() method in Cypress is used to capture a screenshot of the current state of our web page during test execution. It is useful for debugging visual issues, creating visual snapshots for comparisons, or simply documenting the state of our web application at any point during a test.

Usage of screenshot() Method

We can use the screenshot() method to:

  • Capture screenshots of the entire page or specific elements.
  • Document the UI during tests for reporting or debugging.
  • Take snapshots before or after specific interactions.

Syntax:

cy.screenshot(name, options)

Arguments:

  • name (optional): A string to name the screenshot. If not provided, Cypress will generate a name based on the test file name and the state of the test.
  • options (optional): An object that allows us to customize the screenshot, with options such as:
    • capture: Choose what to capture (fullPage, viewport, or runner).
    • clip: An object that defines a specific region to capture with coordinates (x, y, width, height).
    • scale: Whether to scale the image.
    • disableTimersAndAnimations: Disable CSS animations and timers to capture a static view.
    • blackout: An array of CSS selectors to hide specific elements in the screenshot.

Example 1: Capture a Full Page Screenshot

In this example, we will capture a full-page screenshot after loading a web page.

  • HTML File (index.html)
    Save this file in the root directory of our local server (e.g., localhost:3000).
HTML 
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Screenshot Example</title>
</head>
<body>
    <h1>Welcome to the Screenshot Example Page</h1>
    <p>This page demonstrates how to take screenshots in Cypress.</p>
    <button id="showMore">Show More</button>
    <div id="moreContent" style="display:none;">
        <p>This is additional content revealed after clicking the button.</p>
    </div>
    <script>
        document.getElementById('showMore').addEventListener('click', function() {
            document.getElementById('moreContent').style.display = 'block';
        });
    </script>
</body>
</html>
  • Cypress Test File (screenshot_full_spec.js)
    Save this file in the cypress/e2e folder (for Cypress v10 and above) or cypress/integration folder (for older versions).
JavaScript 
describe('Full Page Screenshot Example', () => {

  beforeEach(() => {
    // Visit the HTML file hosted on localhost
    cy.visit('http://localhost:3000');
  });

  it('should capture a full page screenshot', () => {
    // Capture a full-page screenshot
    cy.screenshot('full-page-screenshot', { capture: 'fullPage' });
  });

});

Explanation of the Test:

  • HTML Structure: The page contains a header, a paragraph, and a button that reveals more content when clicked.
  • Cypress Test:
    • The test visits the page and captures a full-page screenshot named full-page-screenshot.

Output:

imresizer-1728751494474
Browser running
first
Screenshot

A full-page screenshot is captured and saved in the cypress/screenshots folder under the name full-page-screenshot.png.

Example 2: Capturing a Screenshot of a Specific Element

In this example, we will capture a screenshot of a specific element on the page, such as the button or the revealed content.

  • HTML File (index.html)
    Save this file in the root directory of our local server (e.g., localhost:3000).
HTML 
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Screenshot Example</title>
</head>
<body>
    <h1>Welcome to the Screenshot Example Page</h1>
    <p>This page demonstrates how to take screenshots in Cypress.</p>
    <button id="showMore">Show More</button>
    <div id="moreContent" style="display:none;">
        <p>This is additional content revealed after clicking the button.</p>
    </div>
    <script>
        document.getElementById('showMore').addEventListener('click', function() {
            document.getElementById('moreContent').style.display = 'block';
        });
    </script>
</body>
</html>
  • Cypress Test File (screenshot_element_spec.js)
    Save this file in the cypress/e2e folder (for Cypress v10 and above) or cypress/integration folder (for older versions).
JavaScript 
 describe('Element Screenshot Example', () => {

  beforeEach(() => {
    // Visit the HTML file hosted on localhost
    cy.visit('http://localhost:3000');
  });

  it('should capture a screenshot of a specific element', () => {
    // Click the button to reveal more content
    cy.get('#showMore').click();

    // Capture a screenshot of the revealed content
    cy.get('#moreContent').screenshot('element-screenshot');
  });

});

Explanation of the Test:

  • Cypress Test:
    • The test clicks the button to reveal additional content.
    • A screenshot is then captured for the specific #moreContent element and saved as element-screenshot.png.

Output:

screenshot2
Browser running
second
Screenshot

The screenshot of the revealed content is captured and saved under the name element-screenshot.png in the cypress/screenshots folder.

Example 3: Using Screenshot Options (Blackout, Clip, and Scale)

In this example, we will use advanced screenshot options to blackout sensitive content and capture a specific region of the page.

  • HTML File (index.html)
    Save this file in the root directory of our local server (e.g., localhost:3000).
HTML 
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Screenshot Example</title>
</head>
<body>
    <h1>Welcome to the Screenshot Example Page</h1>
    <p>This page demonstrates how to take screenshots in Cypress.</p>
    <button id="showMore">Show More</button>
    <div id="moreContent" style="display:none;">
        <p>This is additional content revealed after clicking the button.</p>
    </div>
    <script>
        document.getElementById('showMore').addEventListener('click', function() {
            document.getElementById('moreContent').style.display = 'block';
        });
    </script>
</body>
</html>
  • Cypress Test File (screenshot_options_spec.js)
    Save this file in the cypress/e2e folder (for Cypress v10 and above) or cypress/integration folder (for older versions).
JavaScript 
describe('Screenshot with Options Example', () => {

  beforeEach(() => {
    // Visit the HTML file hosted on localhost
    cy.visit('http://localhost:3000');
  });

  it('should capture a screenshot with blackout and clipping', () => {
    // Blackout the button, so it doesn’t appear in the screenshot
    cy.screenshot('screenshot-with-blackout', {
      blackout: ['#showMore'], // Blackout the button element
      clip: { x: 0, y: 0, width: 500, height: 300 } // Capture a specific region
    });
  });

});

Explanation of the Test:

  • Cypress Test:
    • The test captures a screenshot with the #showMore button blacked out.
    • The clip option specifies a region (500x300 pixels) of the page to capture.

Output:

screenshot-3
Browser running
third
Screenshot

The screenshot with blackout and clipping is saved as screenshot-with-blackout.png in the cypress/screenshots folder.

Running the Test

  1. Start the Local Server: Ensure that the local server is running and serving the index.html file at http://localhost:3000.
  2. Open Cypress Test Runner: Run the following command in our terminal:
    npx cypress open
  3. Run the Test: Click on screenshot_full_spec.js, screenshot_element_spec.js, or screenshot_options_spec.js to execute the tests and view the captured screenshots.

Conclusion

The screenshot() method in Cypress provides an easy way to capture screenshots during test execution. We can capture screenshots of the entire page, specific elements, or a clipped region, and customize the behavior with various options such as blackout and scale. This method is useful for debugging, visual testing, and documenting UI changes.

Comment
Article Tags:
Software Testing
Testing Tools
Cypress

Explore