Bibliothèque partagée de test Azure Core pour Java - version 1.22.0

Article
11/03/2023

Cette bibliothèque contient des classes principales utilisées pour tester les bibliothèques clientes du KIT de développement logiciel (SDK) Azure.

Les tests sdk plus récents utilisent le proxy de test azure SDK Tools pour enregistrer et lire les interactions HTTP. Pour migrer à partir de TestBase existant pour utiliser le proxy de test, ou pour en savoir plus sur l’utilisation du proxy de test, reportez-vous au guide de migration du proxy de test.

Prise en main

Pour utiliser ce package, ajoutez ce qui suit à votre pom.xml.


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

Concepts clés

Exécuter des tests en Record mode : pour enregistrer, vous devez intercepter toute requête HTTP, la stocker dans un fichier, puis stocker la réponse reçue de la ressource dynamique qui a été initialement ciblée.
Exécuter des tests en Playback mode : la lecture signifie intercepter toute requête HTTP et y répondre avec la réponse stockée d’une demande de correspondance enregistrée précédemment.
Exécuter des tests en Live mode : exécuter en direct signifie ne pas intercepter de requête HTTP et les envoyer directement au service Azure.
Assainir les informations sensibles : les informations sensibles signifient que les contenus tels que les mots de passe, les identificateurs uniques ou les informations personnelles doivent être nettoyés des enregistrements.
TestProxyTestBase : classe de test de base qui crée un InterceptorManager et active le test à utiliser test-proxy pour l’exécution du test. Il lit les données de session de test ou enregistre la session de test.
InterceptorManager : classe qui effectue le suivi des appels réseau en lisant les données d’un enregistrement de session de test existant ou en enregistrant les appels réseau en mémoire. Les enregistrements de session de test sont enregistrés ou lus à partir de « .assets/{library-level}/src/test/resources/session-records/TestFileName.testName}.json ».
TestProxyRecordPolicy : stratégie de pipeline qui enregistre les appels réseau à l’aide de test-proxy.
TestProxyPlaybackClient : client HTTP qui lit les réponses à partir des données enregistrées de l’enregistrement de session à l’aide du proxy de test.

Écrire ou exécuter des tests

Configurer des ressources de test

Des ressources Azure en direct seront nécessaires pour exécuter des tests en direct et produire des enregistrements.

Si vous n’avez pas encore configuré de fichier pour le test-resources.json déploiement de ressources de test et/ou si vous souhaitez utiliser vos propres ressources de test, vous pouvez simplement configurer des informations d’identification pour cibler ces ressources à la place.

Pour créer un test-resources.json fichier :

Créez un modèle Azure Resource Management pour votre service spécifique et la configuration dont vous avez besoin. Pour ce faire, vous pouvez créer une ressource dans le portail et, à la toute dernière étape (Vérifier + Créer), cliquez sur « Télécharger un modèle pour l’automatisation ».
Enregistrez ce modèle dans un test-resources.json fichier sous le répertoire qui contient votre fichier de package (sdk/<my-service>/test-resources.json). Vous pouvez vous référer à Table comme exemple.
Ajoutez des modèles pour toutes les ressources supplémentaires dans une section groupée "resources" de test-resources.json (exemple).
Ajoutez une "outputs" section à test-resources.json qui décrit toutes les variables d’environnement nécessaires pour accéder à ces ressources (exemple).

Configurer les informations d’identification

Les tests du Kit de développement logiciel (SDK) Java utilisent EnvironmentVariables pour stocker les informations d’identification de test.

Si vous utilisez un New-TestResources script à partir de /eng/common/TestResources, le script doit générer toutes les variables d’environnement nécessaires pour exécuter des tests en direct pour le service. Après avoir stocké ces variables dans vos variables d’environnement locales avec une mise en forme appropriée, vos informations d’identification et vos variables de configuration de test seront définies dans votre environnement lors de l’exécution des tests.

Si votre service ne dispose pas d’un test-resources.json fichier pour le déploiement de test, vous devez définir des variables d’environnement pour AZURE_SUBSCRIPTION_ID, AZURE_TENANT_ID, AZURE_CLIENT_IDet AZURE_CLIENT_SECRET au minimum.

Définissez la variable sur l’ID AZURE_SUBSCRIPTION_ID d’abonnement de votre organization. Vous pouvez le trouver dans la section « Vue d’ensemble » du panneau « Abonnements » du portail Azure.
Définissez le AZURE_TENANT_ID, AZURE_CLIENT_IDet AZURE_CLIENT_SECRET d’un principal de service de test. Si vous n’avez pas de principal de service, utilisez la commande az ad sp create-for-rbac d’Azure CLI (dans l’idéal, en utilisant votre alias comme préfixe de nom du principal du service) :

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

