How to Take Screenshots in Robot Framework

Use the capture keyword that matches your target and browser library: the built-in Screenshot library captures the test machine’s desktop, SeleniumLibrary captures a Selenium page or element, and Browser captures a Playwright-powered viewport, element, or full page.

Choose an artifact directory that your CI system preserves, and make sure a physical or virtual display exists when using desktop capture. The sections below provide runnable examples, options, failure fixes, and CI guidance.

Choose the right Robot Framework screenshot method

Need	Use	Important detail
Entire desktop or native application	Built-in `Screenshot`	Requires a physical or virtual display and a supported capture backend.
Current page in a Selenium test	`Capture Page Screenshot`	Saves an image and embeds it in the log by default.
One element in Selenium	`Capture Element Screenshot`	Element support varies by browser and driver.
Viewport, element, or full page in Browser	`Take Screenshot`	Use `selector` for an element and `fullPage=True` for the scrollable page.

Capture the test machine’s desktop

The built-in library takes a JPEG of the operating system desktop where the test runs. It is suitable for native applications, desktop dialogs, and debugging the complete runner state.

*** Settings ***
Library    Screenshot

*** Test Cases ***
Capture Desktop
    Take Screenshot

Take Screenshot embeds the image in the Robot Framework log. To keep a separate file linked from the log, use:

*** Settings ***
Library    Screenshot

*** Test Cases ***
Capture Desktop Artifact
    Take Screenshot Without Embedding    desktop-state.jpg

Choose a directory and filename

Set the directory when importing the library, or change it during a suite. The directory must already exist for the built-in keyword.

*** Settings ***
Library    Screenshot    screenshot_directory=${OUTPUTDIR}/screenshots

*** Test Cases ***
Named Desktop Capture
    Take Screenshot    ${OUTPUTDIR}/screenshots/login-desktop.jpg    width=800

*** Settings ***
Library    Screenshot

*** Test Cases ***
Set Directory First
    Set Screenshot Directory    ${OUTPUTDIR}/screenshots
    Take Screenshot    failure-state.jpg

If you reuse a name without a .jpg or .jpeg extension, the library adds a unique index for repeated captures. The default location is the log directory, or the output directory when no log is generated. See the Robot Framework user guide for the current library behavior.

Display and operating-system requirements

macOS uses its built-in screencapture utility.
Other systems may need a supported tool or module such as wxPython, PyGTK, Pillow on Windows, or scrot on non-Windows systems.
A headless CI runner still needs a physical or virtual display. Configure the display before starting Robot Framework.

Capture a SeleniumLibrary browser page or element

Use SeleniumLibrary when the test already opens the browser through Selenium. A page capture records the current browser page; an element capture targets a located element.

*** Settings ***
Library    SeleniumLibrary

*** Test Cases ***
Capture Browser Page And Element
    Open Browser    https://example.com    chrome
    Capture Page Screenshot    ${OUTPUTDIR}/artifacts/example-page.png
    Capture Element Screenshot    css:main    ${OUTPUTDIR}/artifacts/example-main.png
    Close Browser

Capture Page Screenshot and Capture Element Screenshot embed the result in the log by default. Pass a filename to control the artifact location. Use {index} in a filename when a loop or failure hook can capture the same step repeatedly:

Capture Page Screenshot    ${OUTPUTDIR}/artifacts/page-{index}.png

Element screenshots have limited support among browser vendors. If the call fails, verify the browser, WebDriver, and driver versions, then try a page screenshot to separate an element-support problem from a general capture problem. Refer to the SeleniumLibrary keyword documentation.

Capture a viewport, element, or full page with Browser

Robot Framework Browser is powered by Playwright. Its Take Screenshot keyword captures the current viewport by default. Supply a selector for one element or fullPage=True for the full scrollable document.

*** Settings ***
Library    Browser

*** Test Cases ***
Capture Full Page
    New Page    https://example.com
    Take Screenshot    fullPage=True    fileType=png

*** Settings ***
Library    Browser

*** Test Cases ***
Capture Viewport And Element
    New Page    https://example.com
    Take Screenshot    fileType=jpeg    path=${OUTPUTDIR}/browser/viewport.jpg
    Take Screenshot    selector=main    fileType=png    path=${OUTPUTDIR}/browser/main.png
    Take Screenshot    fullPage=True    fileType=png    path=${OUTPUTDIR}/browser/full-page.png

