For a screenshot at a specific point in a Python Selenium test, use Selenium WebDriver’s built-in screenshot methods; you do not need a separate library. For automatic failure artifacts in a pytest suite, pytest-selenium is the strongest-supported choice in the available documentation: it can add screenshots and other diagnostics to its HTML reporting workflow. Other pytest screenshot plugins exist, but their current compatibility and maintenance status are not established here.
Which Selenium screenshot option should you use?
| Option | Best fit | What to weigh |
|---|---|---|
| Selenium Python WebDriver methods | A test or helper that should explicitly decide when and where to save a screenshot. | You control the call and file path. Automatic failure capture and report attachment are not established by the WebDriver API itself. Selenium Python WebDriver API |
| pytest-selenium | A pytest suite that needs failure diagnostics, especially alongside HTML reporting. | Can provide a screenshot, URL, page HTML, and available logs. Capture behavior is configurable; collecting all debug artifacts can substantially increase report size. pytest-selenium user guide |
| pytest-selenium-auto | Teams evaluating capture triggered by WebDriver events. | The pytest registry describes event-based screenshot capture, but current maintenance and compatibility have not been verified. pytest plugin list |
| pytest-screenshot-on-failure | Teams evaluating a plugin focused on screenshots after test failures. | PyPI and the pytest registry describe its purpose; current maintenance and compatibility have not been verified. PyPI project page |
Choose by capture trigger and evidence needs: explicit call versus automatic capture, a chosen event versus a test failure, and screenshot alone versus a screenshot plus URL, HTML, or logs. There is no supported performance or reliability winner in the sources cited here.
Save a screenshot directly with Selenium
WebDriver provides save_screenshot(), which writes the current browser view to a PNG file and returns a boolean indicating whether the save succeeded. The related get_screenshot_as_file() method also saves to a file. Use an explicit path so your test runner or CI job can collect the output.
from pathlib import Path
from selenium import webdriver
output_dir = Path("artifacts")
output_dir.mkdir(parents=True, exist_ok=True)
with webdriver.Chrome() as driver:
driver.get("https://example.com")
ok = driver.save_screenshot(str(output_dir / "example.png"))
if not ok:
raise RuntimeError("WebDriver could not save the screenshot")The example captures only where the test calls it. To take a screenshot on failure, catch the exception around the test actions, save the file, and re-raise so pytest still reports the failure:
#1 Best Overall
from pathlib import Path
from selenium import webdriver
output_dir = Path("artifacts")
output_dir.mkdir(parents=True, exist_ok=True)
def test_checkout():
with webdriver.Chrome() as driver:
try:
driver.get("https://example.com/checkout")
# Add test actions and assertions here.
assert "Checkout" in driver.title
except Exception:
driver.save_screenshot(str(output_dir / "checkout-failure.png"))
raiseThis simple pattern is useful for an individual test, but it requires each test or a shared wrapper to manage its own capture logic. Selenium’s API documentation describes saving screenshots; it does not by itself establish an automatic pytest failure-reporting workflow.
Collect failure artifacts with pytest-selenium
If the suite already uses pytest and you want failure diagnostics gathered consistently, pytest-selenium supplies a function-scoped selenium fixture. Its documented HTML-report workflow can include screenshots together with the failing page’s URL, HTML, and available logs. Consult the user guide for installation and report setup for the version you use; the available evidence does not establish a current Python, Selenium, and pytest compatibility matrix.
Configure capture behavior
The documentation describes the selenium_capture_debug choices as never, failure (the documented default), and always. It also describes excluding selected debug types. For suites that do not use its HTML report, the pytest_selenium_capture_debug hook can save screenshot artifacts to the filesystem. Check the documentation for the exact configuration syntax supported by your installed release.
Capturing every available artifact may make reports substantially larger. Exclude artifacts the team does not need, and treat screenshots, page source, and logs as potentially sensitive: they can expose credentials or personal data. Store and share them under the same access controls as other test diagnostics.
Other pytest screenshot plugins
The pytest plugin registry lists pytest-selenium-auto, described as capturing screenshots on WebDriver events, and pytest-screenshot-on-failure, described as taking screenshots on failure. These descriptions establish stated purposes, not quality, active maintenance, current version support, or integration with a particular report format. Before adopting either, inspect its release history and project metadata, confirm supported Python, Selenium, and pytest versions, and try it in the same CI and reporting setup used by your suite.
Use a screenshot API instead of managing a browser
If your goal is to capture a URL for a report or workflow rather than control a Selenium browser session, ScreenshotNeo is an alternative to try first. It is a website screenshot API and MCP server; it is not a Selenium pytest plugin. A single GET request returns a PNG, JPEG, WebP, or PDF. Its cleanup can accept cookie or consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture, with each step switchable. Only clean shots are billed: bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses identify the page verdict and billing status in headers. Its MCP server offers screenshot tools for AI agents and MCP clients.
Or skip the browser setup
Use an API key from ScreenshotNeo’s API documentation. This cURL call saves a WebP screenshot:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpCookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000. Sign up for free.
Free tools Windows power users keep installed
One-click scans. No signup required.
Operational considerations
File handling and CI
- Create the artifact directory before saving files, and use distinct names if parallel tests could otherwise overwrite one another.
- Configure CI to collect the artifact directory after a test run, including failed runs; a successful local file save does not automatically publish or attach it to a test report.
- Decide how long artifacts should be retained and who can access them, particularly if pages contain account data or test credentials.
Cost and report size
The direct Selenium methods add no separate screenshot-plugin dependency for capture, though they still require the browser and driver setup your Selenium tests use. pytest-selenium adds an integration dependency and may increase report size when many debug types or tests are captured. No benchmark in the cited sources establishes relative runtime overhead, so measure the effect in your own suite if capture volume matters.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting
- No screenshot file appears: Check the return value from
save_screenshot(), confirm the output directory exists, and verify that the test process can write to the path. In CI, make sure the configured artifact collection step includes that path. - Failure artifacts are missing: Confirm pytest-selenium is installed and its fixture is used, review the capture setting (including whether it is
never), and check that the selected debug types have not been excluded. For filesystem capture without the HTML report, verify thepytest_selenium_capture_debughook is configured for your installed version. - Reports or artifacts are unexpectedly large: Reduce capture frequency or exclude debug types your team does not use; the pytest-selenium documentation warns that always collecting debug information can substantially increase report size.
- A candidate plugin fails to install or run: Compare its declared Python, Selenium, and pytest requirements with your environment and check recent release and maintenance information. The available registry descriptions do not establish current compatibility.
- A screenshot contains sensitive information: Restrict access and retention, and exclude screenshots, page source, or logs when they are not needed for diagnosis.
Frequently Asked Questions
Does Selenium’s screenshot API save a PNG or a PDF?
The documented WebDriver screenshot-saving methods save screenshots as PNG files.
Does pytest-selenium require pytest?
Yes. It is a pytest integration built around pytest fixtures and hooks.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
