Java 用 Azure Core テスト共有ライブラリ - バージョン 1.22.0

[アーティクル]
11/03/2023

このライブラリには、Azure SDK クライアントライブラリをテストするために使用されるコアクラスが含まれています。

新しい SDK テストでは、 Azure SDK Tools テストプロキシを使用して、HTTP 対話を記録および再生します。既存の TestBase からテストプロキシを使用するように移行する場合、またはテストプロキシの使用の詳細については、テストプロキシ移行ガイドを参照してください。

作業の開始

このパッケージを使用するには、 pom.xmlに以下を追加します。


<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-test</artifactId>
  <version>1.22.0</version>
</dependency>

主要な概念

モードで Record テストを実行する: HTTP 要求をインターセプトする手段を記録するには、その要求をファイルに格納し、最初にターゲットにされたライブリソースから受信した応答を格納します。
モードで Playback テストを実行する: 再生とは、HTTP 要求をインターセプトし、以前に記録された一致する要求の格納された応答で応答することを意味します。
モードで Live テストを実行する: ライブ実行とは、HTTP 要求をインターセプトせず、Azure サービスに直接送信することを意味します。
機密情報をサニタイズする: 機密情報は、パスワード、一意の識別子、個人情報などのコンテンツを記録からクリーンアップする必要があることを意味します。
TestProxyTestBase: を作成 InterceptorManager し、テストをテストの実行に使用 test-proxy できるようにする基本テストクラス。テストセッションデータを再生するか、テストセッションを記録します。
InterceptorManager: 既存のテストセッションレコードからデータを読み取るか、ネットワーク呼び出しをメモリに記録することによって、ネットワーク呼び出しを追跡するクラス。テストセッションレコードは、".assets/{library-level}/src/test/resources/session-records/TestFileName.testName}.json" から保存または読み取られます。
TestProxyRecordPolicy: を使用してネットワーク呼び出しを記録する test-proxyパイプラインポリシー。
TestProxyPlaybackClient: テストプロキシを使用してセッションレコードの記録されたデータからの応答を再生する HTTP クライアント。

テストを記述または実行する

テストリソースを設定する

ライブテストを実行して記録を生成するには、ライブ Azure リソースが必要です。

テストリソースのデプロイ用にファイルを test-resources.json まだ設定していない場合、または独自のテストリソースを使用する場合は、代わりにこれらのリソースをターゲットにするように資格情報を構成するだけです。

ファイルを test-resources.json 作成するには:

特定のサービスと必要な構成用の Azure Resource Management テンプレートを作成します。これを行うには、ポータルでリソースを作成し、最後の手順 (確認と作成) で [自動化用テンプレートのダウンロード] をクリックします。
このテンプレートを、 test-resources.json パッケージ (sdk/<my-service>/test-resources.json) ファイルを含むディレクトリの下のファイルに保存します。例として Table のを参照できます。
のグループ化された "resources" セクションに、追加のリソースの test-resources.json テンプレートを追加します (例)。
"outputs"これらのリソースにアクセスするためにtest-resources.json必要な環境変数について説明するセクションをに追加します (例)。

資格情報を構成する

Java SDK テストでは、を使用 EnvironmentVariables してテスト資格情報を格納します。

/eng/common/TestResources のスクリプトを使用New-TestResourcesする場合、スクリプトはサービスのライブテストを実行するために必要な環境変数を出力する必要があります。これらの変数を適切な書式設定でローカル環境変数に格納すると、テストの実行時に資格情報とテスト構成変数が環境に設定されます。

サービスにテストデプロイ用のファイルがないtest-resources.json場合は、、、、および AZURE_CLIENT_SECRET の環境変数AZURE_SUBSCRIPTION_IDAZURE_TENANT_IDAZURE_CLIENT_IDを少なくとも設定する必要があります。

