GitLab CI template for Robot Framework¶

This project implements a GitLab CI/CD template to run your automated tests with Robot Framework.

Usage¶

This template can be used both as a CI/CD component or using the legacy include:project syntax.

Use as a CI/CD component¶

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the component
  - component: $CI_SERVER_FQDN/to-be-continuous/robotframework/gitlab-ci-robotframework@4.3.0
    # 2: set/override component inputs
    inputs:
      # ⚠ this is only an example
      tests-dir: "e2e"
      review-enabled: "true"

Use as a CI/CD template (legacy)¶

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the template
  - project: 'to-be-continuous/robotframework'
    ref: '4.3.0'
    file: '/templates/gitlab-ci-robotframework.yml'

variables:
  # 2: set/override template variables
  # ⚠ this is only an example
  ROBOT_TESTS_DIR: "e2e"
  REVIEW_ENABLED: "true"

Jobs¶

`robotframework-lint` job¶

This job performs a lint analysis on Robot Framework files, using robotframework-lint.

It is bound to the test stage, and uses the following variable:

Input / Variable	Description	Default value
`lint-disabled` / `ROBOT_LINT_DISABLED`	Set to `true` to disable linter	none

`robotframework` job¶

This job performs Robot Framework tests.

It is bound to the acceptance stage, and uses the following variable:

Input / Variable	Description	Default value
`base-image` / `ROBOT_BASE_IMAGE`	The Docker image used to run Robot Framework	`registry.hub.docker.com/ppodgorsek/robot-framework:latest`
`tests-dir` / `ROBOT_TESTS_DIR`	Robot Framework's tests directory	`robot`
`threads` / `ROBOT_THREADS`	Number of threads to execute Robot Framework's tests (uses Pabot if > `1`)	`1`
`screen-colour-depth` / `ROBOT_SCREEN_COLOUR_DEPTH`	Screen colour depth for X Window Virtual Framebuffer	`24`
`screen-height` / `ROBOT_SCREEN_HEIGHT`	Screen height for X Window Virtual Framebuffer	`1080`
`screen-width` / `ROBOT_SCREEN_WIDTH`	Screen width for X Window Virtual Framebuffer	`1920`
`browser` / `ROBOT_BROWSER`	Browser to use (one of `firefox` or `chrome`)	`firefox`
`options` / `ROBOT_OPTIONS`	Robot Framework additional options	none
`pabot-options` / `PABOT_OPTIONS`	Pabot additional options (if `ROBOT_THREADS` > `1`)	none
`review-enabled` / `REVIEW_ENABLED`	Set to `true` to enable Robot Framework tests on review environments (dynamic environments instantiated on development branches)	none (disabled)

Notes: * the Robot Framework project does not maintain an official Docker image. Use the default Docker image at your own risks. See the to-be-continuous documentation for more details. * the default Docker image used here runs as non-root user. Therefore it is not able - like most other templates - to manage custom certificate authorities (declared using either $CUSTOM_CA_CERTS or $DEFAULT_CA_CERTS). If you need it (need to call a server with SSL certificate issued by a non-official certificate authority), then you'll have to build your own Docker image that either embeds the required CA certificates, or that runs as root (thus the template will be able to install custom certificate authorities). * The template runs XVFB with -screen parameter $ROBOT_SCREEN_WIDTHx$ROBOT_SCREEN_HEIGHTx$ROBOT_SCREEN_COLOUR_DEPTH to run tests. * Depending on the ROBOT_THREADS value, the template runs either robot or pabot (if ROBOT_THREADS > 1). * Tests are run automatically on master and develop branches, and manually on others (may be overridden setting the REVIEW_ENABLED variable).

In addition to a textual report in the console, this job produces the following reports, kept for one day:

Report	Format	Usage
`reports/robotframework.xunit.xml`	xUnit test report(s)	GitLab integration

Robot Framework `{{ BASE_URL }}` auto evaluation¶

By default, the Robot Framework template tries to auto-evaluate the {{ BASE_URL }} variable (i.e. the variable pointing at server under test) by looking either for a $environment_url variable or for an environment_url.txt file.

Therefore if an upstream job in the pipeline deployed your code to a server and propagated the deployed server url, either through a dotenv variable $environment_url or through a basic environment_url.txt file, then the Robot Framework test will automatically be run on this server.

all our deployment templates implement this design. Therefore even purely dynamic environments (such as review environments) will automatically be propagated to your Robot Framework tests.

Hook scripts¶

The Robot Framework template supports optional hook scripts from your project, located in the $ROBOT_TESTS_DIR directory to perform additional project-specific logic:

