cyclelabs/cycle-cli

Cycle CLI 容器化版本技术文档

概述和主要用途

Cycle CLI容器化版本是将Cycle命令行界面（CLI）打包为容器的解决方案。传统上，Cycle CLI与Cycle测试自动化软件安装程序一起分发，而容器化版本增强了灵活性，允许用户不仅在本地环境，更重要的是在CI/CD流水线中执行Cycle测试，无需专用Windows虚拟机代理，同时兼容Linux架构。尽管在容器中可执行的测试类型存在一定限制，但它为许多客户提供了可行的替代方案。

核心功能和特性

主要优势

• 可移植性：容器完全独立，包含运行cycle-cli所需的所有依赖，可在任何支持容器运行时的环境（如Azure DevOps、GitLab、GitHub Actions的托管代理/运行器）中运行，无需对执行系统进行额外配置。
• 成本效益：不再要求运行硬件架构为Windows，可在Linux虚拟机或Azure容器实例等工具上运行，减少虚拟机层，降低测试执行成本。
• 自动化友好：轻松集成到任何CI/CD平台，每次自动化执行都在全新容器环境中启动，确保环境清洁。

使用场景和适用范围

• 本地测试：开发人员在本地设备上快速执行Cycle测试，无需复杂环境配置。
• CI/CD流水线：集成到Jenkins、GitHub Actions、GitLab CI等CI/CD平台，实现测试自动化，支持多阶段测试流程。
• 跨平台测试：在Linux环境中执行原本依赖Windows的Cycle测试，扩展测试环境兼容性。

使用要求

• Docker Engine：需安装Docker运行时环境。
• 操作系统：支持Linux、Windows或macOS。
• Cycle认证：通过token或client-id/client-credential（推荐）进行Cycle认证，详情参见Cycle OAuth2认证文档。

详细使用方法和配置说明

Docker卷挂载（Volume Mapping）

容器需要访问本地Cycle项目文件（如.cycproj、.feature文件），通过-v参数将主机目录挂载到容器内的/code目录。

基本语法

bash
docker run -v "$(pwd):/code"

说明

• $(pwd)：主机当前工作目录（Cycle项目所在目录）。
• /code：容器内的目标目录，项目文件将映射到此处，容器可访问其中的.cycproj、config/secrets.conf及/combined文件夹等。

环境变量映射（Environment Variable Mapping）

通过--env参数将主机环境变量传递到容器，至少需传递Cycle认证所需的DOCKERIZED_CYCLE_APP_ID和DOCKERIZED_CYCLE_APP_SECRET。

基本语法

bash
docker pull cyclelabs/cycle-cli:latest
docker run --rm \
  --env DOCKERIZED_CYCLE_APP_ID="${DOCKERIZED_CYCLE_APP_ID}" \
  --env DOCKERIZED_CYCLE_APP_SECRET="${DOCKERIZED_CYCLE_APP_SECRET}" \
  cyclelabs/cycle-cli:latest \
  --clientid "${DOCKERIZED_CYCLE_APP_ID}" \
  --client-credential "${DOCKERIZED_CYCLE_APP_SECRET}" \
  -p /code combined/api-test.feature

关键环境变量

使用.conf文件管理配置和秘密

配置文件（.conf）用于安全映射秘密值，避免明文暴露，使cycle-cli可在测试中使用这些值。

1. .conf文件与Cycle变量映射

在Cycle测试的.feature文件中，通过Background步骤从.conf文件加载变量：

gherkin
Background:
If I verify file "combined/local.conf" exists
Then I assign values from config file "combined/local.conf" to variables
Else I assign values from config file "combined/secrets.conf" to variables
EndIf

2. .conf文件示例（secrets.conf）

将环境变量映射为Cycle变量：

ini
pw_oracle_db=${PW_ORACLE_DB}
pw_sql_db=${PW_SQL_DB}
pw_db2=${PW_DB2}
pw_mysql=${PW_MYSQL}
pw_openssh=${PW_OPENSSH}

3. 在.feature文件中使用变量

引用上述配置的变量（如$pw_openssh）：

gherkin
Scenario: OpenSSH/Linux - Cycle CI
When I open terminal with SSH encryption connected to "openssh.ci.cyclelabs.io:22" logged in as "cycl-ci" $pw_openssh sized to 25 lines and 80 columns
Then I see "~]$" on last line in terminal within 15 seconds
    And I close terminal

4. 变量黑名单（VariableBlacklist）

为防止秘密值在Cycle报告中明文显示，需在.cycproj文件中配置VariableBlacklist：

json
"VariableBlackList": ["pw_azuresql", "pw_db2", "pw_moca", "pw_mysql", "pw_oracle_db", "pw_openssh"]

