Skip to content

Commit

Permalink
Merge pull request #475 from ppodgorsek/issue-474
Browse files Browse the repository at this point in the history 
Issue #474 - README TOC links don't work on the Docker Hub
  • Loading branch information
@ppodgorsek
ppodgorsek committed Feb 7, 2024
2 parents 0f78b7d + 983728e commit 40daee8
Showing 1 changed file with 48 additions and 0 deletions.
48 changes: 48 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,12 +29,16 @@

-----

<a name="what-is-it"></a>

## What is it?

This project consists of a Docker image containing a Robot Framework installation.

This installation also contains Firefox, Chrome, Microsoft Edge and the Selenium library for Robot Framework. The test cases and reports should be mounted as volumes.

<a name="versioning"></a>

## Versioning

The versioning of this image follows the one of Robot Framework:
Expand Down Expand Up @@ -64,6 +68,8 @@ The versions used are:

As stated by [the official GitHub project](https://github.com/robotframework/Selenium2Library), starting from version 3.0, Selenium2Library is renamed to SeleniumLibrary and this project exists mainly to help with transitioning. The Selenium2Library 3.0.0 is also the last release and for new releases, please look at the [SeleniumLibrary](https://github.com/robotframework/SeleniumLibrary) project.

<a name="running-the-container"></a>

## Running the container

This container can be run using the following command:
Expand All @@ -73,6 +79,8 @@ This container can be run using the following command:
-v <local path to the test suites' folder>:/opt/robotframework/tests:Z \
ppodgorsek/robot-framework:<version>

<a name="switching-browsers"></a>

### Switching browsers

Browsers can be easily switched. It is recommended to define `${BROWSER} %{BROWSER}` in your Robot variables and to use `${BROWSER}` in your test cases. This allows to set the browser in a single place if needed.
Expand All @@ -81,6 +89,8 @@ When running your tests, simply add `-e BROWSER=chrome`, `-e BROWSER=firefox` or

Please note: `edge` will work with Selenium but not the Browser Library, as the latter currently doesn't have an easy mechanism to install additional browsers. Playwright, on which the Browser library relies, cannot install additional browsers on Linux platforms other than Ubuntu/Debian and [suggests using Chromium to test Microsoft Edge scenarios](https://playwright.dev/docs/browsers), unless you require Edge-specific capabilities.

<a name="changing-the-containers-screen-resolution"></a>

### Changing the container's screen resolution

It is possible to define the settings of the virtual screen in which the browser is run by changing several environment variables:
Expand All @@ -89,13 +99,17 @@ It is possible to define the settings of the virtual screen in which the browser
* `SCREEN_HEIGHT` (default: 1080)
* `SCREEN_WIDTH` (default: 1920)

<a name="changing-the-containers-tests-and-reports-directories"></a>

### Changing the container's tests and reports directories

It is possible to use different directories to read tests from and to generate reports to. This is useful when using a complex test file structure. To change the defaults, set the following environment variables:

* `ROBOT_REPORTS_DIR` (default: /opt/robotframework/reports)
* `ROBOT_TESTS_DIR` (default: /opt/robotframework/tests)

<a name="parallelisation"></a>

### Parallelisation

It is possible to parallelise the execution of your test suites. Simply define the `ROBOT_THREADS` environment variable, for example:
Expand All @@ -106,6 +120,8 @@ It is possible to parallelise the execution of your test suites. Simply define t

By default, there is no parallelisation.

<a name="parallelisation-options"></a>

#### Parallelisation options

When using parallelisation, it is possible to pass additional [pabot options](https://github.com/mkorpela/pabot#command-line-options), such as `--testlevelsplit`, `--argumentfile`, `--ordering`, etc. These can be passed by using the `PABOT_OPTIONS` environment variable, for example:
Expand All @@ -115,6 +131,8 @@ When using parallelisation, it is possible to pass additional [pabot options](ht
-e PABOT_OPTIONS="--testlevelsplit" \
ppodgorsek/robot-framework:latest

<a name="passing-additional-options"></a>

### Passing additional options

RobotFramework supports many options such as `--exclude`, `--variable`, `--loglevel`, etc. These can be passed by using the `ROBOT_OPTIONS` environment variable, for example:
Expand All @@ -123,12 +141,16 @@ RobotFramework supports many options such as `--exclude`, `--variable`, `--logle
-e ROBOT_OPTIONS="--loglevel DEBUG" \
ppodgorsek/robot-framework:latest

<a name="testing-emails"></a>

### Testing emails

This project includes the IMAP library which allows Robot Framework to connect to email servers.

A suggestion to automate email testing is to run a [Mailcatcher instance in Docker which allows IMAP connections](https://github.com/estelora/docker-mailcatcher-imap). This will ensure emails are discarded once the tests have been run.

<a name="dealing-with-datetimes-and-timezones"></a>

### Dealing with Datetimes and Timezones

This project is meant to allow your tests to run anywhere. Sometimes that can be in a different timezone than your local one or of the location under test. To help solve such issues, this image includes the [DateTimeTZ Library](https://testautomation.github.io/DateTimeTZ/doc/DateTimeTZ.html).
Expand All @@ -139,6 +161,8 @@ To set the timezone used inside the Docker image, you can set the `TZ` environme
-e TZ=America/New_York \
ppodgorsek/robot-framework:latest

<a name="installing-additional-dependencies"></a>

### Installing additional dependencies

It is possible to install additional dependencies dynamically at runtime rather than having to extend this image.
Expand All @@ -161,6 +185,8 @@ rpa==1.50.0

**For large dependencies, it is still recommended to extend the project's image and to add them there, to avoid delaying the CI/CD pipelines with repeated dependency installations.**

<a name="security-considerations"></a>

## Security consideration

By default, containers are implicitly run using `--user=1000:1000`, please remember to adjust that command-line setting accordingly, for example:
Expand All @@ -178,6 +204,8 @@ Additionally, it is possible to rely on user namespaces to further secure the ex

This is a good security practice to make sure containers cannot perform unwanted changes on the host. In that sense, Podman is probably well ahead of Docker by not relying on a root daemon to run its containers.

<a name="continuous-integration"></a>

## Continuous integration

It is possible to run the project from within a Jenkins pipeline by relying on the shell command line directly:
Expand Down Expand Up @@ -217,6 +245,8 @@ The pipeline stage can also rely on a Docker agent, as shown in the example belo
}
}

<a name="defining-a-test-run-id"></a>

### Defining a test run ID

When relying on Continuous Integration tools, it can be useful to define a test run ID such as the build number or branch name to avoid overwriting consecutive execution reports.
Expand All @@ -233,6 +263,8 @@ It can simply be passed during the execution, such as:

By default, the test run ID is empty.

<a name="upload-test-reports-to-an-aws-s3-bucket"></a>

### Upload test reports to an AWS S3 bucket

To upload the report of a test run to an S3 bucket, you need to define the following environment variables:
Expand All @@ -244,6 +276,8 @@ To upload the report of a test run to an S3 bucket, you need to define the follo
-e AWS_BUCKET_NAME=<name of your S3 bucket> \
ppodgorsek/robot-framework:latest

<a name="testing-this-project"></a>

## Testing this project

Not convinced yet? Simple tests have been prepared in the `test/` folder, you can run them using the following commands:
Expand Down Expand Up @@ -280,8 +314,12 @@ For Windows users who use **PowerShell**, the commands are slightly different:

Screenshots of the results will be available in the `reports/` folder.

<a name="troubleshooting"></a>

## Troubleshooting

<a name="chromium-is-crashing"></a>

### Chromium is crashing

Chrome drivers might crash due to the small size of `/dev/shm` in the docker container:
Expand All @@ -291,6 +329,8 @@ This is [a known bug of Chromium](https://bugs.chromium.org/p/chromium/issues/de

To avoid this error, please change the shm size when starting the container by adding the following parameter: `--shm-size=1g` (or any other size more suited to your tests)

<a name="accessing-the-logs"></a>

### Accessing the logs

In case further investigation is required, the logs can be accessed by mounting their folder. Simply add the following parameter to your `run` command:
Expand All @@ -303,6 +343,8 @@ Chromium allows to set additional environment properties, which can be useful wh
* `webdriver.chrome.verboseLogging=true`: enables the verbose logging mode
* `webdriver.chrome.logfile=/path/to/chromedriver.log`: sets the path to Chromium's log file

<a name="error-suite-contains-no-tests"></a>

### Error: Suite contains no tests

When running tests, an unexpected error sometimes occurs:
Expand All @@ -321,6 +363,8 @@ It is also important to check if Robot Framework is allowed to access the resour
* The folder where the tests are located,
* The test files themselves.

<a name="database-tests-are-failing-in-spite-of-the-databaselibrary-being-present"></a>

### Database tests are failing in spite of the DatabaseLibrary being present

As per their official project page, the [Robot Framework DatabaseLibrary](https://github.com/franz-see/Robotframework-Database-Library) contains utilities meant for Robot Framework's usage. This can allow you to query your database after an action has been made to verify the results. This is compatible with any Database API Specification 2.0 module.
Expand All @@ -331,6 +375,8 @@ It is anyway mandatory to extend the container image to install the specific dat
* [Oracle](https://www.oracle.com/uk/database/technologies/appdev/python.html): `pip install py2oracle`
* [PostgreSQL](http://pybrary.net/pg8000/index.html): `pip install pg8000`

<a name="supported-devices-and-architectures"></a>

### Supported devices and architectures

As mentioned on the [Docker Hub](https://hub.docker.com/r/ppodgorsek/robot-framework), the project has been built and uploaded as a `linux/amd64` image only. This means ARM devices such as MacBook M1/M2 and Amazon EC2 Graviton won't be able to run the image with the default configuration.
Expand All @@ -347,6 +393,8 @@ Please note: builds and automated tests of this project will remain performed on

If this does not solve your platform-related issues, you will have to rebuild the image for your device/platform, specifying that `--platform` option during the build and run.

<a name="please-contribute"></a>

## Please contribute!

Have you found an issue? Do you have an idea for an improvement? Feel free to contribute by submitting it [on the GitHub project](https://github.com/ppodgorsek/docker-robot-framework/issues).

0 comments on commit 40daee8

Please sign in to comment.