Best Selenium Screenshot Libraries for Python Web Testing

Selenium already includes screenshot capture in its Python WebDriver API, so you do not need another library to save a screenshot at a point your test chooses. For pytest suites that should collect screenshots automatically when tests fail and attach them to HTML reports with other diagnostics, pytest-selenium is the strongest-supported integration in the available documentation. Other pytest plugins are listed below, but verify their current maintenance and compatibility before adopting them.

Which Selenium screenshot option should you choose?

Option	Choose it when	What to consider
Selenium WebDriver methods	You want an explicit screenshot at a particular point in a test or helper.	Your code decides when and where to save it. The API itself does not establish automatic failure capture or report attachment.
pytest-selenium	Your suite uses pytest and you want failure diagnostics, potentially in an HTML report.	It provides screenshot capture alongside URL, page HTML, and available logs. Capture settings and exclusions are configurable; collecting all debug artifacts can make reports substantially larger.
pytest-selenium-auto	You want to investigate a plugin whose registry description says it captures on WebDriver events.	The available research does not verify its current maintenance or version compatibility.
pytest-screenshot-on-failure	You want to investigate a plugin described as capturing screenshots on failures.	The available research does not verify its current maintenance or version compatibility.

Compare options on four practical questions: do you call capture directly or have it happen automatically; which events trigger it; does the output include only an image or also URL, HTML, and logs; and can you configure capture or exclude sensitive artifact types? The sources available for this guide do not establish a performance or reliability winner.

Use Selenium’s built-in screenshot API

Use WebDriver’s save_screenshot method to save the current browser view as a PNG. It returns a boolean indicating whether the file was saved. Check the return value so a failed write does not silently pass as a successful artifact.

from pathlib import Path
from selenium import webdriver

output_dir = Path("artifacts")
output_dir.mkdir(parents=True, exist_ok=True)

# Configure a driver for the browser installed in your environment.
driver = webdriver.Chrome()
try:
    driver.get("https://example.com")
    saved = driver.save_screenshot(str(output_dir / "example.png"))
    if not saved:
        raise RuntimeError("WebDriver did not save the screenshot")
finally:
    driver.quit()

Install Selenium and configure a browser driver according to the official Selenium WebDriver documentation. The example assumes Chrome and a working local browser/driver setup. Replace the driver with the browser used by your suite.

For a failure-only screenshot, put the call in a pytest fixture or exception handler and ensure it runs before the driver is closed. Use a unique filename per test, for example by incorporating a sanitized test identifier. Create the destination directory first, and retain the screenshot path in the test report or logs so the artifact can be found.

The Selenium Python API also offers screenshot methods on WebDriver. For the exact method signatures and behavior supported by the Selenium version installed in your project, consult the Python WebDriver API reference. A normal WebDriver screenshot represents the current browser view; it should not be assumed to capture an entire long page unless the browser or an additional technique specifically supports that behavior.

Automatically collect failure artifacts with pytest-selenium

Choose pytest-selenium when pytest is already part of the project and automatic failure diagnostics are useful. Its documented selenium fixture is function-scoped. The plugin’s HTML reporting workflow can include screenshots, page URL, page HTML, and available logs. Its documentation describes selenium_capture_debug settings including never, failure (the documented default), and always, as well as exclusions for debug artifact types.

Install the plugin in the same Python environment as pytest and Selenium, then configure it using the plugin’s current user guide. A typical pytest test uses the provided fixture as follows:

def test_homepage_title(selenium):
    selenium.get("https://example.com")
    assert "Example" in selenium.title

Configure the plugin’s documented HTML report workflow when you want the captured diagnostics assembled into a report. The exact command-line options and configuration names can change between releases; use the pytest-selenium user guide for the version you install rather than copying options from an unrelated release.

The documentation also describes a pytest_selenium_capture_debug hook for saving screenshots to the filesystem, particularly when not using the HTML report. This is useful when the team wants automatic capture but stores artifacts in its own CI artifact system. Read the hook documentation for the expected hook signature and debug payload for your installed version.

