Selenium Screenshot Leitfaden: Code-Beispiele (2026)

# Selenium Screenshot Leitfaden: Seiten, Elemente und Fehler erfassen

Um einen Selenium-Screenshot zu erstellen, caste den Driver auf TakesScreenshot und rufe getScreenshotAs(OutputType.FILE) in Java, driver.save_screenshot("shot.png") in Python oder driver.takeScreenshot() in JavaScript auf. Selenium 4 unterstützt Erfassungen auf Element-Ebene und (in einigen Browsern) Full-Page-Erfassungen über das Chrome DevTools Protocol.

Selenium WebDriver ist die richtige Wahl für bestehende Test-Suiten. Es passt auch zu Cross-Browser-Läufen auf BrowserStack oder Sauce Labs und für mehrsprachige Teams, die Java, Python, .NET und Ruby mischen. Neuere Tools wie Playwright und Puppeteer sind schneller. Aber Selenium hat immer noch die Nase vorn bei Mehrsprachigkeit und liefert Safari-Unterstützung sofort mit. Dieser Leitfaden geht jede Screenshot-Operation durch, die du brauchst. Code in drei Sprachen plus die Stolperfallen, auf die QA-Engineers in der Produktion stoßen.

Setup-Matrix: Selenium für deinen Stack installieren

Selenium 4.10 und neuer werden mit Selenium Manager ausgeliefert. Es holt den passenden Chrome-, Firefox-, Edge- oder Safari-Driver für deinen Browser. Du brauchst keine webdriver-manager-Pakete mehr. Du musst auch keine ChromeDriver-Versionen mehr von Hand fixieren. In den offiziellen Selenium-Docs findest du die komplette Setup-Matrix.

Seiten-Screenshot: Viewport-Erfassung in drei Sprachen

Der Standard-Selenium-Screenshot ist eine Viewport-Erfassung. Er zeigt nur das, was der Nutzer sieht, nicht die komplette scrollbare Seite.

Python:

from selenium import webdriver

driver = webdriver.Chrome()
driver.get("https://example.com")
driver.save_screenshot("page.png")
driver.quit()

Java:

import org.openqa.selenium.*;
import org.openqa.selenium.chrome.ChromeDriver;
import java.io.File;
import java.nio.file.Files;

WebDriver driver = new ChromeDriver();
driver.get("https://example.com");
File src = ((TakesScreenshot) driver).getScreenshotAs(OutputType.FILE);
Files.copy(src.toPath(), new File("page.png").toPath());
driver.quit();

JavaScript (Node):

const { Builder } = require('selenium-webdriver');
const fs = require('fs');

const driver = await new Builder().forBrowser('chrome').build();
await driver.get('https://example.com');
const png = await driver.takeScreenshot();
fs.writeFileSync('page.png', png, 'base64');
await driver.quit();

Das ist der Standardaufruf. Jedes Binding kapselt im Hintergrund denselben WebDriver-Protokoll-Endpunkt.

Element-Screenshot: eine einzelne Komponente erfassen

Selenium 4 hat native Element-Screenshots ergänzt, sodass du direkt auf einen bestimmten Button, eine Karte oder ein Diagramm zuschneiden kannst, ohne Nachbearbeitung.

# Python
header = driver.find_element("css selector", "h1.hero-title")
header.screenshot("hero.png")

// Java
WebElement header = driver.findElement(By.cssSelector("h1.hero-title"));
File src = header.getScreenshotAs(OutputType.FILE);
Files.copy(src.toPath(), new File("hero.png").toPath());

// JavaScript
const header = await driver.findElement(By.css('h1.hero-title'));
const png = await header.takeScreenshot();
fs.writeFileSync('hero.png', png, 'base64');

Element-Screenshots sind pixelgenau. Sie respektieren das eigene Padding und den Border des Elements. Sie sind der sauberste Weg, um Bilder auf Komponenten-Ebene in ein Visual-Diff-Tool einzuspeisen.

Speichern als base64, Byte-Array oder Datei

Oft willst du keine Datei auf der Festplatte. Vielleicht hängst du das Bild an einen Test-Report. Oder du bettest es in eine HTML-E-Mail ein. Oder du pushst es direkt zu S3.

