ScreenshotNeo

BlogHow-to

How to Name Robot Framework Failure Screenshots After Test Cases

Name Robot Framework failure screenshots after their test cases with `${TEST NAME}`, unique indexes, safe paths, and reliable CI artifact storage.

By the ScreenshotNeo team30 September 20269 min read

How to Name Robot Framework Failure Screenshots After Test Cases

Use Robot Framework’s built-in ${TEST NAME} variable when you call Capture Page Screenshot. A practical SeleniumLibrary filename is ${TEST NAME}_FAILURE_{index}.png. The test name identifies the case, _FAILURE makes the artifact easy to find, and {index} prevents later captures from overwriting earlier ones.

This pattern works in a test teardown, where one screenshot is captured after a failed test, or in a run-on-failure hook, where screenshots can be captured after failed keywords. SeleniumLibrary expands {index} to a running number beginning at 1 and also supports formatting such as {index:03}. See the SeleniumLibrary keyword documentation.

A teardown is the clearest default when you want one final browser image per failed test case:

*** Settings ***
Library    SeleniumLibrary
Test Teardown    Capture Failure Screenshot

*** Keywords ***
Capture Failure Screenshot
    Run Keyword If Test Failed    Capture Page Screenshot    ${TEST NAME}_FAILURE_{index}.png

*** Test Cases ***
Checkout rejects an expired card
    Open Browser    https://example.test/checkout    chrome
    Input Text    id=card-number    4000000000000002
    Click Button    id=pay
    Page Should Contain    Payment failed
    [Teardown]    Close All Browsers

If the test fails, the screenshot filename will contain the test case name, the failure marker, and a unique number. For example, a case named Checkout rejects an expired card can produce Checkout rejects an expired card_FAILURE_1.png.

The keyword returns the absolute path of the created file. That makes it possible to log the path, copy the file to another artifact directory, or pass it to a reporting step. If no screenshot directory is configured, SeleniumLibrary saves the file where the Robot Framework log is written.

Choose the capture trigger

Test teardown: one final failure image

Use a test teardown when the useful state is the final state of the test. It keeps artifact volume predictable and captures only failed tests when combined with Run Keyword If Test Failed.

A failure teardown turns the active test name into a searchable, unique screenshot artifact.
A failure teardown turns the active test name into a searchable, unique screenshot artifact.
*** Settings ***
Library    SeleniumLibrary
Test Teardown    Capture Failure Screenshot

*** Keywords ***
Capture Failure Screenshot
    Run Keyword If Test Failed    Capture Page Screenshot    ${TEST NAME}_FAILURE_{index:03}.png

The formatted index gives names such as _001 and _002, which sort correctly in file listings.

Run-on-failure: capture after a failed keyword

SeleniumLibrary uses Capture Page Screenshot as its default run-on-failure keyword. You can configure another keyword when importing the library:

*** Settings ***
Library    SeleniumLibrary    run_on_failure=Capture Page Screenshot

This mode is useful when the failure occurs before the test reaches its teardown, or when you need the browser state immediately after the failing SeleniumLibrary keyword. It can create several images during one test, so include {index} in any custom naming scheme.

To include the test name in every automatic capture, create a wrapper keyword and register it:

*** Settings ***
Library    SeleniumLibrary

Suite Setup    Configure Failure Capture

*** Keywords ***
Configure Failure Capture
    Register Keyword To Run On Failure    Capture Named Failure Screenshot

Capture Named Failure Screenshot
    Capture Page Screenshot    ${TEST NAME}_FAILURE_{index}.png

The wrapper computes the filename at capture time, when ${TEST NAME} identifies the active test. Keep this wrapper small: a failure hook that raises another error can hide the original problem.

Make filenames safe for every filesystem

Robot test names are written for people, while filenames must work on the operating system and in CI artifact stores. Spaces are normally acceptable, but slashes, colons, backslashes, wildcard characters, and control characters can cause errors or create unintended directories. The SeleniumLibrary documentation defines filename and index handling but does not prescribe one universal sanitization algorithm.