変数をAZURE_SUBSCRIPTION_IDorganizationのサブスクリプション ID に設定します。 Azure Portal の [サブスクリプション] ブレードの [概要] セクションで確認できます。
テストサービスプリンシパルの AZURE_TENANT_ID、 AZURE_CLIENT_ID、および AZURE_CLIENT_SECRET を定義します。サービスプリンシパルがない場合は、Azure CLI の az ad sp create-for-rbac コマンドを使用します (理想的には、サービスプリンシパルの名前プレフィックスとしてエイリアスを使用します)。

az login
az ad sp create-for-rbac --name "{your alias}-tests" --role Contributor

コマンドは、一連の資格情報を出力します。環境変数で、、AZURE_CLIENT_IDおよび AZURE_CLIENT_SECRET のAZURE_TENANT_ID値を設定します。

テストプロキシサーバーを起動する

テストを機能させるには、テストプロキシを使用できる必要があります。これは、テストがから TestProxyTestBase拡張されるときに自動的に行われます。メソッドは com.azure.core.test.TestProxyTestBase#setupTestProxy() 、テストプロキシの開始を担当します。

public class MyTest extends TestProxyTestBase {
    // method in TestProxyTestBase 
    @BeforeAll
    public static void setupTestProxy(TestInfo testInfo) {
        // Start the test proxy server
        testProxyManager.startProxy();
    }
}

これがテストプロキシまたはテストプロキシ自体を起動する方法の詳細については、テストプロキシ移行ガイドを参照してください。

テストを作成する

各 SDK には、名前付けパターン {ServiceName}ClientTest.java{ServiceName}AsyncClientTest.javaとを使用して、testsディレクトリ (sdk/{service}/{package}/tests) にクライアント同期と非同期テストを含める必要があります。 {ServiceName}ClientTestは同期クライアントのテストを担当し{ServiceName}AsyncClientTest、は非同期クライアントのテストを担当します。 {ServiceName}ClientTestとの両方が {ServiceName}AsyncClientTest を{ServiceName}ClientTestBase拡張し、クラスをTestProxyTestBase拡張します。 {ServiceName}ClientTestBaseは、クライアントの初期化、テストデータの準備、サニタイザー/マッシャーの登録などを担当します (この例では、デモンストレーションのために Tables SDK を使用します)。


/**
 * Set the AZURE_TEST_MODE environment variable to either PLAYBACK or RECORD to determine if tests are playback or
 * record. By default, tests are run in playback mode.
 */
public static class ClientTests extends TestProxyTestBase {

