UI テスト ui-testing

カスタム UI テストは、アプリケーションの UI テストを作成して自動的に実行できるオプション機能です。

概要 custom-ui-testing

AEM には、Cloud Manager 品質ゲートの統合スイートが用意されており、カスタムアプリケーションをスムーズに更新できるようになっています。特に、IT テストゲートでは、AEM API を使用したカスタムテストの作成と自動化に既に対応しています。

UI テストは、言語とフレームワーク（Cypress、Selenium、Java と Maven、JavaScript など）を幅広く選択できるように、Docker イメージにパッケージ化されています。また、AEM プロジェクトアーキタイプを使用すると、UI テストプロジェクトを容易に生成できます。

アドビでは、リアルタイムの再読み込みと自動待機が利用でき、時間の節約やテスト中の生産性の向上に役立つ、Cypress の使用をお勧めします。また、Cypress はシンプルで直感的な構文を提供し、テストを初めて行うユーザーでも学習と使用が容易になります。

UI テストは、カスタム UI テスト ステップで品質ゲートとして実行します。​ 実稼動パイプライン ​ では必須で、​ 実稼動以外のパイプライン ​ ではオプションです。 回帰や新しい機能を含む UI テストでは、エラーが検出、報告されます。

Java で記述された HTTP テストであるカスタム機能テストとは異なり、UI テストは Docker イメージにすることができます。 テストは、「UI テストの作成 ​ の節で定義されている規則に従う限り、任意の言語で記述でき ​ す。

UI テストの概要 get-started-ui-tests

この節では、Cloud Manager で実行用の UI テストの設定に必要な手順について説明します。

UI テストの作成 building-ui-tests

Maven プロジェクトでは、Docker ビルドコンテキストを生成します。この Docker ビルドコンテキストでは、UI テストを含む Docker イメージを作成する方法を説明します。Cloud Manager はこれを使用して、実際の UI テストを含む Docker イメージを生成します。

この節では、UI テストプロジェクトをリポジトリーに追加するために必要な手順について説明します。

Docker ビルドコンテキストの生成 generate-docker-build-context

Docker ビルドコンテキストを生成するには、次の処理を行う Maven モジュールが必要です。

最も簡単な方法は、Maven アセンブリプラグイン ​ を設定して 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 アセンブリプラグインに実行を追加します。

<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>

この実行は、assembly-ui-test-docker-context.xml に含まれている命令（プラグインの専門用語では​ アセンブリ記述子 ​と呼ばれます）に基づいてアーカイブを作成するように Maven アセンブリプラグインに指示します。アセンブリ記述子では、アーカイブに含める必要のあるすべてのファイルがリストアップされます。

<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>

アセンブリ記述子は、.tar.gz タイプのアーカイブを作成するようにプラグインに指示し、そのアーカイブに ui-test-docker-context 分類子を割り当てます。さらに、そのアーカイブに含める必要のある次のファイルがリストされます。

また、アセンブリ記述子は、UI テストのローカル実行中に生成される可能性のある一部のファイルを除外します。これにより、アーカイブのサイズが小さくなり、ビルドが高速になります。

Cloud Managerは、デプロイメントパイプライン中に Docker ビルドコンテキストアーカイブを自動的に取得して、テストイメージをビルドします。 最終的に、Cloud Managerは Docker イメージを実行して、アプリケーションに対する UI テストを実行します。

ビルドでは、0 または 1 つのアーカイブが生成されます。アーカイブが 0 の場合、テストステップはデフォルトで通過します。ビルドで複数のアーカイブが生成される場合、どのアーカイブが選択されるかは非決定的です。

顧客オプトイン customer-opt-in

Cloud Manager で UI テストを作成して実行するには、リポジトリにファイルを追加して、この機能をオプトインする必要があります。

このファイルが存在しない場合、UI テストの作成と実行はスキップされます。

testing.properties ファイルをビルドアーティファクトに含めるには、include ステートメントを assembly-ui-test-docker-context.xml ファイルに追加します。

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

アドビが指定したサンプルを使用する場合：

UI テストの書き込み writing-ui-tests

この節では、UI テストを含んだ Docker イメージが従う必要がある規則について説明します。Docker イメージは、前の節で説明した Docker ビルドコンテキストから作成されます。

環境変数 environment-variables

フレームワークに応じて、実行時に次の環境変数が Docker イメージに渡されます。

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

アドビテストサンプルには、設定パラメーターにアクセスするためのヘルパー関数が用意されています。

Cypress：標準関数 Cypress.env('VARIABLE_NAME') を使用します

テストレポートの生成 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

テストを開始する前に、Selenium サーバーが実行状態にあることを Docker イメージ側で確認する必要があります。Selenium サービスの準備が完了するまで、次の 2 段階の手順で待機します。

Selenium のステータスエンドポイントが肯定的な応答を返したら、テストを開始できます。

Adobeの UI テストサンプルでは、wait-for-grid.sh を使用します。 Docker の開始時に実行され、グリッドの準備が整った後でのみテストを開始します。

スクリーンショットとビデオのキャプチャ capture-screenshots

Docker イメージでは、追加のテスト出力（スクリーンショット、ビデオなど）を生成し、それらを環境変数 REPORTS_PATH で指定されたパスに保存する場合があります。REPORTS_PATH の下にあるファイルはすべて、テスト結果のアーカイブに含まれます。

デフォルトでアドビが提供するテストサンプルは、失敗したテストのスクリーンショットを作成します。

ヘルパー関数を使用して、テストのスクリーンショットを作成できます。

UI テストの実行中にテスト結果アーカイブが作成された場合は、Download Details カスタム UI テスト 手順 の下の「 定」ボタンをクリックして、Cloud Managerからダウンロードできます。

ファイルのアップロード upload-files

テストでは、場合によって、テスト中のアプリケーションにファイルをアップロードする必要があります。テストに対する Selenium デプロイメントの柔軟性を維持するため、Selenium に直接アセットをアップロードすることはできません。 ファイルをアップロードするには、代わりに次の手順を実行する必要があります。

Cypress 固有の詳細

HTTP プロキシの設定

Docker コンテナのエントリポイントでは、PROXY_HOST 環境変数の値を確認する必要があります。

この値が空の場合は、追加の手順は必要なく、HTTP プロキシを使用せずにテストを実行する必要があります。

空でない場合は、エントリポイントスクリプトで次の操作を実行する必要があります。

実装例は、GitHub の Cypress サンプルテストモジュールのエントリポイントにあります。

Playwright 固有の詳細

HTTP プロキシの設定

Cypress と同様に、空でない PROXY_HOST 環境変数が設定されている場合、テストでは HTTP プロキシを使用する必要があります。

その際は、以下の点を編集する必要があります。

Dockerfile

certutil. を提供する cURL と libnss3-tools をインストールします。

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

エントリポイントスクリプト

PROXY_HOST 環境変数が設定されている場合は、次の操作を実行する bash スクリプトを含めます。

実装例：

# 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 の設定

HTTP_PROXY 環境変数が設定されている場合にプロキシを使用するように、playwright 設定（例：playwright.config.js）を変更します。

実装例：

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 テストをアクティブ化する前に、Adobeでは、AEM as a Cloud Service SDK に対して UI テストをローカルで実行することをお勧めします。 または、実際のAEM as a Cloud Service インスタンスに対して実行します。

Cypress テストサンプル cypress-sample

JavaScript WebdriverIO テストサンプル javascript-sample

Playwright テストサンプル playwright-sample

Java Selenium WebDriver テストサンプル java-sample