Freigegebene Azure Core Test-Bibliothek für Java – Version 1.22.0

Artikel
11/03/2023

Diese Bibliothek enthält Kernklassen, die zum Testen von Azure SDK-Clientbibliotheken verwendet werden.

Neuere SDK-Tests verwenden den Azure SDK Tools-Testproxy zum Aufzeichnen und Wiedergeben von HTTP-Interaktionen. Informationen zum Migrieren von vorhandenem TestBase zur Verwendung des Testproxys oder weitere Informationen zur Verwendung des Testproxys finden Sie im Leitfaden zur Testproxymigration.

Erste Schritte

Um dieses Paket zu verwenden, fügen Sie Ihrem pom.xmlFolgendes hinzu.


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

Wichtige Begriffe

Ausführen von Tests im Record Modus: Um die Mittel aufzuzeichnen, um http-Anforderungen abzufangen, speichern Sie sie in einer Datei, und speichern Sie dann die Antwort, die von der Liveressource empfangen wurde, die ursprünglich als Ziel galt.
Ausführen von Tests im Playback Modus: Für Wiedergabe bedeutet, jede HTTP-Anforderung abzufangen und mit der gespeicherten Antwort einer zuvor aufgezeichneten übereinstimmenden Anforderung darauf zu reagieren.
Ausführen von Tests im Live Modus: Liveausführung bedeutet, keine HTTP-Anforderungen abzufangen und sie direkt an den Azure-Dienst zu senden.
Vertrauliche Informationen bereinigen: Vertrauliche Informationen bedeuten, dass Inhalte wie Kennwörter, eindeutige Bezeichner oder persönliche Informationen aus den Aufzeichnungen bereinigt werden sollten.
TestProxyTestBase: Basistestklasse, die eine InterceptorManager erstellt und die Verwendung test-proxy des Tests zum Ausführen des Tests ermöglicht. Es gibt entweder Testsitzungsdaten zurück oder zeichnet die Testsitzung auf.
InterceptorManager: Eine Klasse, die Netzwerkaufrufe nachverfolgt, indem sie entweder die Daten aus einem vorhandenen Testsitzungsdatensatz liest oder die Netzwerkaufrufe im Arbeitsspeicher aufzeichnet. Testsitzungsdatensätze werden gespeichert oder aus ".assets/{library-level}/src/test/resources/session-records/TestFileName.testName.testName}.json" gelesen.
TestProxyRecordPolicy: Pipelinerichtlinie, die Netzwerkaufrufe mithilfe von test-proxyerfasst.
TestProxyPlaybackClient: HTTP-Client, der Antworten aus den aufgezeichneten Daten des Sitzungsdatensatzes mithilfe des Testproxys wiedergibt.

Schreiben oder Ausführen von Tests

Einrichten von Testressourcen

Azure-Liveressourcen sind erforderlich, um Livetests auszuführen und Aufzeichnungen zu erstellen.

Wenn Sie noch keine Datei für die test-resources.json Testressourcenbereitstellung eingerichtet haben und/oder eigene Testressourcen verwenden möchten, können Sie stattdessen einfach Anmeldeinformationen für diese Ressourcen konfigurieren.

So erstellen Sie eine test-resources.json Datei:

Erstellen Sie eine Azure Resource Management-Vorlage für Ihren spezifischen Dienst und die konfiguration, die Sie benötigen. Dies kann im Portal erfolgen, indem Sie eine Ressource erstellen und im letzten Schritt (Überprüfen + Erstellen) auf "Vorlage zur Automatisierung herunterladen" klicken.
Speichern Sie diese Vorlage in einer test-resources.json Datei unter dem Verzeichnis, das Ihre Paketdatei (sdk/<my-service>/test-resources.json) enthält. Sie können als Beispiel auf Tabellen verweisen.
Fügen Sie Vorlagen für alle zusätzlichen Ressourcen in einem gruppierten "resources" Abschnitt von hinzu test-resources.json (Beispiel).
Fügen Sie einen "outputs" Abschnitt hinzu, in test-resources.json dem alle Umgebungsvariablen beschrieben werden, die für den Zugriff auf diese Ressourcen erforderlich sind (Beispiel).

