Skip to content

GitLab CI template for Robot Framework

Overview

This project implements a generic GitLab CI template for Robot Framework.

Usage

In order to include this template in your project, add the following to your gitlab-ci.yml:

include:
  - project: 'to-be-continuous/robotframework'
    ref: '2.0.1'
    file: '/templates/gitlab-ci-robotframework.yml'

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:

Name description default value
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:

Name description default value
ROBOT_BASE_IMAGE The Docker image used to run Robot Framework ppodgorsek/robot-framework:latest
ROBOT_TESTS_DIR Robot Framework's tests directory robot
ROBOT_THREADS Number of threads to execute Robot Framework's tests (uses Pabot if > 1) 1
ROBOT_SCREEN_COLOUR_DEPTH Screen colour depth for X Window Virtual Framebuffer 24
ROBOT_SCREEN_HEIGHT Screen height for X Window Virtual Framebuffer 1080
ROBOT_SCREEN_WIDTH Screen width for X Window Virtual Framebuffer 1920
ROBOT_BROWSER Browser to use (one of firefox or chrome) firefox
ROBOT_OPTIONS Robot Framework additional options none
PABOT_OPTIONS Pabot additional options (if ROBOT_THREADS > 1) none
ACCEPTANCE_ALWAYS Force to execute the test after each commit (even on development branches) false
REVIEW_ENABLED Set to true to enable Robot Framework tests on review environments (dynamic environments instantiated on development branches) none (disabled)

Notes:

  • ⚠ī¸ 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).

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.

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: '2.0.1'
    file: '/templates/gitlab-ci-robotframework.yml'

stages:
  - build
  - test
  - package-build
  - package-test
  - acceptance
  - publish

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: '2.0.1'
    file: '/templates/gitlab-ci-robotframework.yml'

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

stages:
  - build
  - test
  - deploy
  - acceptance
  - publish
  - production

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:

Name description default value
VAULT_BASE_URL The Vault server base API url none
🔒 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:

Name 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
  - project: 'to-be-continuous/robotframework'
    ref: '2.0.1'
    file: '/templates/gitlab-ci-robotframework.yml'
  # Vault variant
  - project: 'to-be-continuous/robotframework'
    ref: '2.0.1'
    file: '/templates/gitlab-ci-robotframework-vault.yml'

variables:
    ### variables have to be explicitly declared in the YAML to be exported to the service.
    VAULT_ROLE_ID: ${VAULT_ROLE_ID}
    VAULT_SECRET_ID: ${VAULT_SECRET_ID}
    # $VAULT_ROLE_ID and $VAULT_SECRET_ID defined as a secret CI/CD variable

    ### /!\ don't define VAULT_ROLE_ID and VAULT_SECRET_ID if you want to use gitlab JWT
    # VAULT_JWT_TOKEN: "$CI_JOB_JWT"
    # VAULT_JWT_ROLE: "my_gitlab_role"

    ### Secrets managed by Vault
    MY_APPLICATION_PASS: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/my-app/robot/noprod?field=application_password"
    VAULT_BASE_URL: "https://vault.acme.host/v1"

Gitlab compatibility

ℹī¸ This template is actually tested and validated on GitLab Community Edition instance version 13.12.11