Choose a teardown for one final image or a run-on-failure hook for evidence after each failed keyword.
Choose a teardown for one final image or a run-on-failure hook for evidence after each failed keyword.

Pick one policy and apply it consistently. Common choices are:

  • Replace path separators and punctuation with underscores.
  • Collapse repeated whitespace into one underscore.
  • Limit the final name to a fixed length.
  • Preserve a short stable identifier if two tests become identical after sanitization.

For example, a test called Profile / deletes account: confirmation could become Profile_deletes_account_confirmation_FAILURE_001.png. If you sanitize names in a pre-processing step, make sure the same mapping is used in the report links so developers can find the file.

Prevent overwrites and parallel-run collisions

A plain ${TEST NAME}.png is deterministic, but it is unsafe when a test can capture more than once, retry after failure, or run in parallel. Add {index} whenever repeated captures are possible. SeleniumLibrary starts the index at 1 for the captures it creates.

Parallel workers can still write the same filename if they share a directory and each worker starts its own index at 1. Give each worker a separate output directory, or add a worker identifier to the directory path:

*** Settings ***
Library    SeleniumLibrary    screenshot_directory=${OUTPUT DIR}${/}screenshots${/}${WORKER_ID}
Test Teardown    Capture Failure Screenshot

The exact worker variable depends on the parallel runner. If your runner does not expose one, configure separate output directories at the process level. Do not rely on timestamps alone: clocks can have low resolution, and identical names are easier to search in CI.

Configure screenshot storage

By default, SeleniumLibrary follows the Robot Framework log location. That is convenient locally because screenshots sit beside log.html, but CI systems often collect only a dedicated artifact directory. Configure that directory when importing the library or pass an explicit path to the screenshot keyword.

*** Settings ***
Library    SeleniumLibrary    screenshot_directory=${OUTPUT DIR}${/}failure-screenshots

Robot Framework’s built-in Screenshot library also defaults to the log directory and supports an explicit location through screenshot_directory or Set Screenshot Directory. Its behavior is separate from SeleniumLibrary, so check which library owns the screenshot keyword in your suite. See the Robot Framework Screenshot library documentation.

Robot Framework Browser alternative

If your suite uses Robot Framework Browser rather than SeleniumLibrary, the documented failure filename convention is ${TEST NAME}_FAILURE_SCREENSHOT_{index}. Register Take Screenshot as the run-on-failure keyword and provide a custom prefix when needed. The same naming decisions apply: use the test name for identity, a failure marker for filtering, and an index for uniqueness. See the Browser library screenshot keyword reference.

Complete patterns for common projects

One screenshot after each failed test

*** Settings ***
Library    SeleniumLibrary    screenshot_directory=${OUTPUT DIR}${/}screenshots
Test Teardown    Capture Failure Screenshot

*** Keywords ***
Capture Failure Screenshot
    Run Keyword If Test Failed    Capture Page Screenshot    ${TEST NAME}_FAILURE_{index:03}.png

Capture every failed keyword

*** Settings ***
Library    SeleniumLibrary    run_on_failure=Capture Page Screenshot

*** Test Cases ***
Search shows results
    Open Browser    https://example.test/search    chrome
    Input Text    id=query    robot framework
    Click Button    id=search
    Page Should Contain    Results

Keep teardown cleanup separate

*** Settings ***
Library    SeleniumLibrary
Test Teardown    Run Keywords    Capture Failure Screenshot    AND    Close All Browsers

*** Keywords ***
Capture Failure Screenshot
    Run Keyword If Test Failed    Capture Page Screenshot    ${TEST NAME}_FAILURE_{index}.png

Capture before closing the browser. Once the browser is closed, SeleniumLibrary cannot capture the page that failed.

Troubleshooting