Konfigurieren von Anmeldeinformationen

Java SDK-Tests werden zum Speichern von Testanmeldeinformationen verwendet EnvironmentVariables .

Wenn Sie ein New-TestResources Skript aus /eng/common/TestResources verwenden, sollte das Skript alle Umgebungsvariablen ausgeben, die zum Ausführen von Livetests für den Dienst erforderlich sind. Nachdem Sie diese Variablen in Ihren lokalen Umgebungsvariablen mit entsprechender Formatierung gespeichert haben, werden Ihre Anmeldeinformationen und Testkonfigurationsvariablen in Ihrer Umgebung festgelegt, wenn Tests ausgeführt werden.

Wenn Ihr Dienst keine Datei für die test-resources.json Testbereitstellung hat, müssen Sie Umgebungsvariablen mindestens für AZURE_SUBSCRIPTION_ID, AZURE_TENANT_ID, AZURE_CLIENT_IDund AZURE_CLIENT_SECRET festlegen.

Legen Sie die Variable auf die AZURE_SUBSCRIPTION_ID Abonnement-ID Ihres organization fest. Sie finden sie im Abschnitt "Übersicht" des Blatts "Abonnements" im Azure-Portal.
Definieren Sie den AZURE_TENANT_ID, AZURE_CLIENT_IDund AZURE_CLIENT_SECRET eines Testdienstprinzipals. Wenn Sie über keinen Dienstprinzipal verfügen, verwenden Sie den Befehl az ad sp create-for-rbac der Azure CLI (idealerweise mit Ihrem Alias als Namenspräfix des Dienstprinzipals):

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

Der Befehl gibt eine Reihe von Anmeldeinformationen aus. Legen Sie Werte für AZURE_TENANT_ID, AZURE_CLIENT_IDund AZURE_CLIENT_SECRET in Ihren Umgebungsvariablen fest.

Starten des Testproxyservers

Der Testproxy muss verfügbar sein, damit die Tests funktionieren. dies erfolgt automatisch, wenn der Test von TestProxyTestBaseerweitert wird. Die com.azure.core.test.TestProxyTestBase#setupTestProxy() -Methode ist für das Starten des Testproxys verantwortlich.

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

Weitere Informationen zum Starten des Testproxys oder des Testproxys finden Sie im Leitfaden zur Testproxymigration.

Erstellen der Tests

Alle SDKs sollten die Clientsynchronisierung und asynchrone Tests in ihrem tests Verzeichnis (sdk/{service}/{package}/tests) mit dem Benennungsmuster {ServiceName}ClientTest.java und {ServiceName}AsyncClientTest.javaenthalten. Der {ServiceName}ClientTest ist für das Testen des synchronen Clients verantwortlich, und der {ServiceName}AsyncClientTest ist für das Testen des asynchronen Clients verantwortlich. Die {ServiceName}ClientTest und die {ServiceName}AsyncClientTest beiden erweitern das {ServiceName}ClientTestBase , was dann die TestProxyTestBase -Klasse erweitert. Der {ServiceName}ClientTestBase ist für die Initialisierung der Clients, das Vorbereiten von Testdaten, die Registrierung von Desinfektions-/Abgleichsprogrammen usw. verantwortlich (in diesem Beispiel verwenden wir das Tabellen-SDK zur Veranschaulichung):


