sodcalculator

10 Tech How-To

How to Add Browser & Viewport Details to QA Screenshots

Guide 10-52422 · Updated · Step by step

Capturing screenshots during QA testing is only half the battle — without browser and viewport details, a screenshot can be misleading or impossible to reproduce. This guide shows you how to automatically embed browser name, version, and viewport dimensions into your screenshots, so every captured image carries its own context. You’ll need a basic understanding of your testing framework (e.g., Selenium, Playwright, Cypress) and access to its configuration files.

What You’ll Need

  • A testing framework that supports screenshots (Selenium, Playwright, Cypress, etc.)
  • Access to your test scripts or configuration files
  • Basic knowledge of JavaScript, Python, or your framework’s language
  • An image editing library (e.g., Pillow for Python, Sharp for Node.js) or a built-in annotation tool

Step-by-Step

  1. Identify your screenshot capture method. Determine how your framework takes screenshots. For example, in Selenium WebDriver, you use driver.get_screenshot_as_file() (Python) or driver.save_screenshot() (Java). In Playwright, it’s page.screenshot(). Note the output file path and format (usually PNG).
  2. Retrieve browser and viewport information. Use your framework’s API to get the browser name, version, and viewport size. In Selenium: driver.capabilities['browserName'], driver.capabilities['browserVersion'], and driver.get_window_size(). In Playwright: browser.version() and page.viewport_size().
  3. Format the metadata string. Create a readable string like Chrome 120.0.6099.109 | 1366x768. Include the operating system if useful (e.g., Windows 10).
  4. Choose an annotation method. You can either overlay text on the screenshot using an image library, or use your framework’s built-in screenshot annotation features (if available). For Playwright, you can use the clip option to capture a specific area, but for text overlay, you’ll need an external library.
  5. Implement the text overlay. Here’s a Python example using Pillow:
    from PIL import Image, ImageDraw, ImageFont
    
    def add_metadata_to_screenshot(screenshot_path, metadata):
        img = Image.open(screenshot_path)
        draw = ImageDraw.Draw(img)
        font = ImageFont.load_default()  # or specify a larger font
        # Position text at top-left with a semi-transparent background
        draw.rectangle([0, 0, 300, 20], fill=(0, 0, 0, 128))
        draw.text((5, 2), metadata, fill=(255, 255, 255), font=font)
        img.save(screenshot_path)
    
  6. Integrate into your test flow. After taking a screenshot, call the annotation function with the metadata. For example, in a Selenium test:
    driver.save_screenshot('test.png')
    add_metadata_to_screenshot('test.png', f"{browser} {version} | {width}x{height}")
    
  7. Test on different viewports. If you run responsive tests, ensure the viewport size is correctly captured. You can set the viewport using driver.set_window_size() or Playwright’s page.set_viewport_size() before taking the screenshot.
  8. Automate for all screenshots. Instead of manually calling the function each time, wrap your screenshot logic in a helper method that automatically adds metadata. This ensures consistency across all test runs.
  9. Store screenshots with meaningful filenames. Include the metadata in the filename as well, e.g., test_login_chrome_1366x768.png. This makes it easier to search and organize later.
  10. Verify the output. Run a test and open the screenshot to confirm the text is readable, positioned correctly, and doesn’t overlap important UI elements.

Common Mistakes

  • Hardcoding viewport size. Always retrieve the actual viewport from the driver, not a hardcoded value, because it can change due to browser zoom or window resizing.
  • Not handling font issues. Using a default font may be too small or unreadable. Use a larger, monospaced font for clarity.
  • Forgetting to save the modified image. If you open the screenshot and then don’t save it, the metadata won’t be added.
  • Placing text over critical content. Choose a location (like top-left or bottom-right) that rarely contains important UI elements, or make the background semi-transparent.
  • Ignoring device pixel ratio. On high-DPI screens, the viewport size in CSS pixels may differ from actual device pixels. Use the framework’s reported viewport, not the window size in physical pixels.

Tips

  • Use a consistent format. Standardize the metadata format across your team, e.g., Browser Name Version | WidthxHeight | OS.
  • Include the test case name. Adding the test name helps identify which scenario the screenshot belongs to.
  • Leverage your CI/CD pipeline. In CI, you can set environment variables for browser and viewport and read them in your script, making it easy to switch configurations.
  • Consider using a screenshot service. Tools like Percy or Applitools automatically capture browser and viewport info, but they integrate with your existing framework.
  • Make the text small but readable. A font size of 12-14px is usually sufficient; avoid covering more than 10% of the image.

Troubleshooting

  • Text is not appearing on the screenshot. Check that you are saving the image after drawing. Also, ensure the image mode supports transparency (use RGBA). If using Pillow, convert to RGBA before drawing.
  • Viewport size is incorrect. If you’re using Selenium, make sure you call get_window_size() after the page has loaded, as the browser may adjust size after navigation. For Playwright, use page.viewport_size after the page is ready.
  • Browser version is missing. Some drivers may not return the version. Use driver.capabilities.get('browserVersion') and fall back to driver.capabilities['version'] if needed.
  • Text overlaps on mobile screenshots. On narrow viewports, the text may span multiple lines. Use a smaller font or position it at the bottom.
  • Image library not installed. Install the required library (e.g., pip install Pillow for Python, npm install sharp for Node.js).
  • Screenshot is saved but annotation fails. Ensure the file is not locked by another process. Save the annotated image to a temporary file and then replace the original.

Frequently Asked Questions

Can I do this without an external image library?

Some frameworks like Playwright have built-in screenshot options that can add a footer or header, but they don’t support custom text. You can use a simple HTML canvas approach if you capture via a browser, but for most cases, an image library is the easiest.

Will this work with parallel test execution?

Yes, as long as each test writes to a unique file name. Include the test name or a timestamp in the filename to avoid overwrites.

How do I get the browser version in Cypress?

In Cypress, you can use Cypress.browser object which contains name and version. For viewport, use cy.viewport() to set, and cy.window().innerWidth to get the current width.

Is it possible to add metadata to screenshots taken with Selenium Grid?

Yes, the capabilities from the remote driver include browser and version. The viewport size is available via driver.get_window_size() even on remote nodes.

Can I add a timestamp as well?

Absolutely. Include the current date/time in the metadata string or filename. Use a standard format like YYYY-MM-DD_HH-MM-SS to avoid sorting issues.

What if I need to capture screenshots on a headless browser?

Headless browsers still report viewport size and browser version. The same code works; just ensure you set the viewport size explicitly if needed.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →