UI 测试 ui-testing

自定义 UI 测试是一项可选功能，可用于为应用程序创建和自动运行 UI 测试。

概述 custom-ui-testing

AEM 提供了 Cloud Manager 质量关卡集成包，确保对自定义应用程序的顺利更新。 特别是，IT 测试门已支持使用 AEM API 创建和自动化定制测试。

UI 测试被打包为 Docker 映像，以便可选择多种语言和框架（如 Cypress、Selenium、Java 和 Maven 以及 JavaScript）。此外，通过使用AEM项目原型，可以轻松生成UI测试项目。

Adobe 建议使用 Cypress，因为它提供实时重新加载和自动等待，而这些功能有助于在测试期间节省时间并提高工作效率。Cypress 还提供一种简单而直观的语法，即使是不熟悉测试的人士也很容易学习和使用。

按照生产管道或非生产管道（可选）中的​ 自定义 UI 测试 步骤，作为每个 Cloud Manager 管道的特定质量关卡的一部分执行 UI 测试。任何 UI 测试，包括回归和新功能，都可以检测和报告错误。

与自定义功能测试（用 Java 编写的 HTTP 测试）不同，UI 测试可以是 Docker 映像，其中包含用任何语言编写的测试，只要它们遵循构建 UI 测试一节中定义的约定。

开始使用 UI 测试 get-started-ui-tests

此部分介绍了设置 UI 测试以在 Cloud Manager 中执行所需的步骤。

构建 UI 测试 building-ui-tests

Maven 项目生成 Docker 构建上下文。 此 Docker 构建上下文描述了如何创建包含 UI 测试的 Docker 映像，Cloud Manager 将使用它生成包含实际 UI 测试的 Docker 映像。

此部分介绍将 UI 测试项目添加到存储库所需的步骤。

生成 Docker 构建上下文 generate-docker-build-context

要生成 Docker 构建上下文，您需要一个 Maven 模块执行以下操作：

最简单的方法是配置 Maven Assembly 插件创建 Docker 构建上下文档案并为其分配正确的分类器。

您可以使用不同的技术和框架构建 UI 测试，但本节假设您的项目的布局方式与以下类似。

├── Dockerfile
├── assembly-ui-test-docker-context.xml
├── pom.xml
├── test-module
│   ├── package.json
│   ├── index.js
│   └── wdio.conf.js
└── wait-for-grid.sh

pom.xml 文件负责 Maven 构建。 将执行添加到 Maven Assembly 插件，如下所示。

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-assembly-plugin</artifactId>
    <configuration>
        <descriptors>
            <descriptor>${project.basedir}/assembly-ui-test-docker-context.xml</descriptor>
        </descriptors>
        <tarLongFileMode>gnu</tarLongFileMode>
    </configuration>
    <executions>
        <execution>
            <id>make-assembly</id>
            <phase>package</phase>
            <goals>
                <goal>single</goal>
            </goals>
        </execution>
    </executions>
</plugin>

此执行指示 Maven Assembly 插件根 assembly-ui-test-docker-context.xml 上下文中包含的指令创建档案，在插件的行话中称为​ Assembly 描述符。 Assembly 描述符列出了必须作为档案的一部分的所有文件。

<assembly>
    <id>ui-test-docker-context</id>
    <includeBaseDirectory>false</includeBaseDirectory>
    <formats>
        <format>tar.gz</format>
    </formats>
    <fileSets>
        <fileSet>
            <directory>${basedir}</directory>
            <includes>
                <include>Dockerfile</include>
                <include>wait-for-grid.sh</include>
            </includes>
        </fileSet>
        <fileSet>
            <directory>${basedir}/test-module</directory>
            <excludes>
                <exclude>node/**</exclude>
                <exclude>node_modules/**</exclude>
                <exclude>reports/**</exclude>
            </excludes>
        </fileSet>
    </fileSets>
</assembly>

Assembly 描述符指示插件创建 .tar.gz 类型的档案，并将 ui-test-docker-context 分类器分配给它。 此外，它还列出了必须包含在档案中的文件，包括以下内容：

Assembly 描述符还排除了在本地运行 UI 测试时可能生成的一些文件。 这保证了更小的档案和更快的构建。

Cloud Manager 会自动拾取包含 Docker 构建上下文的档案，它将在部署管道期间构建包含测试的 Docker 映像。最终，Cloud Manager 将运行 Docker 映像，对应用程序执行 UI 测试。

构建应该生成零或一个档案。 如果它生成零个档案，则默认通过测试步骤。 如果构建生成多个档案，那么选择哪个档案是不确定的。

客户选择启用 customer-opt-in

对于 Cloud Manager，要构建和执行 UI 测试，您必须通过向存储库添加文件来选择此功能。

如果此文件不存在，则会跳过 UI 测试生成和执行。

要在构建工件中包含 testing.properties 文件，请在 assembly-ui-test-docker-context.xml 文件中添加 include 语句。

[...]
<includes>
    <include>Dockerfile</include>
    <include>wait-for-grid.sh</include>
    <include>testing.properties</include> <!-- opt-in test module in Cloud Manager -->
</includes>
[...]

如果您使用的是 Adobe 提供的示例：

编写 UI 测试 writing-ui-tests

本节描述包含 UI 测试的 Docker 映像必须遵循的惯例。 Docker 映像是根据上一节所述 Docker 构建上下文构建的。

环境变量 environment-variables

根据您的框架，以下环境变量会在运行时传递给 Docker 映像。

* these values will be empty if there is no publish instance

Adobe 测试示例提供了帮助程序函数来访问配置参数：

生成测试报告 generate-test-reports

Docker 映像必须以 JUnit XML 格式生成测试报告，并将其保存在环境变量 REPORTS_PATH 指定的路径中。JUnit XML 格式是一种广泛使用的报告测试结果的格式。如果 Docker 映像使用 Java 和 Maven，则诸如 Maven Surefire 插件和 Maven Failsafe 插件等标准测试模块可以立即生成此类报告。

如果 Docker 映像是用其他编程语言或测试运行程序实现的，请查看文档，了解如何生成 JUnit XML 报告。

前提条件 prerequisites

特定于 Selenium 详细信息

等待 Selenium 就绪 waiting-for-selenium

在测试开始之前，Docker 映像负责确保 Selenium 服务器启动并运行。 等待 Selenium 服务需要两个步骤。

一旦 Selenium 的状态端点得到肯定响应，测试就可以开始了。

Adobe UI 测试示例使用脚本 wait-for-grid.sh 执行此工作，该脚本在 Docker 启动时执行，并且仅在网格准备就绪后才开始实际测试执行。

捕获屏幕快照和视频 capture-screenshots

Docker 映像可能会产生额外的测试输出（例如，屏幕快照或视频），并将其保存在环境变量 REPORTS_PATH 指定的路径中。测试结果存档中包括任何可在 REPORTS_PATH 下找到的文件。

默认情况下，Adobe 提供的测试示例将为任何失败的测试创建屏幕快照。

您可以使用辅助程序函数通过测试创建屏幕快照。

如果在执行 UI 测试期间创建了测试结果存档，则可使用​自定义 UI 测试 ​步骤下的 Download Details 按钮从 Cloud Manager 下载该存档。

上载文件 upload-files

测试有时必须将文件上载到正在测试的应用程序。 要确保 Selenium 的部署相对于您的测试具备灵活性，就无法直接将资源上传到 Selenium。相反，上载文件需要以下步骤。

Cypress特定的详细信息

设置HTTP代理

Docker容器的入口点需要检查PROXY_HOST环境变量的值。

如果此值为空，则无需执行其他步骤，并且无需使用HTTP代理即可执行测试。

如果不为空，则入口点脚本需要：

在GitHub上的Cypress示例测试模块的Entrypoint中可以找到示例实施。

特定于播放器的详细信息

设置HTTP代理

与Cypress类似，如果提供了非空的PROXY_HOST环境变量，则测试需要使用HTTP代理。

为此，需要做出以下修改。

Dockerfile

安装cURL和libnss3-tools，后者提供certutil.

RUN apt -y update \
    && apt -y --no-install-recommends install curl libnss3-tools \
    && rm -rf /var/lib/apt/lists/*

入口点脚本

包括一个bash脚本，在提供PROXY_HOST环境变量时，该脚本将执行以下操作：

实施示例：

# setup proxy environment variables and CA certificate
if [ -n "${PROXY_HOST:-}" ]; then
  if [ -n "${PROXY_HTTPS_PORT:-}" ]; then
    export HTTP_PROXY="https://${PROXY_HOST}:${PROXY_HTTPS_PORT}"
  elif [ -n "${PROXY_HTTP_PORT:-}" ]; then
    export HTTP_PROXY="http://${PROXY_HOST}:${PROXY_HTTP_PORT}"
  fi
  if [ -n "${PROXY_CA_PATH:-}" ]; then
    echo "installing certificate"
    mkdir -p $HOME/.pki/nssdb
    certutil -d sql:$HOME/.pki/nssdb -A -t "CT,c,c" -n "EaaS Client Proxy Root" -i $PROXY_CA_PATH
    export NODE_EXTRA_CA_CERTS=${PROXY_CA_PATH}
  fi
  if [ -n "${PROXY_OBSERVABILITY_PORT:-}" ] && [ -n "${HTTP_PROXY:-}" ]; then
    echo "waiting for proxy"
    curl --silent  --retry ${PROXY_RETRY_ATTEMPTS:-3} --retry-connrefused --retry-delay ${PROXY_RETRY_DELAY:-10} \
      --proxy ${HTTP_PROXY} --proxy-cacert ${PROXY_CA_PATH:-""} \
      ${PROXY_HOST}:${PROXY_OBSERVABILITY_PORT}
    if [ $? -ne 0 ]; then
      echo "proxy is not ready"
      exit 1
    fi
  fi
fi

播放器配置

修改播放器配置（例如在playwright.config.js中）以在设置HTTP_PROXY环境变量时使用代理。

实施示例：

const proxyServer = process.env.HTTP_PROXY || ''

// enable proxy if set
if (proxyServer !== '') {
 cfg.use.proxy = {
  server: proxyServer,
 }
}

本地运行 UI 测试 run-ui-tests-locally

在 Cloud Manager 管道中激活 UI 测试之前，建议在本地对 AEM as a Cloud Service SDK 或实际的 AEM as a Cloud Service 实例中运行 UI 测试。

Cypress 测试示例 cypress-sample

JavaScript WebdriverIO 测试示例 javascript-sample

Playwright测试示例 playwright-sample

Java Selenium WebDriver 测试示例 java-sample