/**
 * 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());
    }

Konfigurieren des Live- oder Wiedergabetestmodus

"Live"-Tests beziehen sich auf Tests, die Anforderungen an tatsächliche Azure-Ressourcen stellen. "Wiedergabe"-Tests erfordern eine Aufzeichnung für jeden Test. Der Testproxy vergleicht die Anforderungen/Antworten, die während jedes Tests mit Anforderungen/Antworten in der Aufzeichnung erfolgen würden.

Legen Sie zum Ausführen von Livetests die Umgebungsvariable AZURE_TEST_MODE auf fest LIVE. Um Tests in der Wiedergabe auszuführen, legen Sie auf PLAYBACK festAZURE_TEST_MODE, oder lassen Sie es nicht festgelegt.

Ausführen und Aufzeichnen von Tests

Legen Sie die Umgebungsvariable AZURE_TEST_MODE auf fest RECORD , um Ihre Tests im Datensatzmodus auszuführen.

Nachdem die Tests ausgeführt wurden, sollte in Ihrem Paketverzeichnis ein Ordner namens vorhanden src/test/resources/session-records sein. Jede Aufzeichnung in diesem Ordner ist eine .json Datei, die den HTTP-Datenverkehr erfasst, der beim Ausführen des Tests generiert wurde, der dem Namen der Datei entspricht. Wenn Sie die Umgebungsvariable AZURE_TEST_MODE auf "PLAYBACK" festlegen und Tests erneut ausführen, sollten sie erneut bestanden werden – diesmal im Wiedergabemodus (d. h. ohne tatsächliche HTTP-Anforderungen unter Verwendung der aufgezeichneten Daten aus der JSON-Aufzeichnungsdatei).

Ausführen von Tests mit Out-of-Repo-Aufzeichnungen

Wenn das zu testende Paket seine Aufzeichnungen außerhalb des azure-sdk-for-java Repositorys speichert ( d. h. der Leitfaden zur Aufzeichnungsmigration wurde befolgt und das Paket enthält eine assets.json Datei ), befindet sich src/test/resources/session-records kein Ordner im tests Verzeichnis. Stattdessen zeigt die Datei des Pakets assets.json auf ein Tag im Repository, das azure-sdk-assets die Aufzeichnungen enthält. Dies ist die bevorzugte Aufzeichnungskonfiguration.

Die Ausführung von Live- oder Wiedergabetests ist in dieser Konfiguration identisch wie im vorherigen Abschnitt. Die einzigen Änderungen sind der Prozess der Aktualisierung von Aufzeichnungen.

Aktualisieren von Testaufzeichnungen

Voraussetzungen

Die Zielbibliothek wurde bereits migriert, um den Testproxy zu verwenden.
Git-Version > 2.30.0 ist auf dem Computer und im Pfad. Git wird vom Skript- und Testproxy verwendet.
Globale Git-Konfigurationseinstellungen werden für user.name und user.emailkonfiguriert.
- Diese Einstellungen werden auch mit Umgebungsvariablen GIT_COMMIT_OWNER bzw GIT_COMMIT_EMAIL. festgelegt (in Ihrer Umgebung oder Ihrer lokalen .env Datei).
Mitgliedschaft in der azure-sdk-write GitHub-Gruppe.

Testaufzeichnungen werden aktualisiert, wenn Tests ausgeführt werden und die Umgebungsvariable AZURE_TEST_MODE auf RECORDfestgelegt ist. Da sich die Aufzeichnungen selbst jedoch nicht mehr im azure-sdk-for-java Repository befinden, werden diese Updates in einem ordner mit Git-Ausschluss .assets im Stammverzeichnis des Repositorys widergespiegelt.

Der .assets Ordner enthält mindestens ein Verzeichnis mit zufälligen Namen, wobei es sich jeweils um ein Git-Verzeichnis mit Aufzeichnungen handelt. Wenn Sie cd sich in den Ordner mit den Aufzeichnungen Ihres Pakets einfügen, können Sie die von Ihnen vorgenommenen Aufzeichnungsupdates anzeigen git status . Sie können auch andere git Befehle verwenden, z. B git diff {file name} . zum Anzeigen bestimmter Dateiänderungen oder git restore {file name} zum Rückgängigmachen von Änderungen, die Sie nicht beibehalten möchten.

Um das Verzeichnis zu finden, das die Aufzeichnungen Ihres Pakets enthält, öffnen Sie die .breadcrumb Datei im .assets Ordner. Diese Datei listet in jeder Zeile einen Paketnamen auf, gefolgt vom Namen des Aufzeichnungsverzeichnisses. Zum Beispiel:

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

Das Aufzeichnungsverzeichnis ist 2Wm2Z8745in diesem Fall die Zeichenfolge zwischen den beiden Semikolons.

Nachdem Sie überprüft haben, ob Ihre Aufzeichnungsupdates korrekt aussehen, können Sie den test-proxy push -a assets.json Befehl verwenden, um diese Aufzeichnungen per Push an das azure-sdk-assets Repository zu übertragen. Diesem Befehl sollte ein relativer Pfad zur Datei Ihres Pakets assets.json bereitgestellt werden. Beispiel: Aus dem Stamm des azure-sdk-for-java Repositorys:

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

Die Verben, die für dieses Skript bereitgestellt werden können, sind "push", "restore" und "reset":

push: Push: Pusht Aufzeichnungsupdates an ein neues Ressourcenrepositorytag und aktualisiert den Tagzeiger in assets.json.
Restore: Ruft Aufzeichnungen aus dem Ressourcenrepository ab, basierend auf dem Tagzeiger in assets.json.
zurücksetzen: Verwirft alle ausstehenden Änderungen an Aufzeichnungen basierend auf dem Tagzeiger in assets.json.

Nachdem Sie Ihre Aufzeichnungen per Push übertragen haben, wird die assets.json Datei für Ihr Paket aktualisiert, sodass sie auf ein neues Tag verweist, das die Updates enthält. Fügen Sie dieses assets.json Update in jeden Pull Request ein, um den Aufzeichnungszeiger im Upstream Repository zu aktualisieren.

Geheimnisse bereinigen

Die .json Dateien, die aus der Ausführung von Tests im Datensatzmodus erstellt wurden, können Autorisierungsdetails, Kontonamen, Freigegebene Zugriffssignaturen und andere Geheimnisse enthalten. Die Aufzeichnungen sind in unserem öffentlichen GitHub-Repository enthalten, sodass es für uns wichtig ist, alle Geheimnisse aus diesen Aufzeichnungen zu entfernen, bevor sie in das Repository übertragen werden.

Es gibt zwei Hauptmethoden, um zu schützen, dass Geheimnisse nicht in Aufzeichnungen geschrieben werden:

Standarddesinfektionsmittel, ähnlich wie die Verwendung von RecordingRedactor, sind bereits in den TestProxyUtils für Standardraktionen registriert.

Benutzerdefinierte Desinfektionsmittel können mithilfe [TestProxySanitizer]test_proxy_sanitizer-Methode&interceptorManager.addSanitizers() hinzugefügt werden, um bestimmte Anforderungen an die Dienstbereinigung zu erfüllen. Die Registrierung eines benutzerdefinierten Desinfektionsmittels zum Redacting des Werts des JSON-Schlüssels modelId aus dem Antworttext sieht beispielsweise wie folgt aus:.


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);
}

Hinweis: Sanitizer dürfen erst hinzugefügt werden, wenn der Wiedergabeclient oder die Datensatzrichtlinie registriert wurde. Sehen Sie sich beispielsweise die TableClientTestBase-Klasse an.

Ausführliche Informationen zu den vom Testproxy unterstützten Desinfektionsmodulen finden Sie hier.

Anpassen der Aufzeichnungen

Einige Tests senden große Anforderungstexte, die nicht aussagekräftig sind und nicht in den Sitzungsdatensätzen gespeichert werden sollten. Um das Speichern des Anforderungstexts für eine bestimmte Anforderung zu deaktivieren, fügen Sie die RecordWithoutRequestBody Anmerkung zur Testmethode hinzu.

Beispiele

Problembehandlung

Wenn Bei diesen SDKs Fehler auftreten, datein Sie Probleme über Issues oder checken Sie StackOverflow for Azure Java SDK aus.

Nächste Schritte

Weitere nützliche Pakete sind:

azure-core: Enthält Kernklassen und Funktionen, die von allen Clientbibliotheken verwendet werden.

Mitwirken

Ausführliche Informationen zum Mitwirken zu diesem Repository finden Sie im [Mitwirkenden Leitfaden][cg].

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys mit unserer CLA tun.

Dieses Projekt hat den [Microsoft Open Source Code of Conduct][coc] übernommen. Weitere Informationen finden Sie unter [Häufig gestellte Fragen zum Verhaltenskodex][coc_faq] oder wenden Sie sich an opencode@microsoft.com weitere Fragen oder Kommentare.

Aufrufe

Freigeben über