    /**
     * Use JUnit annotation here for your testcase
     */
    public void testMethodName() {
        HttpPipelineBuilder pipelineBuilder = new HttpPipelineBuilder();
        if (interceptorManager.isRecordMode()) {
            // Add a policy to record network calls.
            pipelineBuilder.policies(interceptorManager.getRecordPolicy());
        }
        if (interceptorManager.isPlaybackMode()) {
            // Use a playback client when running in playback mode
            pipelineBuilder.httpClient(interceptorManager.getPlaybackClient());
        }

        Mono<HttpResponse> response =
            pipelineBuilder.build().send(new HttpRequest(HttpMethod.GET, "http://bing.com"));

        // Validate test results.
        assertEquals(200, response.block().getStatusCode());
    }

ライブまたは再生テストモードを構成する

"ライブ" テストは、実際の Azure リソースに要求を行うテストを指します。 "再生" テストでは、各テストの記録が必要です。テストプロキシは、各テスト中に行われる要求/応答と、記録内の要求/応答を比較します。

ライブテストを実行するには、環境変数 AZURE_TEST_MODE をに LIVE設定します。再生中にテストを実行するには、をにPLAYBACK設定AZURE_TEST_MODEするか、未設定のままにします。

テストの実行と記録

環境変数 AZURE_TEST_MODE をに RECORD 設定して、レコードモードでテストを実行します。

テストの実行が完了したら、パッケージディレクトリにという src/test/resources/session-records フォルダーが存在する必要があります。このフォルダー内の各記録は、 .json ファイルの名前と一致するテストの実行中に生成された HTTP トラフィックをキャプチャするファイルになります。環境変数を AZURE_TEST_MODE "PLAYBACK" に設定し、テストを再実行する場合は、もう一度合格する必要があります。今回は再生モードで (つまり、json 記録ファイルから記録されたデータを使用して、実際の HTTP 要求を行わずに) 渡す必要があります。

リポジトリ外の記録を使用してテストを実行する

テスト対象のパッケージがリポジトリの外部azure-sdk-for-javaに記録を格納している場合 (つまり、記録移行ガイドに従い、パッケージにファイルが含まれているassets.json場合)、ディレクトリにtestsフォルダーはありませんsrc/test/resources/session-records。代わりに、パッケージの assets.json ファイルは、記録を含むリポジトリ内の azure-sdk-assets タグを指します。これが推奨される記録構成です。

ライブテストまたは再生テストの実行は、前のセクションと同じ構成です。唯一の変更は、記録を更新するプロセスです。

テスト記録を更新する

前提条件

ターゲットライブラリは、テストプロキシを使用するように既に移行されています。
Git バージョン > 2.30.0 は、マシン上とパスでです。 Git は、スクリプトとテストプロキシによって使用されます。
グローバル Git 構成設定は、とに対してuser.nameuser.email構成されます。
- これらの設定は、環境変数 GIT_COMMIT_OWNER と GIT_COMMIT_EMAIL、それぞれ (ご使用の環境またはローカル .env ファイル) で設定されます。
GitHub グループの azure-sdk-write メンバーシップ。

テストが実行され、環境変数 AZURE_TEST_MODE がに RECORD設定されている場合、テスト記録が更新されます。ただし、記録自体はリポジトリに azure-sdk-for-java 存在しなくなったため、これらの更新はリポジトリのルートにある git から除外された .assets フォルダーに反映されます。

フォルダーには .assets 、ランダムな名前を持つ 1 つ以上のディレクトリが含まれています。各ディレクトリは、記録を含む git ディレクトリです。 cdパッケージの記録を含むフォルダーに移動した場合は、を使用git statusして、行った記録の更新を表示できます。他 git のコマンドを使用することもできます。たとえば、 git diff {file name} 特定のファイルの変更を表示したり git restore {file name} 、保持したくない変更を元に戻したりすることもできます。

パッケージの記録を含むディレクトリを見つけるには、フォルダー内のファイルを.breadcrumb.assets開きます。このファイルには、各行にパッケージ名が一覧表示され、その後に記録ディレクトリ名が続きます。例えば：

sdk/{service}/{package}/assets.json;2Wm2Z87545;java/{service}/{package}_<10-character-commit-SHA>

この場合の記録ディレクトリは、 2Wm2Z87452 つのセミコロンの間の文字列です。

記録更新プログラムが正しく表示されることを確認したら、コマンドを test-proxy push -a assets.json 使用して、これらの記録をリポジトリに azure-sdk-assets プッシュできます。このコマンドには、パッケージassets.jsonのファイルへの相対パスを指定する必要があります。たとえば、リポジトリのルートから次のようになります azure-sdk-for-java 。

test-proxy push -a sdk/{service}/{package}/assets.json

このスクリプトに提供できる動詞は、"push"、"restore"、および "reset" です。

push: 記録の更新を新しい資産リポジトリタグにプッシュし、の assets.jsonタグポインターを更新します。
restore: のタグポインター assets.jsonに基づいて、資産リポジトリから記録をフェッチします。
reset: のタグポインター assets.jsonに基づいて、記録に対する保留中の変更をすべて破棄します。

記録をプッシュすると、パッケージの assets.json ファイルが更新され、更新プログラムを含む新 Tag しいが指し示されます。アップストリームリポジトリの記録ポインターを更新するために、プル要求にこの assets.json 更新プログラムを含めます。

シークレットをサニタイズする

.jsonレコードモードでテストを実行して作成されたファイルには、承認の詳細、アカウント名、共有アクセス署名、およびその他のシークレットを含めることができます。記録はパブリック GitHub リポジトリに含まれており、リポジトリにコミットする前に、これらの記録からシークレットを削除することが重要です。

シークレットが記録に書き込まれないようにするには、主に次の 2 つの方法があります。

RecordingRedactor の使用と同様の既定のサニタイザーは、既定のやり直しのために TestProxyUtils に既に登録されています。

カスタムサニタイザーは、特定のサービスサニタイズニーズに対処するためにtest_proxy_sanitizer&interceptorManager.addSanitizers()メソッドを使用して[TestProxySanitizer]追加できます。たとえば、応答本文から json キー modelId の値を編集するためのカスタムサニタイザーを登録すると、次のようになります。


List<TestProxySanitizer> customSanitizer = new ArrayList<>();
// sanitize value for key: "modelId" in response json body
customSanitizer.add(
    new TestProxySanitizer("$..modelId", "REPLACEMENT_TEXT", TestProxySanitizerType.BODY_KEY));

if (interceptorManager.isRecordMode()) {
    // Add a policy to record network calls.
    pipelineBuilder.policies(interceptorManager.getRecordPolicy());
}
if (interceptorManager.isPlaybackMode()) {
    // Use a playback client when running in playback mode
    pipelineBuilder.httpClient(interceptorManager.getPlaybackClient());
    // Add matchers only in playback mode
    interceptorManager.addMatchers(Arrays.asList(new CustomMatcher()
        .setHeadersKeyOnlyMatch(Arrays.asList("x-ms-client-request-id"))));
}
if (!interceptorManager.isLiveMode()) {
    // Add sanitizers when running in playback or record mode
    interceptorManager.addSanitizers(customSanitizer);
}

注: サニタイザーは、再生クライアントまたはレコードポリシーが登録された後にのみ追加する必要があります。たとえば、 TableClientTestBase クラスを確認します。

テストプロキシでサポートされているサニタイザーの詳細については、こちらを参照してください。

記録される内容のカスタマイズ

一部のテストでは、意味のない大きな要求本文が送信され、セッションレコードに格納できません。特定の要求の要求本文の格納を無効にするには、注釈を RecordWithoutRequestBody テストメソッドに追加します。

例

トラブルシューティング

これらの SDK でバグが発生した場合は、問題を報告するか、 Azure Java SDK の StackOverflow をチェックアウトしてください。

次のステップ

その他の便利なパッケージは次のとおりです。

azure-core: すべてのクライアントライブラリで使用されるコアクラスと機能が含まれています。

共同作成

このリポジトリへの投稿の詳細については、[投稿ガイド][cg]を参照してください。

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。これは、CLA を使用するすべてのリポジトリで 1 回だけ行う必要があります。

このプロジェクトでは、[Microsoft Open Source Code of Conduct][coc] を採用しています。詳細については、[行動規範に関する FAQ][coc_faq] を参照するか、その他の質問やコメントに問い合わせてください opencode@microsoft.com 。

インプレッション数

次の方法で共有

Java 用 Azure Core テスト共有ライブラリ - バージョン 1.22.0

目次

作業の開始

主要な概念

テストを記述または実行する

テストリソースを設定する

資格情報を構成する

テストプロキシサーバーを起動する

テストを作成する

ライブまたは再生テストモードを構成する

テストの実行と記録

リポジトリ外の記録を使用してテストを実行する

テスト記録を更新する

前提条件

シークレットをサニタイズする

記録される内容のカスタマイズ

例

トラブルシューティング

次のステップ

共同作成

フィードバック

その他のリソース

次の方法で共有

Java 用 Azure Core テスト共有ライブラリ - バージョン 1.22.0

目次

作業の開始

主要な概念

テストを記述または実行する

テスト リソースを設定する

資格情報を構成する

テスト プロキシ サーバーを起動する

テストを作成する

ライブまたは再生テスト モードを構成する

テストの実行と記録

リポジトリ外の記録を使用してテストを実行する

テスト記録を更新する

前提条件

シークレットをサニタイズする

記録される内容のカスタマイズ

例

トラブルシューティング

次のステップ

共同作成

フィードバック

その他のリソース

テストリソースを設定する

テストプロキシサーバーを起動する

ライブまたは再生テストモードを構成する