UI テスト
- トピック:
- Cloud Manager
- 開発
作成対象:
- 管理者
- 開発者
カスタム UI テストは、アプリケーションの UI テストを作成して自動的に実行できるオプション機能です。
概要
AEM には、Cloud Manager 品質ゲートの統合スイートが用意されており、カスタムアプリケーションをスムーズに更新できるようになっています。特に、IT テストゲートでは、AEM API を使用したカスタムテストの作成と自動化に既に対応しています。
UI テストは、言語とフレームワーク(Cypress、Selenium、Java と Maven、JavaScript など)を幅広く選択できるように、Docker イメージにパッケージ化されています。また、AEM プロジェクトアーキタイプを使用すると、UI テストプロジェクトを容易に生成できます。
アドビでは、リアルタイムの再読み込みと自動待機が利用でき、時間の節約やテスト中の生産性の向上に役立つ、Cypress の使用をお勧めします。Cypress は、簡単で直感的な構文を提供し、テストを初めて行うユーザーでも学習や使用が簡単にできます。
UI テストは、実稼動パイプラインまたはオプションで非実稼動パイプラインのカスタム UI テスト 手順で、各 Cloud Manager パイプラインの特定の品質ゲートの一部として実行します。回帰や新しい機能を含む UI テストでは、エラーが検出、報告されます。
UI テストは、Java で記述された HTTP テストであるカスタム機能テストとは異なり、UI テストの作成の節で定義されている規則に従う限り、任意の言語で記述されたテストを含む Docker イメージにすることができます。
UI テストの概要
この節では、Cloud Manager で実行用の UI テストの設定に必要な手順について説明します。
-
使用するテストフレームワークを決定します。
-
Cypress (デフォルト)の場合は、AEM テストサンプルのリポジトリからサンプルコードを使用するかCloud Manager リポジトリの
ui.tests
フォルダーに自動的に生成されたサンプルコードを使用します。 -
Playwright の場合は、AEM テストサンプルリポジトリのサンプルコードを使用します。
-
Webdriver.IO の場合は、AEM テストサンプルのリポジトリからサンプルコードを使用します。
-
Selenium WebDriver の場合は、AEM テストサンプルのリポジトリからサンプルコードを使用します。
-
その他のプログラミング言語については、このドキュメントの UI テストの構築の節を参照して、テストプロジェクトを設定してください。
-
-
このドキュメントの顧客オプトインの節に従って、UI テストがアクティベートされていることを確認してください。
-
テストケースを作成し、ローカルでテストを実行します。
-
コードを Cloud Manager リポジトリにコミットし、Cloud Manager パイプラインを実行します。
UI テストの作成
Maven プロジェクトでは、Docker ビルドコンテキストを生成します。この Docker ビルドコンテキストでは、UI テストを含む Docker イメージを作成する方法を説明します。Cloud Manager はこれを使用して、実際の UI テストを含む Docker イメージを生成します。
この節では、UI テストプロジェクトをリポジトリーに追加するために必要な手順について説明します。
Docker ビルドコンテキストの生成
Docker ビルドコンテキストを生成するには、次の処理を行う Maven モジュールが必要です。
Dockerfile
と、テストを含んだ Docker イメージの作成に必要なその他のすべてのファイルを格納したアーカイブを作成する。- アーカイブに
ui-test-docker-context
分類子をタグ付けする。
これを行うには、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
分類子を割り当てます。さらに、そのアーカイブに含める必要のある次のファイルがリストされます。
Dockerfile
:Docker イメージの作成に必須wait-for-grid.sh
スクリプト:目的は後述のとおり- 実際の UI テスト:
test-module
フォルダー内に Node.js プロジェクトで実装
また、アセンブリ記述子は、UI テストのローカル実行中に生成される可能性のある一部のファイルを除外します。これにより、アーカイブのサイズが小さくなり、ビルドが高速になります。
Docker ビルドコンテキストを含んだアーカイブが Cloud Manager で自動的に選択され、テストを含んだ Docker イメージがデプロイメントパイプライン中に作成されます。最終的に、Cloud Manager は Docker イメージを実行して、アプリケーションに対する UI テストを実行します。
ビルドでは、0 または 1 つのアーカイブが生成されます。アーカイブが 0 の場合、テストステップはデフォルトで通過します。ビルドで複数のアーカイブが生成される場合、どのアーカイブが選択されるかは非決定的です。
顧客オプトイン
Cloud Manager で UI テストを作成して実行するには、リポジトリにファイルを追加して、この機能をオプトインする必要があります。
- ファイル名は
testing.properties
にする必要があります。 - ファイルの内容は
ui-tests.version=1
にする必要があります。 - このファイルは、UI テストサブモジュールの
pom.xml
ファイルの横にある UI テスト用 Maven サブモジュールの下にある必要があります。 - ファイルは、作成された
tar.gz
ファイルのルートに必要です。
このファイルが存在しない場合、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>
[...]
アドビが指定したサンプルを使用する場合:
-
AEM プロジェクトアーキタイプに基づいて生成された JavaScript ベースの
ui.tests
フォルダーの場合、以下のコマンドを実行して必要な設定を追加できます。echo "ui-tests.version=1" > testing.properties if ! grep -q "testing.properties" "assembly-ui-test-docker-context.xml"; then awk -v line=' <include>testing.properties</include>' '/<include>wait-for-grid.sh<\/include>/ { printf "%s\n%s\n", $0, line; next }; 1' assembly-ui-test-docker-context.xml > assembly-ui-test-docker-context.xml.new && mv assembly-ui-test-docker-context.xml.new assembly-ui-test-docker-context.xml fi
-
アドビが提供する Cypress および Java Selenium のテストサンプルには、既にオプトインフラグが設定されています。
UI テストの書き込み
この節では、UI テストを含んだ Docker イメージが従う必要がある規則について説明します。Docker イメージは、前の節で説明した Docker ビルドコンテキストから作成されます。
環境変数
フレームワークに応じて、実行時に次の環境変数が Docker イメージに渡されます。
SELENIUM_BASE_URL
http://my-ip:4444
SELENIUM_BROWSER
chrome
AEM_AUTHOR_URL
http://my-ip:4502/context-path
AEM_AUTHOR_USERNAME
admin
AEM_AUTHOR_PASSWORD
admin
AEM_PUBLISH_URL
http://my-ip:4503/context-path
AEM_PUBLISH_USERNAME
admin
AEM_PUBLISH_PASSWORD
admin
REPORTS_PATH
/usr/src/app/reports
UPLOAD_URL
http://upload-host:9090/upload
PROXY_HOST
proxy-host
PROXY_HTTPS_PORT
8071
PROXY_HTTP_PORT
8070
PROXY_CA_PATH
/path/to/root_ca.pem
PROXY_OBSERVABILITY_PORT
8081
PROXY_RETRY_ATTEMPTS
12
PROXY_RETRY_DELAY
5
* these values will be empty if there is no publish instance
アドビテストサンプルには、設定パラメーターにアクセスするためのヘルパー関数が用意されています。
- Cypress:標準関数
Cypress.env('VARIABLE_NAME')
を使用します - JavaScript:
lib/config.js
モジュールを参照してください - Java:
Config
クラスを参照してください
テストレポートの生成
Docker イメージは、テストレポートを JUnit XML 形式で生成して、環境変数 REPORTS_PATH
で指定されたパスに保存する必要があります。JUnit XML 形式は、テスト結果のレポートに広く使用されている形式です。Docker イメージで Java と Maven を使用する場合、Maven Surefire プラグインや Maven Failsafe プラグイン などの標準テストモジュールでは、すぐに使用できるレポートを生成できます。
Docker イメージが他のプログラミング言語またはテストランナーで実装されている場合は、選択したツールのドキュメントを参照して、JUnit XML レポートの生成方法を確認してください。
request.log
ファイルが含まれます。前提条件
- Cloud Manager でのテストは、技術管理者ユーザーを使用して実行されます。
- 機能テストの範囲を定義するコンテナ化されたインフラストラクチャは、次の境界によって制限されます。
Selenium 固有の詳細
Selenium の準備完了までの待機
テストを開始する前に、Selenium サーバーが実行状態にあることを Docker イメージ側で確認する必要があります。Selenium サービスの準備が完了するまで、次の 2 段階の手順で待機します。
SELENIUM_BASE_URL
環境変数から Selenium サービスの URL を読み取ります。- Selenium API で公開されている ステータスエンドポイントに対して定期的にポーリングを行います。
Selenium のステータスエンドポイントが肯定的な応答を返したら、テストを開始できます。
Adobe UI のテストサンプルでは、これをスクリプト wait-for-grid.sh
で処理します。Docker の起動時に実行され、グリッドの準備が整った場合にのみ、実際のテストが実行されます。
スクリーンショットとビデオのキャプチャ
Docker イメージでは、追加のテスト出力(スクリーンショット、ビデオなど)を生成し、それらを環境変数 REPORTS_PATH
で指定されたパスに保存する場合があります。REPORTS_PATH
の下にあるファイルはすべて、テスト結果のアーカイブに含まれます。
デフォルトでアドビが提供するテストサンプルは、失敗したテストのスクリーンショットを作成します。
ヘルパー関数を使用して、テストのスクリーンショットを作成できます。
- JavaScript:takeScreenshot コマンド
- Java:コマンド
UI テストの実行中にテスト結果アーカイブが作成された場合は、カスタム UI テスト 手順の下にある「Download Details
」ボタンを使用して、Cloud Manager からダウンロードできます。
ファイルのアップロード
テストでは、場合によって、テスト中のアプリケーションにファイルをアップロードする必要があります。テストに対する Selenium デプロイメントの柔軟性を維持するため、Selenium に直接アセットをアップロードすることはできません。ファイルをアップロードするには、代わりに次の手順を実行する必要があります。
-
UPLOAD_URL
環境変数で指定された URL にファイルをアップロードします。-
アップロードは、マルチパートフォームを含んだ 1 つの POST リクエストで実行する必要があります。
-
このマルチパートフォームには、1 つのファイルフィールドが必要です。
-
これは
curl -X POST ${UPLOAD_URL} -F "data=@file.txt"
と同等です。 -
このような HTTP リクエストを実行する方法については、Docker イメージで使用されているプログラミング言語のドキュメントやライブラリを参照してください。
-
アドビテストサンプルには、ファイルをアップロードするためのヘルパー関数が用意されています。
- JavaScript:getFileHandleForUpload コマンドを参照してください。
- Java:FileHandler クラスを参照してください。
-
-
アップロードが成功した場合、リクエストは
200 OK
タイプのtext/plain
応答を返します。- この応答の内容は不透明なファイルハンドルです。
<input>
要素のファイルパスの代わりにこのハンドルを使用して、アプリケーション内のアップロードファイルをテストできます。
Cypress 固有の詳細
HTTP プロキシの設定
Docker コンテナのエントリポイントでは、PROXY_HOST
環境変数の値を確認する必要があります。
この値が空の場合は、追加の手順は不要で、HTTP プロキシを使用せずにテストを実行する必要があります。
空でない場合は、エントリポイントスクリプトで次の操作を実行する必要があります。
-
UI テストを実行するための HTTP プロキシ接続を設定します。これを行うには、次の値を使用して作成された
HTTP_PROXY
環境変数を書き出します。PROXY_HOST
変数によって提供されるプロキシホストPROXY_HTTPS_PORT
またはPROXY_HTTP_PORT
変数によって提供されるプロキシポート(値が空でない変数が使用されます)
-
HTTP プロキシに接続する際に使用する CA 証明書を設定します。その場所は、
PROXY_CA_PATH
変数によって提供されます。- これを行うには、
NODE_EXTRA_CA_CERTS
環境変数を書き出します。
- これを行うには、
-
HTTP プロキシの準備が整うまで待機します。
- 準備状況を確認するには、環境変数
PROXY_HOST
、PROXY_OBSERVABILITY_PORT
、PROXY_RETRY_ATTEMPTS
およびPROXY_RETRY_DELAY
を使用できます。 - cURL リクエストを使用して確認できます。その場合は、必ず
Dockerfile
に cURL をインストールしてください。
- 準備状況を確認するには、環境変数
実装例は、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 スクリプトを含めます。
HTTP_PROXY
やNODE_EXTRA_CA_CERTS
などのプロキシ関連の変数を書き出しますcertutil
を使用して Chromium のプロキシ CA 証明書をインストールします- HTTP プロキシの準備が整うまで待機します(失敗した場合は終了します)。
実装例:
# 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 テストのローカルでの実行
Cloud Manager パイプラインで UI テストをアクティブ化する前に、UI テストをAEM as a Cloud Service SDK に対してローカルで実行するか、実際の AEM as a Cloud Service インスタンスに対してローカルで実行することをお勧めします。
Cypress テストサンプル
-
シェルを開き、リポジトリ内の
ui.tests/test-module
フォルダーに移動します -
Cypress およびその他の前提条件のインストール
npm install
-
テストの実行に必要な環境変数の設定
export AEM_AUTHOR_URL=https://author-<program-id>-<environment-id>.adobeaemcloud.com export AEM_AUTHOR_USERNAME=<user> export AEM_AUTHOR_PASSWORD=<password> export AEM_PUBLISH_URL=https://publish-<program-id>-<environment-id>.adobeaemcloud.com export AEM_PUBLISH_USERNAME=<user> export AEM_PUBLISH_PASSWORD=<password> export REPORTS_PATH=target/
-
次のいずれかのコマンドでテストを実行します
npm test # Using default Cypress browser npm run test-chrome # Using Google Chrome browser npm run test-firefox # Using Firefox browser
JavaScript WebdriverIO テストサンプル
-
シェルを開き、リポジトリ内の
ui.tests
フォルダーに移動します -
Maven を使用してテストを開始するには、次のコマンドを実行します
mvn verify -Pui-tests-local-execution \ -DAEM_AUTHOR_URL=https://author-<program-id>-<environment-id>.adobeaemcloud.com \ -DAEM_AUTHOR_USERNAME=<user> \ -DAEM_AUTHOR_PASSWORD=<password> \ -DAEM_PUBLISH_URL=https://publish-<program-id>-<environment-id>.adobeaemcloud.com \ -DAEM_PUBLISH_USERNAME=<user> \ -DAEM_PUBLISH_PASSWORD=<password>
- これにより、スタンドアロンの Selenium インスタンスが起動し、それに対するテストが実行されます。
- ログファイルは、リポジトリの
target/reports
フォルダーに保存されます。 - テストでは ChromeDriver の最新リリースがテスト用に自動的にダウンロードされるので、最新バージョンの Chrome を使用していることを確認する必要があります。
再生テストサンプル
-
シェルを開き、リポジトリ内の
ui.tests
フォルダーに移動します -
Maven を使用して Docker イメージをビルドするには、次のコマンドを実行します
mvn clean package -Pui-tests-docker-build
-
Maven を使用してテストを開始するには、次のコマンドを実行します
mvn verify -Pui-tests-docker-execution \ -DAEM_AUTHOR_URL=https://author-<program-id>-<environment-id>.adobeaemcloud.com \ -DAEM_AUTHOR_USERNAME=<user> \ -DAEM_AUTHOR_PASSWORD=<password> \ -DAEM_PUBLISH_URL=https://publish-<program-id>-<environment-id>.adobeaemcloud.com \ -DAEM_PUBLISH_USERNAME=<user> \ -DAEM_PUBLISH_PASSWORD=<password>
Java Selenium WebDriver テストサンプル
-
シェルを開き、リポジトリ内の
ui.tests/test-module
フォルダーに移動します -
Maven を使用してテストを開始するには、次のコマンドを実行します
# Start selenium docker image # we mount /tmp/shared as a shared volume that will be used between selenium and the test module for uploads docker run -d -p 4444:4444 -v /tmp/shared:/tmp/shared selenium/standalone-chromium:latest # Run the tests using the previously started Selenium instance mvn verify -Pui-tests-local-execution -DSELENIUM_BASE_URL=http://<server>:4444