robotframework-testcontainers

Robot Framework keywords for testcontainers.

Keyword Documentation

Installation

• using pip:

pip install robotframework-testcontainers

• using uv:

uv add robotframework-testcontainers

• using poetry:

poetry add robotframework-testcontainers

Usage

Starting a container can be done with a single keyword:

*** Settings ***
Library    TestcontainersLibrary

*** Test Cases ***
Basic Usage Example
    Create Docker Container    image=hello-world

TestcontainersLibrary keeps track of all started containers. It stops containers started during a test when that test ends, and containers started during suite initialization or suite setup when that suite ends.

If you require more control, you can also manually start and stop the container. Additionally, you can use different wait strategies to wait for the container to be ready:

*** Settings ***
Library    TestcontainersLibrary

*** Test Cases ***
Advanced Usage with more control
    ${container}=    Create Docker Container    image=traefik/whoami    start=False    ports=[80]
    Start Container    ${container}
    Wait For Http Endpoint    ${container}    port=80    path=/api
    Stop Container    ${container}

You can also use any of the community maintained containers. Be aware that you have to make sure to install the required dependencies yourself.
For example: starting a CockroachDB container requires installing testcontainers[cockroachdb]. Use the Create Community Container keyword and specify which class to import from which module. Any additional arguments can be passed in as keyword arguments.

*** Settings ***
Library             TestcontainersLibrary


*** Test Cases ***
Starting an CockroachDb Container
    ${password}=    Evaluate    str(uuid.uuid4())
    ${container}=    Create Community Container
    ...    module=testcontainers.cockroachdb
    ...    container_class=CockroachDBContainer
    ...    username=demoUser
    ...    password=${password}
    Log    ${container.get_connection_url()}

You can read the acceptance tests in test/acceptance/ for more concrete usage examples.

Failed-test log artifacts

Register the failed-test log collector on the Robot command line to retain stdout and stderr for every active container started through the library. The listener covers every test in the execution, including child suites that do not import TestcontainersLibrary:

robot \
  --listener TestcontainersLibrary.FailedTestLogCollector \
  tests/

By default, artifacts go to ${OUTPUT_DIR}/container-logs. Pass a different root after the listener name when needed:

robot \
  --listener TestcontainersLibrary.FailedTestLogCollector:/tmp/container-logs \
  tests/

The listener uses absolute custom paths as written. It resolves relative custom paths from the process working directory, not Robot's output directory.

The log window extends one second before and after the failed test to account for Docker log timing. Each Robot run gets one timestamped directory. Beneath it, the listener preserves the logical suite hierarchy:

<artifact-root>/<timestamp>/<suite>/<child-suite>/<test>/<container files>

Unsafe path characters and whitespace become underscores. Each container gets separate stdout and stderr files. When collection writes at least one log or error file, log.html includes one INFO message with the absolute path to that test's artifact directory. Collection errors do not change the Robot test result.

The files contain raw container logs and may include passwords, tokens, or other secrets. Choose an artifact directory with suitable access and retention controls.

License

This project is licensed under the MIT License.

Third-Party Licenses

This library depends on the testcontainers-python package, which is licensed under the Apache License 2.0.

No parts of testcontainers-python are copied or modified in this project. It is used only as a dependency.