Symptom Cause Fix
The filename is always the same The filename omits {index}, or each parallel worker uses one shared path. Add {index} and isolate worker output directories.
No screenshot appears The teardown is not running, the test passed, or the browser was already closed. Confirm the test failed, place capture before browser cleanup, and inspect the Robot log directory.
The name contains an invalid path The test name includes slashes, colons, or other OS-specific characters. Sanitize the test name before constructing the filename.
Several screenshots are created unexpectedly Run-on-failure captures after every failed keyword. Use a test teardown for one final image, or keep the hook and expect indexed files.
The screenshot is blank The failure happened before navigation completed, or the browser page was replaced. Capture with run-on-failure to preserve the earlier state and add explicit waits for the page you need.
The report links break in CI Files were saved outside the collected artifact directory. Set a dedicated screenshot directory under the CI output path and publish it with the Robot report.
The original error is obscured The failure hook itself failed, often because the browser session is gone. Keep the hook defensive and ensure cleanup runs after the capture step.

Performance, reliability, and cost considerations

A screenshot adds browser rendering and image encoding work to the failure path. Test failures are less frequent than ordinary steps, so one teardown image usually has negligible suite impact. Capturing after every failed keyword can produce many files and slow cleanup, artifact upload, and report rendering. Use test teardown for routine CI runs and run-on-failure when diagnosing intermittent failures.

Use PNG when text and sharp edges matter. Use JPEG or WebP only when your reporting system supports them and smaller artifacts are more valuable. Keep the browser viewport consistent so visual comparisons are meaningful. Full-page images can be large; capture the relevant element when the failure is localized.

For reliable artifact retention, create the output directory before the run, publish it even when tests fail, and keep the Robot log and screenshots under the same run identifier. When retries are enabled, retain each indexed image instead of allowing the retry to replace the first failure.

Or skip the browser setup

If you need screenshots of pages outside a Robot test, or want a separate capture service for reports, ScreenshotNeo returns an image or PDF from one GET request. The API accepts the URL and supports PNG, JPEG, and WebP output. Its clean-shot flow accepts cookie and consent banners before capture, then removes more than 60 known consent platforms, newsletter popups, and chat widgets. Each step can be turned off.

Only clean shots are billed. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the result with X-Page-Verdict and X-Billed headers. ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.

See the ScreenshotNeo API documentation for authentication and options.

cURL

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

Python

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)

Node.js

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

ScreenshotNeo includes full-page capture with lazy images loaded, CSS-selector element capture, dark mode, 12 device presets, custom viewports, retina scale, custom CSS and JavaScript, clicks, selector or network-idle waits, blocked ads and trackers, custom headers and cookies, user agent and Authorization headers, timezone and geolocation, transparent backgrounds, resizing, selectable cache TTLs, signed links, asynchronous jobs with signed webhooks, bulk capture for up to 100 URLs per call, a usage API, and an OpenAPI specification. Parameter names used by other screenshot APIs also work to make migration easier.

The Free plan includes 1,000 shots each month with no card. Paid plans start at $5 for 3,000 shots; yearly billing gives two months free. Create a free ScreenshotNeo account and start with the monthly free allowance.

FAQ

What variable contains the current Robot test name?

Use the built-in ${TEST NAME} variable. It is the natural identity component for a failure screenshot filename.

What does {index} do?

SeleniumLibrary expands it to a unique running number beginning at 1. Use {index:03} for zero-padded values such as 001.

Should I use teardown or run-on-failure?

Use teardown for one final image per failed test. Use run-on-failure when the failing keyword’s immediate browser state is the important evidence.

Where are screenshots saved by default?

SeleniumLibrary saves them where the Robot Framework log is written unless you configure a screenshot directory. Robot Framework’s Screenshot library follows the same log-directory default and has its own directory settings.

Why should I sanitize test names?

Names can contain characters that are separators or invalid on a target filesystem. A consistent replacement policy keeps filenames portable and CI artifact links predictable.