Robot Framework Docker镜像（含Firefox、Chrome和Microsoft Edge）

目录

• 概述
• 版本控制
• 运行容器
  • 切换浏览器
  • 修改容器屏幕分辨率
  • 修改容器的测试和报告目录
  • 并行化
    • 并行化选项
  • 传递额外选项
  • 测试电子邮件
  • 处理日期时间和时区
  • 安装额外依赖
  • 重跑失败测试
• 安全考虑
• 持续集成
  • Azure DevOps流水线
  • Jenkins流水线
  • 定义测试运行ID
  • 上传测试报告到AWS S3桶
• 测试本项目
• 故障排除
  • Chromium崩溃
  • 访问日志
  • 错误：套件不包含测试用例
  • 尽管已安装DatabaseLibrary，数据库测试仍失败
  • 支持的设备和架构
• 贡献指南

概述

此项目包含一个安装了Robot Framework的容器镜像。该镜像还包含Firefox、Chrome、Microsoft Edge浏览器，以及Robot Framework的Selenium和Playwright/RFBrowser库。

版本控制

本镜像的版本控制遵循Robot Framework的版本规范：

• 主版本号与Robot Framework一致
• 次版本号和补丁版本号特定于本项目（用于更新其他依赖项版本）

使用的组件版本如下：

• Robot Framework 7.3.2
• Robot Framework 浏览器（Playwright）库 19.7.0
• Robot Framework DatabaseLibrary 2.1.4
• Robot Framework Datadriver 1.11.2
• Robot Framework DateTimeTZ 1.0.6
• Robot Framework Faker 6.0.0
• Robot Framework FTPLibrary 1.9
• Robot Framework IMAPLibrary 2 0.4.11
• Robot Framework Pabot 5.0.0
• Robot Framework Requests 0.9.7
• Robot Framework SeleniumLibrary 6.7.1
• Robot Framework SSHLibrary 3.8.0
• Axe Selenium Library 2.1.6
• Firefox 141.0
• Chrome for Testing 139.0
• Microsoft Edge 139.0
• Amazon AWS CLI 1.42.11

根据Selenium2Library官方GitHub项目说明，从3.0版本开始，Selenium2Library已重命名为SeleniumLibrary，该项目主要用于帮助过渡。Selenium2Library 3.0.0是最后一个版本，新版本请关注SeleniumLibrary项目。

运行容器

可使用以下命令运行容器：

docker run \
    -v <本地报告文件夹路径>:/opt/robotframework/reports:Z \
    -v <本地测试套件文件夹路径>:/opt/robotframework/tests:Z \
    ppodgorsek/robot-framework:<版本>

切换浏览器

浏览器可轻松切换。建议在Robot变量中定义${BROWSER} %{BROWSER}，并在测试用例中使用${BROWSER}。这样如需更改浏览器，只需在一个地方设置。

运行测试时，只需在命令中添加-e BROWSER=chrome、-e BROWSER=firefox或-e BROWSER=edge。

注意：edge可与Selenium配合使用，但不适用于Browser Library，因为后者目前没有简单的机制安装额外浏览器。Browser库依赖的Playwright在非Ubuntu/Debian的Linux平台上无法安装额外浏览器，建议使用Chromium测试Microsoft Edge场景，除非需要Edge特定功能。

修改容器屏幕分辨率

可通过修改以下环境变量定义浏览器运行的虚拟屏幕设置：

• SCREEN_COLOUR_DEPTH（默认：24）
• SCREEN_HEIGHT（默认：1080）
• SCREEN_WIDTH（默认：1920）

修改容器的测试和报告目录

可使用不同目录读取测试和生成报告，这在复杂测试文件结构时很有用。要修改默认目录，设置以下环境变量：

• ROBOT_REPORTS_DIR（默认：/opt/robotframework/reports）
• ROBOT_TESTS_DIR（默认：/opt/robotframework/tests）

并行化

可并行执行测试套件。只需定义ROBOT_THREADS环境变量，例如：

docker run \
    -e ROBOT_THREADS=4 \
    ppodgorsek/robot-framework:latest

默认情况下不启用并行化。

并行化选项

使用并行化时，可传递额外的pabot选项，如--testlevelsplit、--argumentfile、--ordering等。可通过PABOT_OPTIONS环境变量传递，例如：