pre-robot.sh is executed before running Robot Framework,
post-robot.sh is executed after running Robot Framework (whichever the tests status).

How to manage Robot Framework tests in a separate GitLab repository¶

This template can obviously be used in an application repository that also embeds the Robot Framework test scripts.

But you may also decide to manage your acceptance tests in a separate GitLab repository (for instance if people developing those tests have their own project cycle, separate from the application itself).

On the repository containing the Robot Framework tests, you should create a Docker image containing Robot Framework + your test scripts.

Dockerfile example:

FROM ppodgorsek/robot-framework:latest

LABEL name="My acceptance tests"
LABEL description="Robot Framework + tests in Docker"
LABEL url="https://gitlab.acme.host/my-project/rf-tests"
LABEL maintainer="john.dev@acme.com"

COPY robotframework/tests /opt/robotframework/tests

RUN pip3 install --no-cache-dir \
    <some robot framework library>

.gitlab-ci.yml example (build the Docker image using the Docker template):

include:
  # Include Docker template (to build the Docker image)
  - project: 'to-be-continuous/docker'
    ref: '<tag>'
    file: '/templates/gitlab-ci-docker.yml'
  # Include Robot Framework (to run robotframework-lint)
  - project: 'to-be-continuous/robotframework'
    ref: '4.3.0'
    file: '/templates/gitlab-ci-robotframework.yml'

And lastly in the repository containing the application to test, you'll have to use the Robot Framework template but override ROBOT_BASE_IMAGE with your own image built above.

include:
  # Include Robot Framework
  - project: 'to-be-continuous/robotframework'
    ref: '4.3.0'
    file: '/templates/gitlab-ci-robotframework.yml'

variables:
  # use my own Robot Framework image (with embedded tests)
  ROBOT_IMAGE: '$CI_REGISTRY/my-project/rf-tests:master'
  ROBOT_THREADS: 4
  # Important: override the tests directory
  ROBOT_TESTS_DIR: "/opt/robotframework/tests"

Variants¶

Vault variant¶

This variant allows delegating your secrets management to a Vault server.

Configuration¶

In order to be able to communicate with the Vault server, the variant requires the additional configuration parameters:

Input / Variable	Description	Default value
`TBC_VAULT_IMAGE`	The Vault Secrets Provider image to use (can be overridden)	`registry.gitlab.com/to-be-continuous/tools/vault-secrets-provider:latest`
`vault-base-url` / `VAULT_BASE_URL`	The Vault server base API url	none
`vault-oidc-aud` / `VAULT_OIDC_AUD`	The `aud` claim for the JWT	`$CI_SERVER_URL`
`VAULT_ROLE_ID`	The AppRole RoleID	must be defined
`VAULT_SECRET_ID`	The AppRole SecretID	must be defined

VAULT_ROLE_ID and VAULT_SECRET_ID can be replaced by VAULT_JWT_ROLE and VAULT_JWT_TOKEN. More informations can be found HERE

Usage¶

Then you may retrieve any of your secret(s) from Vault using the following syntax:

@url@http://vault-secrets-provider/api/secrets/{secret_path}?field={field}

With:

Parameter	Description
`secret_path` (path parameter)	this is your secret location in the Vault server
`field` (query parameter)	parameter to access a single basic field from the secret JSON payload

Example¶

include:
  # main template
  - component: $CI_SERVER_FQDN/to-be-continuous/robotframework/gitlab-ci-robotframework@4.3.0
  # Vault variant
  - component: $CI_SERVER_FQDN/to-be-continuous/robotframework/gitlab-ci-robotframework-vault@4.3.0
    inputs:
      # audience claim for JWT
      vault-oidc-aud: "https://vault.acme.host"
      vault-base-url: "https://vault.acme.host/v1"
      # $VAULT_ROLE_ID and $VAULT_SECRET_ID defined as a secret CI/CD variable

variables:
  ### Secrets managed by Vault
  MY_APPLICATION_PASS: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/my-app/robot/noprod?field=application_password"

GitLab CI template for Robot Framework¶

Usage¶

Use as a CI/CD component¶

Use as a CI/CD template (legacy)¶

Jobs¶

robotframework-lint job¶

robotframework job¶

Robot Framework {{ BASE_URL }} auto evaluation¶

Hook scripts¶

How to manage Robot Framework tests in a separate GitLab repository¶

Variants¶

Vault variant¶

Configuration¶

Usage¶

Example¶

`robotframework-lint` job¶

`robotframework` job¶

Robot Framework `{{ BASE_URL }}` auto evaluation¶