# Python — base64-String
b64 = driver.get_screenshot_as_base64()

# Python — Rohbytes
png_bytes = driver.get_screenshot_as_png()

// Java — Datei, Bytes oder base64
File file = ((TakesScreenshot) driver).getScreenshotAs(OutputType.FILE);
byte[] bytes = ((TakesScreenshot) driver).getScreenshotAs(OutputType.BYTES);
String b64 = ((TakesScreenshot) driver).getScreenshotAs(OutputType.BASE64);

// JavaScript — base64 standardmäßig
const b64 = await driver.takeScreenshot();
const buf = Buffer.from(b64, 'base64');

Selenium gibt nur PNG aus. Es gibt keine native Option für JPEG oder WebP. Brauchst du ein kleineres Format? Kodiere die PNG-Bytes nach der Erfassung über Pillow (Python) oder sharp (Node).

Die Full-Page-Einschränkung: Selenium's größte Lücke

Hier hängt Selenium hinter Playwright und Puppeteer zurück. Selenium WebDriver hat keine Einzeiler-Full-Page-API, die überall funktioniert. Standardmäßig bekommst du nur den Viewport.

Du hast drei Workarounds:

1. Native API nur für Firefox. Selenium 4 hat getFullPageScreenshotAs() für den Firefox-Driver hinzugefügt:

// Nur Firefox
File src = ((FirefoxDriver) driver).getFullPageScreenshotAs(OutputType.FILE);

Wenn du dich für Screenshot-Tests bereits auf Firefox standardisiert hast, ist das der sauberste Weg.

2. Headless Chrome + Fenstergrößenänderung. Ändere die Fenstergröße so, dass sie zu body.scrollHeight passt. Mache dann einen normalen Screenshot. Chrome erfasst das gesamte Dokument, weil alles in den Viewport passt.

total_height = driver.execute_script("return document.body.scrollHeight")
driver.set_window_size(1280, total_height)
driver.save_screenshot("fullpage.png")

Das funktioniert im headless-Modus. Aber es bricht bei fixierten Headern und lazy-geladenen Bildern. Scrolle die Seite zuerst, wenn deine Site Bilder beim Scrollen lädt.

3. Chrome DevTools Protocol (CDP). In Selenium 4 kannst du CDP-Befehle direkt aufrufen:

result = driver.execute_cdp_cmd(
    "Page.captureScreenshot",
    {"captureBeyondViewport": True, "fromSurface": True}
)
import base64
with open("fullpage.png", "wb") as f:
    f.write(base64.b64decode(result["data"]))

CDP ist der zuverlässigste Ansatz. Aber er bindet dich an Chromium-basierte Browser. Wähle den Workaround, der zu deiner Browser-Matrix passt.

Gesponsert von den Machern

Genug von langweiligen Screenshots? Probier ScreenSnap Pro.

Wunderschöne Hintergründe, professionelle Annotationen, GIF-Aufnahme und sofortiges Cloud-Sharing — alles in einer App. Einmalig 29 $, für immer deins.

Sieh, was es kann

Visuelle Regressionstests mit Selenium

Selenium hat keinen eingebauten Bild-Diff. Du paarst es mit einem von drei Tools: Applitools, Percy oder einer Open-Source-Bibliothek wie pixelmatch.

Applitools kapselt den Screenshot-Aufruf, sodass du keine Baselines von Hand verwaltest:

Eyes eyes = new Eyes();
eyes.setApiKey(System.getenv("APPLITOOLS_API_KEY"));
eyes.open(driver, "MyApp", "Login Page Test");
eyes.checkWindow("Login form");
eyes.close();

Percy nutzt ein ähnliches Muster in JavaScript:

const percySnapshot = require('@percy/selenium-webdriver');
await percySnapshot(driver, 'Login page');

Für einen tieferen Blick auf Frameworks und Diff-Strategien siehe unseren Leitfaden zu visuellen Regressionstests. Wähle einen Managed Service, wenn dir Setup-Geschwindigkeit wichtiger ist als Kosten. Wähle pixelmatch, wenn du keine Gebühren willst und nichts dagegen hast, die Diff-Schleife selbst zu verdrahten.