docker run \
    -e ROBOT_THREADS=4 \
    -e PABOT_OPTIONS="--testlevelsplit" \
    ppodgorsek/robot-framework:latest

传递额外选项

RobotFramework支持许多选项，如--exclude、--variable、--loglevel等。可通过ROBOT_OPTIONS环境变量传递，例如：

docker run \
    -e ROBOT_OPTIONS="--loglevel DEBUG" \
    ppodgorsek/robot-framework:latest

测试电子邮件

本项目包含IMAP库，允许Robot Framework连接到邮件服务器。

建议使用支持IMAP连接的Docker Mailcatcher实例进行电子邮件测试，确保测试完成后邮件被丢弃。

处理日期时间和时区

本项目旨在允许测试在任何环境运行，有时可能在与本地或测试位置不同的时区。为解决此类问题，此镜像包含DateTimeTZ库。

要设置Docker镜像内使用的时区，可设置TZ环境变量：

docker run \
    -e TZ=America/New_York \
    ppodgorsek/robot-framework:latest

安装额外依赖

无需扩展镜像，可在运行时动态安装额外依赖。

只需挂载一个包含要通过pip安装的依赖列表的文本文件（默认情况下，如不挂载，该文件为空）：

docker run \
    -v <本地依赖文件路径>:/opt/robotframework/pip-requirements.txt:Z \
    -v <本地测试套件文件夹路径>:/opt/robotframework/tests:Z \
    ppodgorsek/robot-framework:latest

该文件必须遵循Pip官方要求文件格式。

以下是此类文件的示例内容：

robotframework-docker==1.4.2
rpa==1.50.0

对于大型依赖，仍建议扩展项目镜像并在其中添加依赖，以避免重复安装依赖延迟CI/CD流水线。

重跑失败测试

通过将环境变量ROBOT_RERUN_FAILED设置为大于0的值，可重跑失败测试。所有失败测试的重跑将在无并行化情况下执行。 环境变量ROBOT_RERUN_FAILED中的数字表示最大重跑轮次。所有重跑轮次仅测试上一轮失败的用例。 报告文件会合并所有轮次的结果，最后一轮结果为最终结果。

ROBOT_RERUN_FAILED的默认值为0，即测试失败后不会重新执行。

docker run \
    -e ROBOT_RERUN_FAILED=1 \
    ppodgorsek/robot-framework:latest

安全考虑

默认情况下，容器隐式使用--user=1000:1000运行，请记得相应调整命令行设置，例如：

docker run \
    --user=1001:1001 \
    ppodgorsek/robot-framework:latest

请记住，该UID/GID应被允许访问挂载的卷，以便读取测试套件和写入输出。

此外，可依靠用户命名空间进一步增强安全性。官方容器文档中有详细说明：

• Docker：Docker Engine中用户命名空间简介
• Podman：以非root用户运行无根Podman

确保容器无法对主机执行不必要的更改是良好的安全实践。在这方面，Podman可能领先于Docker，因为它不依赖root守护进程运行容器。

持续集成

Azure DevOps流水线

Azure DevOps提供Docker@2任务，但仅支持有限命令，因此需要使用script任务：

- job: FunctionalRegressionTests
  displayName: Robot Framework测试
  steps:
    - script: |
        set -x

        mkdir -p $(Build.Repository.LocalPath)/robot-framework-reports
        chmod -R ugo+rwx $(Build.Repository.LocalPath)/robot-framework-reports

        # ROBOT_OPTIONS用于生成特定输出文件，可用于在Azure DevOps流水线中发布测试结果
        # 记得将${{ parameters.robotFrameworkFolder }}替换为仓库中的正确文件夹名称
        docker run --rm \
          --shm-size=1g \
          -v $(Build.Repository.LocalPath)/robot-framework-reports:/opt/robotframework/reports:Z \
          -v $(Build.Repository.LocalPath)/${{ parameters.robotFrameworkFolder }}:/opt/robotframework/tests:Z \
          -e ROBOT_OPTIONS="-x outputxunit.xml" \
          -t docker.io/ppodgorsek/robot-framework:latest
      displayName: 运行Robot Framework测试

    - task: PublishTestResults@2
      condition: always()
      displayName: 发布Robot Framework测试结果
      inputs:
        testResultsFormat: 'JUnit'
        testResultsFiles: '**/outputxunit.xml'
        searchFolder: '$(Build.Repository.LocalPath)/robot-framework-reports'
        failTaskOnFailedTests: true
        failTaskOnFailureToPublishResults: true
        failTaskOnMissingResultsFile: true