Docker Compose配置

使用docker-compose.yml可简化多容器协调（如Cycle CLI容器与Selenium Chrome容器）和环境配置。

示例：Chrome浏览器测试的docker-compose.yml

yaml
services:
  cycle-browser-test-chrome:
    image: "cyclelabs/cycle-cli:latest"
    shm_size: 2g
    volumes:
      - .:/code  # 挂载当前目录到容器/code
    depends_on:
      - "chrome"  # 依赖Chrome容器启动
    environment:
      DOCKERIZED_CYCLE_APP_ID: ${DOCKERIZED_CYCLE_APP_ID}
      DOCKERIZED_CYCLE_APP_SECRET: ${DOCKERIZED_CYCLE_APP_SECRET}
      PW_OPENSSH: ${PW_OPENSSH}  # 其他秘密环境变量
    command: ["--clientid", "${DOCKERIZED_CYCLE_APP_ID}", "--client-credential", "${DOCKERIZED_CYCLE_APP_SECRET}", "-p", "/code", "combined/grocerio-browser-test-chrome.feature"]

  chrome:
    image: "selenium/standalone-chrome"
    environment:
      - CHROME_OPTS=--no-sandbox --disable-dev-shm-usage --headless
    volumes:
      - /dev/shm:/dev/shm
    ports:
      - "4444:4444"
    hostname: chrome
    privileged: true
    shm_size: 2g

说明

• depends_on：确保chrome容器先启动，Cycle测试才能连接Chrome浏览器。
• shm_size：设置共享内存大小，避免浏览器运行时内存不足。
• command：指定Cycle CLI执行命令，包括认证参数和测试特征文件路径。

CI/CD平台集成

Jenkins集成示例

在Jenkins流水线中，通过Jenkinsfile配置多阶段测试，使用Docker Compose执行不同类型的Cycle测试。

Jenkinsfile片段

groovy
stage('Run Cycle Browser Test - Chrome') {
    steps {
        catchError(buildResult: 'SUCCESS', stageResult: 'FAILURE') {
            sh "docker compose -f chrome-test-docker-compose.yml up --attach cycle-browser-test-chrome --abort-on-container-exit"
            sh "docker compose -f chrome-test-docker-compose.yml down"
        }
    }
}

秘密管理

Jenkins中通过"Manage Jenkins → Manage Credentials"存储秘密，在流水线中引用：

groovy
environment {
    DOCKERIZED_CYCLE_APP_ID = credentials('cycle-app-id')
    DOCKERIZED_CYCLE_APP_SECRET = credentials('cycle-app-secret')
}

GitHub Actions集成示例

在GitHub Actions中，通过secrets存储秘密，在工作流文件中映射为环境变量。

.github/workflows/cycle-test.yml片段

yaml
jobs:
  cycle-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Cycle test with Docker Compose
        env:
          DOCKERIZED_CYCLE_APP_ID: ${{ secrets.DOCKERIZED_CYCLE_APP_ID }}
          DOCKERIZED_CYCLE_APP_SECRET: ${{ secrets.DOCKERIZED_CYCLE_APP_SECRET }}
        run: |
          docker compose -f chrome-test-docker-compose.yml up --attach cycle-browser-test-chrome --abort-on-container-exit

本地运行指南

1. 设置环境变量

Windows（命令提示符）

cmd
set DOCKERIZED_CYCLE_APP_ID=your-app-id
set DOCKERIZED_CYCLE_APP_SECRET=your-app-secret

Windows（PowerShell）

powershell
$env:DOCKERIZED_CYCLE_APP_ID="your-app-id"
$env:DOCKERIZED_CYCLE_APP_SECRET="your-app-secret"

Mac/Linux（终端）

bash
export DOCKERIZED_CYCLE_APP_ID="your-app-id"
export DOCKERIZED_CYCLE_APP_SECRET="your-app-secret"

2. 执行单特征文件（docker run）

bash
docker pull cyclelabs/cycle-cli:latest
docker run --rm \
  --shm-size=2g \
  -v "$(pwd):/code" \
  --env DOCKERIZED_CYCLE_APP_ID="${DOCKERIZED_CYCLE_APP_ID}" \
  --env DOCKERIZED_CYCLE_APP_SECRET="${DOCKERIZED_CYCLE_APP_SECRET}" \
  cyclelabs/cycle-cli:latest \
  --clientid "${DOCKERIZED_CYCLE_APP_ID}" \
  --client-credential "${DOCKERIZED_CYCLE_APP_SECRET}" \
  -p /code combined/api-test.feature

3. 执行Docker Compose文件

在包含docker-compose.yml的目录中运行：

bash
docker compose up

执行完成后停止并移除容器：

bash
docker compose down