La commande génère un ensemble d’informations d’identification. Définissez des valeurs pour AZURE_TENANT_ID, AZURE_CLIENT_IDet AZURE_CLIENT_SECRET dans vos variables d’environnement.

Démarrer le serveur proxy de test

Le proxy de test doit être disponible pour que les tests fonctionnent ; cette opération est effectuée automatiquement lorsque le test est étendu à partir de TestProxyTestBase. La com.azure.core.test.TestProxyTestBase#setupTestProxy() méthode est responsable du démarrage du proxy de test.

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

Pour plus d’informations sur la façon dont cela démarre le proxy de test ou le proxy de test lui-même, reportez-vous au guide de migration du proxy de test.

Écrire vos tests

Chacun des sdk doit inclure la synchronisation du client et le test asynchrone dans son répertoire (sdk/{service}/{package}/tests) avec le modèle {ServiceName}ClientTest.java de nommage et {ServiceName}AsyncClientTest.java.tests {ServiceName}ClientTest sera responsable du test du client synchrone et le {ServiceName}AsyncClientTest sera responsable du test du client asynchrone. le {ServiceName}ClientTest et les {ServiceName}AsyncClientTest deux étendent le {ServiceName}ClientTestBase qui étend ensuite la TestProxyTestBase classe. {ServiceName}ClientTestBase le sera responsable de l’initialisation des clients, de la préparation des données de test, de l’inscription des assainisseurs/correspondances, etc. (dans cet exemple, nous utilisons le SDK Tables à des fins de démonstration) :


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

Configurer le mode de test en direct ou de lecture

Les tests « en direct » font référence aux tests qui effectuent des demandes à des ressources Azure réelles. Les tests de lecture nécessitent un enregistrement pour chaque test ; le proxy de test compare les requêtes/réponses qui seront effectuées pendant chaque test avec les demandes/réponses dans l’enregistrement.

Pour exécuter des tests en direct, définissez la variable AZURE_TEST_MODE d’environnement sur LIVE. Pour exécuter des tests en lecture, définissez AZURE_TEST_MODEPLAYBACK sur ou laissez-le non défini.

Exécuter et enregistrer des tests

Définissez la variable AZURE_TEST_MODE d’environnement sur RECORD pour exécuter vos tests en mode enregistrement.

Une fois les tests terminés, il doit y avoir un dossier appelé src/test/resources/session-records dans le répertoire de votre package. Chaque enregistrement dans ce dossier est un .json fichier qui capture le trafic HTTP généré lors de l’exécution du test correspondant au nom du fichier. Si vous définissez la AZURE_TEST_MODE variable d’environnement sur « PLAYBACK » et réexécutez les tests, ils doivent ressaisis, cette fois, en mode lecture (c’est-à-dire sans effectuer de requêtes HTTP réelles, en utilisant les données enregistrées à partir du fichier d’enregistrement json).

Exécuter des tests avec des enregistrements hors dépôt

Si le package testé stocke ses enregistrements en dehors du azure-sdk-for-java dépôt (c’est-à-dire que le guide de migration d’enregistrement a été suivi et que le package contient un assets.json fichier), il n’y a pas de src/test/resources/session-records dossier dans le tests répertoire. Au lieu de cela, le fichier du assets.json package pointe vers une balise dans le azure-sdk-assets référentiel qui contient les enregistrements. Il s’agit de la configuration d’enregistrement par défaut.

L’exécution de tests en direct ou de lecture est la même dans cette configuration que dans la section précédente. Les seules modifications concernent le processus de mise à jour des enregistrements.

Mettre à jour les enregistrements de test

Prérequis

La bibliothèque ciblée est déjà migrée pour utiliser le proxy de test.
Git version > 2.30.0 est à sur l’ordinateur et dans le chemin d’accès. Git est utilisé par le script et le proxy de test.
Les paramètres de configuration git globaux sont configurés pour user.name et user.email.
- Ces paramètres sont également définis avec des variables GIT_COMMIT_OWNER d’environnement et GIT_COMMIT_EMAIL, respectivement (dans votre environnement ou votre fichier local .env ).
Appartenance au azure-sdk-write groupe GitHub.

Les enregistrements de test sont mis à jour si des tests sont exécutés et que la variable AZURE_TEST_MODE d’environnement est définie sur RECORD. Étant donné que les enregistrements eux-mêmes ne se trouvent plus dans le azure-sdk-for-java référentiel, ces mises à jour seront reflétées dans un dossier git-exclu .assets à la racine du référentiel.

