Metadata-Version: 2.4
Name: robotframework-testcontainers
Version: 0.3.0
Summary: Robot Framework keywords for Testcontainers.
Keywords: robotframework,testing,test,automation,container,testcontainers,docker
Author: Andreas Finkler
Author-email: Andreas Finkler <andi.finkler@gmail.com>
License-Expression: MIT
Classifier: Framework :: Robot Framework
Classifier: Framework :: Robot Framework :: Library
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Testing :: Mocking
Requires-Dist: robotframework>=7.3.2
Requires-Dist: robotframework-assertion-engine>=5.0.1
Requires-Dist: testcontainers[generic]>=4.15.0
Requires-Python: >=3.10
Project-URL: Repository, https://github.com/DudeNr33/robotframework-testcontainers
Project-URL: Documentation, https://dudenr33.github.io/robotframework-testcontainers/
Description-Content-Type: text/markdown

# robotframework-testcontainers

Robot Framework keywords for [testcontainers](https://github.com/testcontainers/testcontainers-python).

[Keyword Documentation](https://dudenr33.github.io/robotframework-testcontainers/)

## Installation

- using `pip`:

```shell
pip install robotframework-testcontainers
```

- using `uv`:

```shell
uv add robotframework-testcontainers
```

- using `poetry`:

```shell
poetry add robotframework-testcontainers
```

## Usage

Starting a container can be done with a single keyword:

```robot
*** 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:

```robot
*** 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.

```robot
*** 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`:

```shell
robot \
  --listener TestcontainersLibrary.FailedTestLogCollector \
  tests/
```

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

```shell
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:

```text
<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](LICENSE).

### Third-Party Licenses

This library depends on the
[`testcontainers-python`](https://github.com/testcontainers/testcontainers-python)
package, which is licensed under the
[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).

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