Jenkins流水线

可直接通过shell命令在Jenkins流水线中运行项目：

pipeline {
  agent any
  stages {
    stage('功能回归测试') {
      steps {
        sh "docker run --shm-size=1g -e BROWSER=firefox -v $WORKSPACE/robot-tests:/opt/robotframework/tests:Z -v $WORKSPACE/robot-reports:/opt/robotframework/reports:Z ppodgorsek/robot-framework:latest"
      }
    }
  }
}

流水线阶段也可依赖Docker代理，如下例所示：

pipeline {
  agent none
  stages {
    stage('功能回归测试') {
      agent { docker {
        image 'ppodgorsek/robot-framework:latest'
        args '--shm-size=1g -u root' }
      }
      environment {
        BROWSER = 'firefox'
        ROBOT_TESTS_DIR = "$WORKSPACE/robot-tests"
        ROBOT_REPORTS_DIR = "$WORKSPACE/robot-reports"
      }
      steps {
        sh '''
          /opt/robotframework/bin/run-tests-in-virtual-screen.sh
        '''
      }
    }
  }
}

定义测试运行ID

在使用持续集成工具时，定义测试运行ID（如构建号或分支名称）有助于避免覆盖连续执行报告。

为此引入了ROBOT_TEST_RUN_ID变量：

• 若测试运行ID为空，报告文件夹为：${ROBOT_REPORTS_DIR}/
• 若提供测试运行ID，报告文件夹为：${ROBOT_REPORTS_DIR}/${ROBOT_TEST_RUN_ID}/

可在执行时传递，例如：

docker run \
    -e ROBOT_TEST_RUN_ID="feature/branch-name" \
    ppodgorsek/robot-framework:latest

默认情况下，测试运行ID为空。

上传测试报告到AWS S3桶

要将测试运行报告上传到S3桶，需定义以下环境变量：

docker run \
    -e AWS_ACCESS_KEY_ID=<您的AWS密钥> \
    -e AWS_SECRET_ACCESS_KEY=<您的AWS密钥 secret> \
    -e AWS_DEFAULT_REGION=<您的AWS区域，例如 eu-central-1> \
    -e AWS_BUCKET_NAME=<您的S3桶名称> \
    ppodgorsek/robot-framework:latest

测试本项目

仍有疑问？test/文件夹中已准备简单测试，可使用以下命令运行：

# 使用Chromium
docker run \
    -v `pwd`/reports:/opt/robotframework/reports:Z \
    -v `pwd`/test:/opt/robotframework/tests:Z \
    -e BROWSER=chrome \
    ppodgorsek/robot-framework:latest

# 使用Firefox
docker run \
    -v `pwd`/reports:/opt/robotframework/reports:Z \
    -v `pwd`/test:/opt/robotframework/tests:Z \
    -e BROWSER=firefox \
    ppodgorsek/robot-framework:latest

对于使用PowerShell的Windows用户，命令略有不同：

# 使用Chromium
docker run \
    -v ${PWD}/reports:/opt/robotframework/reports:Z \
    -v ${PWD}/test:/opt/robotframework/tests:Z \
    -e BROWSER=chrome \
    ppodgorsek/robot-framework:latest

# 使用Firefox
docker run \
    -v ${PWD}/reports:/opt/robotframework/reports:Z \
    -v ${PWD}/test:/opt/robotframework/tests:Z \
    -e BROWSER=firefox \
    ppodgorsek/robot-framework:latest

测试结果截图将保存在reports/文件夹中。

故障排除

Chromium崩溃

Chrome驱动可能因Docker容器中/dev/shm大小不足而崩溃：

UnknownError: session deleted because of page crash

这是Chromium的已知bug。

要避免此错误，请在启动容器时添加以下参数修改shm大小：--shm-size=1g（或其他更适合您测试的大小）

</a