Browser supports PNG or JPEG, embedding in the HTML log, choosing a path, and returning image data. Check the keyword documentation for the installed version because argument names and defaults can evolve. Its default screenshot directory is ${OUTPUTDIR}/browser/screenshot. The documented ${OUTPUTDIR}/browser/ directory is removed at first suite startup, so configure a retained artifact path when files must survive between runs. See the Browser keyword documentation.

Make screenshots useful in failures

Capture after the state you need is visible: wait for the page or element, perform the click that opens a dialog, and then save a uniquely named artifact. Keep screenshots in a CI-collected directory and include the test name or browser in the filename.

*** Settings ***
Library    Browser

*** Test Cases ***
Checkout Failure Evidence
    New Page    https://example.com/checkout
    Wait For Elements State    css:[data-testid="checkout"]    visible
    Take Screenshot    selector=css:[data-testid="checkout"]    path=${OUTPUTDIR}/artifacts/checkout.png

Common errors and fixes

Error or symptom	Cause	Fix
Desktop capture cannot start	No physical or virtual display, or no supported capture backend.	Configure a display for the runner and install a supported module/tool.
Screenshot file is missing	The directory does not exist or CI does not collect it.	Create the directory before the test and publish that directory as a CI artifact.
Only part of a page is captured	A viewport capture was requested.	Use Browser with `fullPage=True`; Selenium page capture is generally the current page view provided by the driver.
Element screenshot fails	Browser/driver does not support element capture.	Check the SeleniumLibrary warning, update the compatible driver, or capture the page instead.
Image shows a loading state	Capture happened before the page finished rendering.	Wait for a selector, a visible state, or the application’s ready condition before capturing.
Old artifacts disappear	Browser removes its default directory at first suite startup.	Use an explicit retained path outside `${OUTPUTDIR}/browser/` and configure CI collection.
Repeated captures overwrite one another	A fixed filename is reused.	Use `{index}`, a test-specific name, or a timestamp generated by the calling code.

Performance, reliability, and cost

Performance: full-page captures take longer and use more memory than viewport or element captures, especially on long pages. Capture only the scope needed for diagnosis.
Reliability: deterministic waits produce more useful images than fixed short sleeps. Keep browser and driver versions compatible and reserve desktop capture for tests that need the whole machine.
Artifacts: embedding increases log size; use “without embedding” or explicit files when suites create many images.
Cost: Robot Framework libraries run on your own test infrastructure. Any cloud browser, CI minutes, storage, or display service is billed by that provider; the libraries themselves do not establish a separate screenshot service price.

Or skip the browser setup

ScreenshotNeo returns a PNG, JPEG, WebP, or PDF from one GET request, so you can capture a URL without installing Robot Framework browser drivers. Its cleanup accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response reports the page verdict and billing status in X-Page-Verdict and X-Billed headers.

Install the Python dependency if needed, then call it from a Robot test or a setup script:

*** Settings ***
Library    OperatingSystem

*** Test Cases ***
Capture With ScreenshotNeo
    ${result}=    Run    curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o ${OUTPUTDIR}/example.webp
    Should Be Equal As Integers    ${result}    0

Equivalent requests:

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

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for all 63 options, including full-page and selector capture, device and retina settings, custom CSS and JavaScript, waits, request blocking, headers and cookies, timezone and geolocation, caching, signed links, asynchronous jobs, webhooks, bulk capture, PDFs, and usage reporting. An MCP server also lets Claude, Cursor, and other MCP clients call take_screenshot, get_page_info, and capture_pdf.

Free accounts include 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.

FAQ

Does Robot Framework screenshot the browser or the whole computer?

It depends on the library. Screenshot captures the desktop; SeleniumLibrary and Browser capture browser content.

How do I capture a full page with Browser?

Use Take Screenshot fullPage=True. This scrolls and captures the full page rather than only the current viewport.

Where should screenshots go in CI?

Use an explicit directory that your CI artifact step collects. Avoid relying on a temporary default directory when the runner cleans output files.

Can I capture one HTML element?

Yes. SeleniumLibrary uses Capture Element Screenshot; Browser uses Take Screenshot with a selector. Selenium element support depends on the browser and driver.

Why is a desktop screenshot blank in headless CI?

Desktop capture needs a physical or virtual display. Configure one before running the suite, or use a browser-library capture when only page content is required.