Le .assets dossier contient un ou plusieurs répertoires avec des noms aléatoires, qui sont chacun un répertoire git contenant des enregistrements. Si vous cd accédez au dossier contenant les enregistrements de votre package, vous pouvez utiliser git status pour afficher les mises à jour d’enregistrement que vous avez effectuées. Vous pouvez également utiliser d’autres git commandes , par exemple, git diff {file name} pour afficher des modifications de fichier spécifiques ou git restore {file name} pour annuler les modifications que vous ne souhaitez pas conserver.

Pour rechercher le répertoire contenant les enregistrements de votre package, ouvrez le .breadcrumb fichier dans le .assets dossier. Ce fichier répertorie un nom de package sur chaque ligne, suivi du nom du répertoire d’enregistrement ; par exemple :

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

Le répertoire d’enregistrement dans ce cas est 2Wm2Z8745, la chaîne entre les deux points-virgules.

Après avoir vérifié que vos mises à jour d’enregistrement semblent correctes, vous pouvez utiliser la test-proxy push -a assets.json commande pour envoyer ces enregistrements au azure-sdk-assets dépôt. Cette commande doit être fournie un chemin d’accès relatif au fichier de assets.json votre package. Par exemple, à partir de la racine du azure-sdk-for-java référentiel :

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

Les verbes qui peuvent être fournis à ce script sont « push », « restore » et « reset » :

push : envoie (push) les mises à jour d’enregistrement vers une nouvelle balise de référentiel de ressources et met à jour le pointeur de balise dans assets.json.
restore : extrait les enregistrements à partir du référentiel de ressources, en fonction du pointeur de balise dans assets.json.
reset : ignore toutes les modifications en attente apportées aux enregistrements, en fonction du pointeur de balise dans assets.json.

Après avoir envoyé vos enregistrements, le assets.json fichier de votre package est mis à jour pour pointer vers un nouveau Tag qui contient les mises à jour. Incluez cette assets.json mise à jour dans n’importe quelle demande de tirage pour mettre à jour le pointeur des enregistrements dans le dépôt amont.

Assainir les secrets

Les .json fichiers créés à partir de l’exécution de tests en mode enregistrement peuvent inclure des détails d’autorisation, des noms de compte, des signatures d’accès partagé et d’autres secrets. Les enregistrements sont inclus dans notre dépôt GitHub public, ce qui nous oblige à supprimer tous les secrets de ces enregistrements avant de les valider dans le dépôt.

Il existe deux méthodes principales pour empêcher les secrets d’être écrits dans des enregistrements :

Les assainisseurs par défaut, similaires à l’utilisation de RecordingRedactor, sont déjà inscrits dans TestProxyUtils pour les rédactions par défaut.

Des assainisseurs personnalisés peuvent être ajoutés à l’aide [TestProxySanitizer]de test_proxy_sanitizer&interceptorManager.addSanitizers() méthode pour répondre à des besoins d’assainissement de service spécifiques. Par exemple, l’inscription d’un assainisseur personnalisé pour la suppression de la valeur de la clé json modelId à partir du corps de la réponse ressemble à ce qui suit :


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

Remarque : Les assainisseurs ne doivent être ajoutés qu’une fois que le client de lecture ou la stratégie d’enregistrement est inscrit. Examinez la classe TableClientTestBase par exemple.

Vous trouverez des informations détaillées sur les assainisseurs pris en charge par le proxy de test ici.

Personnalisation de ce qui est enregistré

Certains tests envoient des corps de requêtes volumineux qui ne sont pas significatifs et ne doivent pas être stockés dans les enregistrements de session. Pour désactiver le stockage du corps de la demande pour une requête spécifique, ajoutez l’annotation RecordWithoutRequestBody à la méthode de test.

Exemples

Dépannage

Si vous rencontrez des bogues avec ces SDK, veuillez déposer des problèmes via Problèmes ou vérifier StackOverflow pour le Kit de développement logiciel (SDK) Java Azure.

Étapes suivantes

D’autres packages utiles sont les suivants :

azure-core : contient les classes et fonctionnalités principales utilisées par toutes les bibliothèques clientes.

Contribution

Pour plus d’informations sur la contribution à ce dépôt, consultez le [guide de contribution][cg].

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous n’aurez besoin de le faire qu’une seule fois sur tous les dépôts à l’aide de notre CLA.

Ce projet a adopté le [Code de conduite Open Source Microsoft][coc]. Pour plus d’informations, consultez la [FAQ sur le code de conduite][coc_faq] ou contactez-nous opencode@microsoft.com pour toute question ou commentaire supplémentaire.

Impressions

Partager via