Häufige Stolperfallen, die jede QA trifft

Ein paar Produktionsfallen erwischen Teams immer wieder.

Warte vor der Erfassung. Ein Screenshot, der vor dem Rendern der Seite erstellt wird, ist nur eine leere Leinwand. Wickle Erfassungen mit WebDriverWait ein:

from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.common.by import By

WebDriverWait(driver, 10).until(
    EC.presence_of_element_located((By.CSS_SELECTOR, ".product-card"))
)
driver.save_screenshot("loaded.png")

Nutze den neuen headless-Modus. In Chrome 109 und neuer ist das alte --headless-Flag veraltet. Nutze --headless=new:

options = webdriver.ChromeOptions()
options.add_argument("--headless=new")
options.add_argument("--window-size=1920,1080")

Der neue headless-Modus nutzt dieselbe Rendering-Pipeline wie Chrome mit UI. Deine Screenshots stimmen mit dem überein, was Nutzer sehen.

Nutze absolute Pfade in CI. Relative Pfade brechen in Docker- und GitHub-Actions-Runnern. Das Arbeitsverzeichnis verschiebt sich. Löse Pfade vorab auf:

import os
out = os.path.join(os.getcwd(), "artifacts", "page.png")
driver.save_screenshot(out)

Achte auf Zoom und DPI. Browser-Zoom und High-DPI-Displays verändern die Screenshot-Maße. Erzwinge eine feste Fenstergröße und fixiere den Device Scale Factor. Das gibt dir byte-gleiche Screenshots in CI:

options.add_argument("--force-device-scale-factor=1")
options.add_argument("--window-size=1280,720")

Erfasse bei Test-Fehlschlag. Das ist das wertvollste Muster. Hänge dich in den Fehlerpfad deines Test-Frameworks. Jeder rote Build hinterlässt dann ein Screenshot-Artefakt. In pytest:

import pytest

@pytest.fixture(autouse=True)
def screenshot_on_failure(request, driver):
    yield
    if request.node.rep_call.failed:
        driver.save_screenshot(f"failures/{request.node.name}.png")

In TestNG (Java) implementiere ITestListener.onTestFailure und rufe von dort getScreenshotAs auf.

Selenium vs Playwright vs Puppeteer für Screenshots

Jedes Tool hat einen anderen Sweet Spot:

Selenium ist älter und langsamer. Aber es hat die breiteste Sprachunterstützung und den einzigen Out-of-the-Box-Safari-Driver. Wenn dein Team heute Java-Tests schreibt, ist Selenium immer noch der Weg des geringsten Widerstands. Für eine direkte Gegenüberstellung der beiden neueren Tools siehe Puppeteer vs Playwright. Unsere Übersicht zu den besten Screenshot-APIs deckt gehostete Dienste ab, die WebDriver für einfachere Aufgaben ersetzen können.

Für Ad-hoc-Desktop-Screenshots beim Debuggen bietet ScreenSnap Pro Region-Erfassung, Annotation und sofortige Cloud-Links auf Mac und Windows. Test-Code bleibt in Selenium. Schnelle "Schick das einem Kollegen"-Captures bleiben in einer Desktop-App.

CI/CD-Beispiel: Selenium auf GitHub Actions

Hier ist ein funktionierender GitHub-Actions-Workflow, der Selenium mit ChromeDriver ausführt und alle Screenshot-Artefakte bei Fehlschlag hochlädt:

name: Selenium Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Install dependencies
        run: pip install selenium pytest
      - name: Run tests
        run: pytest tests/ --tb=short
      - name: Upload screenshots
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: screenshots
          path: failures/

Ubuntu-Runner werden mit vorinstalliertem Chrome ausgeliefert. Selenium Manager wählt den passenden ChromeDriver. Die if: always()-Klausel lädt Screenshots auch dann hoch, wenn Tests fehlschlagen. Genau dann willst du sie. Das Selenium GitHub-Repository hat mehr Beispiel-Workflows in seinen Docs.

Häufig gestellte Fragen

Wie erstelle ich einen Full-Page-Screenshot in Selenium?

