Robot Framework RetryFailed Listener

Warnings

• gotcha The listener is triggered via command-line arguments to `robot`, not by importing a class in a Python file. Ensure the listener name `RetryFailed` is correctly spelled and followed by a colon for arguments (e.g., `RetryFailed:2`).
  Fix: Always use `robot --listener RetryFailed` or `robot --listener RetryFailed:<args>`.
• gotcha Users often confuse this listener with Robot Framework's built-in `Wait Until Keyword Succeeds` keyword (for individual keywords) or the `--rerunfailed` command-line option (for re-executing failed tests from a previous run). `robotframework-retryfailed` offers in-place retries for entire tests or tasks during a single execution run.
  Fix: Understand the scope: `robotframework-retryfailed` for in-place test/task retries, `Wait Until Keyword Succeeds` for keyword retries, `--rerunfailed` for re-running a subset of tests from a previous `output.xml`.
• gotcha There are open issues regarding potential conflicts with Robot Framework's `exitonfailure` option, which might cause unexpected behavior when combined with `robotframework-retryfailed`.
  Fix: Review GitHub issues for updates and consider testing thoroughly if `exitonfailure` is used alongside `robotframework-retryfailed`.
• gotcha An open issue on GitHub reports that the listener might not retry 'Setup' sections (Suite Setup or Test Setup), only the test body itself. Also, issues exist where the first test case in a file might run twice, even if it passes.
  Fix: Be aware that setup failures might not trigger retries. Test any 'Setup' retry expectations. Monitor GitHub issues for fixes or workarounds regarding unintended double execution.
• breaking The project's GitHub repository currently shows no explicit 'Releases' section, despite the package being available on PyPI. This can make tracking structured release notes or breaking changes between versions difficult.
  Fix: Refer to the GitHub `CHANGELOG.md` (if available) or the issue tracker for significant changes, and test new versions thoroughly.

Install

• pip install robotframework-retryfailed Install with pip

Imports

• RetryFailed

  robot --listener RetryFailed <your_suite.robot>

  The library is used as a listener directly via the Robot Framework command line, not typically imported into Python code for direct instantiation.
• RetryFailed with arguments

  robot --listener RetryFailed:1 <your_suite.robot>

  The listener accepts arguments directly after a colon, e.g., to set a global retry count or configuration options.

Quickstart

This quickstart demonstrates how to use the `robotframework-retryfailed` listener. It creates a simple Robot Framework file with a test case tagged for retries. The test is configured to fail, triggering the listener to retry it. Execute the generated `robot` command to see the retries in action.

import os

# Create a dummy Robot Framework test file
robot_file_content = '''
*** Settings ***
Library    OperatingSystem

*** Test Cases ***
Example Failing Test
    [Tags]    test:retry(2)
    Fail If    True    This test is designed to fail and retry
'''.strip()

with open('my_tests.robot', 'w') as f:
    f.write(robot_file_content)

# Run Robot Framework with the RetryFailed listener
# For demonstration, we'll just print the command
# In a real scenario, you'd run this via subprocess or directly in your shell
robot_command = f"robot --listener RetryFailed:2 my_tests.robot"
print(f"To run the example, execute:\n{robot_command}")
# Expected outcome: The test 'Example Failing Test' will fail, be retried twice, and ultimately still fail if 'Fail If True' is never satisfied.
# The final report will show retries occurred.