次の方法で共有


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

このライブラリには、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 作成するには:

  1. 特定のサービスと必要な構成用の Azure Resource Management テンプレートを作成します。 これを行うには、 ポータル でリソースを作成し、最後の手順 (確認と作成) で [自動化用テンプレートのダウンロード] をクリックします。
  2. このテンプレートを、 test-resources.json パッケージ (sdk/<my-service>/test-resources.json) ファイルを含むディレクトリの下のファイルに保存します。 例として Table の を参照できます。
  3. のグループ化された "resources" セクションに、追加のリソースの test-resources.json テンプレートを追加します ()。
  4. "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を少なくとも設定する必要があります。

  1. 変数をAZURE_SUBSCRIPTION_IDorganizationのサブスクリプション ID に設定します。 Azure Portal の [サブスクリプション] ブレードの [概要] セクションで確認できます。
  2. テスト サービス プリンシパルの AZURE_TENANT_IDAZURE_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_SECRETAZURE_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_OWNERGIT_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 つの方法があります。

  1. RecordingRedactor の使用と同様の既定のサニタイザーは、既定のやり直しのために TestProxyUtils に既に登録されています。
  2. カスタムサニタイザーは、特定のサービスサニタイズニーズに対処するために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

インプレッション数