Es gibt keinen portablen Einzeiler. Drei Optionen funktionieren. Nutze getFullPageScreenshotAs() in Firefox. Oder ändere die Fenstergröße auf document.body.scrollHeight und mache dann einen normalen Screenshot. Oder rufe das Chrome DevTools Protocol mit Page.captureScreenshot und captureBeyondViewport: true auf. Der CDP-Ansatz ist auf Chromium-Browsern am zuverlässigsten.

Was ist der Unterschied zwischen Selenium und Playwright bei Screenshots?

Playwright hat native Full-Page- und JPEG-Screenshots. Es läuft schneller. Es liefert standardmäßig Chromium, Firefox und WebKit aus. Selenium braucht Workarounds für Full-Page-Erfassungen und gibt nur PNG aus. Aber es unterstützt fünf Sprachen (vs. vier in Playwright) und bietet Safari-Tests über SafariDriver. Wähle Playwright für neue Test-Suiten. Wähle Selenium, wenn du eine Java-Codebasis hast oder breite Cross-Browser-Abdeckung brauchst.

Kann Selenium Element-Screenshots erstellen?

Ja, seit Selenium 4. Rufe element.screenshot("file.png") in Python auf. Nutze element.getScreenshotAs(OutputType.FILE) in Java. Oder await element.takeScreenshot() in JavaScript. Die Ausgabe wird auf die Bounding Box des Elements zugeschnitten und respektiert sein eigenes Padding.

Unterstützt Selenium visuelle Regressionstests?

Nicht nativ. Du paarst Selenium mit einem Diff-Tool: Applitools, Percy oder Open-Source-Bibliotheken wie pixelmatch und Resemble.js. Applitools und Percy übernehmen Baselines und Freigabe-Workflows für dich. Pixelmatch ist kostenlos, aber du schreibst die Vergleichsschleife selbst.

Wie speichere ich einen Selenium-Screenshot als base64?

In Python nutze driver.get_screenshot_as_base64(). In Java caste auf TakesScreenshot und rufe getScreenshotAs(OutputType.BASE64) auf. In JavaScript gibt driver.takeScreenshot() bereits einen base64-String zurück. Base64 ist nützlich, um Screenshots in HTML-Reports einzubetten. Es lässt dich auch zu APIs pushen, ohne auf die Festplatte zu schreiben.

Wie erstelle ich nur dann einen Screenshot, wenn ein Test fehlschlägt?

Hänge dich in den Fehlerpfad deines Test-Frameworks. In pytest nutze eine autouse=True-Fixture, die request.node.rep_call.failed prüft. In TestNG implementiere ITestListener.onTestFailure. In Mocha nutze einen afterEach-Hook, der this.currentTest.state inspiziert. Setze den Test-Namen in den Dateinamen. So lassen sich Artefakte leicht dem fehlgeschlagenen Test zuordnen.

Verändert headless Chrome die Screenshot-Ausgabe?

Früher schon. Der neue headless-Modus (--headless=new in Chrome 109+) nutzt dieselbe Rendering-Pipeline wie Chrome mit UI. Screenshots stimmen Pixel für Pixel überein. Der alte headless-Modus konnte leicht andere Schriftarten und Schatten produzieren. Nutze für Screenshot-Tests immer den neuen Modus.

Zusammenfassung

Selenium ist nicht das schnellste Tool für Screenshots. Aber es ist das flexibelste über Sprachen und Browser hinweg. Drei Muster zum Merken. Caste auf TakesScreenshot für Roh-Captures. Rufe element.screenshot() für Bilder auf Komponenten-Ebene auf. Stütze dich auf CDP oder Firefox's native API, wenn du Full-Page-Ausgabe brauchst. Paare es mit einem Diff-Tool für visuelle Regression. Jetzt hast du eine komplette Pipeline von der Erfassung bis zum Artefakt.

Für die Desktop-Seite deines Workflows übernimmt ScreenSnap Pro Ad-hoc-Captures mit Annotation und Ein-Klick-Cloud-Sharing. Kein Test-Framework nötig. Es ist ein einmaliger Kauf für 29 $ für Mac und Windows.