Capture policy is a tradeoff: failure limits artifacts to failing tests; always can help diagnose flaky behavior but creates more files and larger reports; never disables automatic capture. Exclude page HTML, logs, or screenshots when they are unnecessary or may expose credentials, personal data, or session state.

Other pytest plugins to evaluate

The pytest plugin registry also lists pytest-selenium-auto and pytest-screenshot-on-failure as screenshot-related options. The registry descriptions establish their stated purposes, not present-day quality, maintenance, supported versions, or integration behavior.

Before adding either package, inspect its release history and project metadata. Confirm Python, Selenium, and pytest version support, how it identifies a failing test or WebDriver event, where it writes files, whether it integrates with your CI report, and how it behaves when screenshot saving itself fails. Try it on a small representative suite before depending on its output.

Or skip the browser setup

If you need a screenshot of a public URL rather than a screenshot from the exact browser session under test, ScreenshotNeo is a website screenshot API and MCP server. A GET request returns an image or PDF, and its documented options include viewport and device settings, full-page capture, custom CSS and JavaScript, waits, and more. It does not replace Selenium when the screenshot must reflect your test’s authenticated session, browser state, or exact interaction sequence.

See the ScreenshotNeo API documentation. One-call example:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers say the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.

Reliability, performance, and cost considerations

• Dependency cost: Selenium’s built-in method adds no screenshot plugin dependency. pytest-selenium adds a pytest integration that is useful when its reporting and automatic diagnostics match your workflow.
• Runtime: A screenshot requires browser capture and file output. The research does not provide comparative benchmarks, so measure suite impact in your own CI if capture frequency matters.
• Storage: Screenshots, page source, and logs consume artifact storage. Capturing on every test can grow reports considerably; use failure-only capture or exclusions when that meets the debugging need.
• Failure handling: Ensure capture runs while the WebDriver session remains alive, use unique paths, and make missing or unwritable artifact directories visible in logs.
• Privacy: Browser images and diagnostic artifacts can contain private page data or session details. Restrict artifact access and retention, and exclude types your team should not store.
• Compatibility: The available research did not verify current version matrices or maintenance status for every plugin. Check project metadata and releases before pinning dependencies.

Troubleshooting

No screenshot file appears

Check the method’s boolean return value, confirm the destination directory exists, and verify the process has write permission. Log the absolute destination path and inspect the CI artifact collection rules.

The screenshot is blank or shows the previous page

The page may not have finished rendering when capture ran. Wait for a meaningful page condition in the test before capturing, and confirm navigation did not fail. The research does not establish a universal wait duration; use the application’s actual readiness condition.

pytest-selenium artifacts are missing

Confirm the test is using the plugin’s selenium fixture, that capture is not set to never, and that the report or debug hook is configured as intended. Compare your configuration with the guide for the installed plugin version.

HTML reports are unexpectedly large

Capturing debug data for every test can substantially increase report size. Switch to failure capture if appropriate, and exclude screenshots, HTML, or logs that are not needed for the investigation.

Artifacts contain secrets or personal data

Treat screenshots and companion diagnostics as sensitive test output. Exclude unneeded artifact types, avoid putting secrets into rendered pages, and limit who can access stored reports.

A plugin fails after a dependency upgrade

Check the plugin’s declared Python, Selenium, and pytest requirements and release history. Compatibility for the alternatives named here was not verified by the available research, so test the upgrade in a small environment before changing the main suite.

Frequently asked questions

Do I need a separate library to take a Selenium screenshot?

No. Selenium’s Python WebDriver API includes screenshot-saving methods. Add a plugin when you need pytest integration or automatic artifact handling.

Can I email a screenshot automatically when a test fails?

The reviewed Selenium API and pytest-selenium documentation establish capture and report diagnostics, not an email delivery workflow. Add email handling in your CI or application workflow and attach the saved artifact there.

Does a WebDriver screenshot capture a full webpage?

Do not assume so. The standard screenshot call captures the current browser view; verify full-page behavior for your browser and installed Selenium version if you require it.

Which option is fastest?

The available sources include no comparable benchmarks. Measure your own suite with its browser, page mix, capture frequency, and CI storage path.