Biblioteca compartida de Prueba básica de Azure para Java: versión 1.22.0

Artículo
11/03/2023

Esta biblioteca contiene clases principales que se usan para probar las bibliotecas cliente del SDK de Azure.

Las pruebas más recientes del SDK usan el proxy de prueba de Azure SDK Tools para grabar y reproducir interacciones HTTP. Para migrar desde testBase existente para usar el proxy de prueba o para obtener más información sobre el uso del proxy de prueba, consulte la guía de migración del proxy de prueba.

Introducción

Para usar este paquete, agregue lo siguiente a la pom.xml.


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

Conceptos clave

Ejecutar pruebas en Record modo: para registrar significa interceptar cualquier solicitud HTTP, almacenarla en un archivo y, a continuación, almacenar la respuesta recibida del recurso activo destinado originalmente.
Ejecutar pruebas en Playback modo: para reproducir significa interceptar cualquier solicitud HTTP y responder a ella con la respuesta almacenada de una solicitud coincidente grabada previamente.
Ejecutar pruebas en Live modo: para ejecutar live significa no interceptar ninguna solicitud HTTP y enviarlos directamente al servicio de Azure.
Sanear información confidencial: la información confidencial significa que el contenido, como contraseñas, identificadores únicos o información personal, debe limpiarse de las grabaciones.
TestProxyTestBase: clase de prueba base que crea y InterceptorManager permite que la prueba se use test-proxy para ejecutar la prueba. Reproduce los datos de la sesión de prueba o registra la sesión de prueba.
InterceptorManager: clase que realiza un seguimiento de las llamadas de red leyendo los datos de un registro de sesión de prueba existente o grabando las llamadas de red en memoria. Los registros de sesión de prueba se guardan o leen de ".assets/{library-level}/src/test/resources/session-records/TestFileName.testName}.json".
TestProxyRecordPolicy: directiva de canalización que registra las llamadas de red mediante .test-proxy
TestProxyPlaybackClient: cliente HTTP que reproduce respuestas de los datos registrados del registro de sesión mediante el proxy de prueba.

Escritura o ejecución de pruebas

Configuración de recursos de prueba

Los recursos de Azure activos serán necesarios para ejecutar pruebas en vivo y generar grabaciones.

Si aún no ha configurado un test-resources.json archivo para la implementación de recursos de prueba o quiere usar recursos de prueba propios, solo puede configurar las credenciales para dirigirse a estos recursos en su lugar.

Para crear un test-resources.json archivo:

Cree una plantilla de Administración de recursos de Azure para su servicio específico y la configuración que necesite. Esto se puede hacer en el portal mediante la creación de un recurso y, en el último paso (Revisar y crear), haga clic en "Descargar una plantilla para la automatización".
Guarde esta plantilla en un test-resources.json archivo en el directorio que contiene el archivo del paquete (sdk/<my-service>/test-resources.json). Puede hacer referencia a Table como ejemplo.
Agregue plantillas para cualquier recurso adicional en una sección agrupada "resources" de test-resources.json (ejemplo).
Agregue una "outputs" sección a test-resources.json que describa las variables de entorno necesarias para acceder a estos recursos (ejemplo).

Configuración de credenciales

Las pruebas del SDK de Java usan EnvironmentVariables para almacenar las credenciales de prueba.

Si usa un New-TestResources script de /eng/common/TestResources, el script debe generar las variables de entorno necesarias para ejecutar pruebas dinámicas para el servicio. Después de almacenar estas variables en las variables de entorno local (con el formato adecuado), las credenciales y las variables de configuración de prueba se establecerán en el entorno al ejecutar pruebas.

Si el servicio no tiene un test-resources.json archivo para la implementación de prueba, deberá establecer variables de entorno para AZURE_SUBSCRIPTION_ID, AZURE_TENANT_ID, AZURE_CLIENT_IDy AZURE_CLIENT_SECRET como mínimo.

Establezca la variable en el AZURE_SUBSCRIPTION_ID identificador de suscripción de la organización. Puede encontrarlo en la sección "Información general" de la hoja "Suscripciones" en Azure Portal.
Defina , AZURE_TENANT_IDAZURE_CLIENT_IDy AZURE_CLIENT_SECRET de una entidad de servicio de prueba. Si no tiene una entidad de servicio, use el comando az ad sp create-for-rbac de la CLI de Azure ( lo ideal es usar el alias como prefijo de nombre de la entidad de servicio):

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

El comando generará un conjunto de credenciales. Establezca valores para AZURE_TENANT_ID, AZURE_CLIENT_IDy AZURE_CLIENT_SECRET en las variables de entorno.

Iniciar el servidor proxy de prueba

El proxy de prueba debe estar disponible para que las pruebas funcionen; Esto se realiza automáticamente cuando la prueba se extiende desde TestProxyTestBase. El com.azure.core.test.TestProxyTestBase#setupTestProxy() método es responsable de iniciar el proxy de prueba.

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

Para más información sobre cómo se inicia el proxy de prueba o el propio proxy de prueba, consulte la guía de migración del proxy de prueba.

Escribir las pruebas

Cada uno de los SDK debe incluir la sincronización de cliente y las pruebas asincrónicas en su tests directorio (sdk/{service}/{package}/tests) con el patrón {ServiceName}ClientTest.java de nomenclatura y {ServiceName}AsyncClientTest.java. {ServiceName}ClientTest será responsable de probar el cliente sincrónico y {ServiceName}AsyncClientTest será responsable de probar el cliente asincrónico. y {ServiceName}ClientTest ambos {ServiceName}AsyncClientTest extenderán la {ServiceName}ClientTestBase clase que, a continuación, extiende la TestProxyTestBase clase . {ServiceName}ClientTestBase será responsable de inicializar los clientes, preparar los datos de prueba, registrar correctores o buscadores de coincidencias, etc. (en este ejemplo, usamos el SDK de tablas para demostrar):


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

Configuración del modo de prueba de reproducción o en vivo

Las pruebas "activas" hacen referencia a las pruebas que realizan solicitudes a recursos reales de Azure. Las pruebas de "reproducción" requieren una grabación para cada prueba; el proxy de prueba comparará las solicitudes y respuestas que se realizarían durante cada prueba con solicitudes o respuestas en la grabación.

Para ejecutar pruebas dinámicas, establezca la variable AZURE_TEST_MODELIVEde entorno en . Para ejecutar pruebas en reproducción, establezca AZURE_TEST_MODEPLAYBACK en o deje sin establecer.

Ejecución y registro de pruebas

Establezca la variable AZURE_TEST_MODERECORD de entorno en para ejecutar las pruebas en modo de registro.

Una vez finalizada la ejecución de las pruebas, debe haber una carpeta denominada src/test/resources/session-records en el directorio del paquete. Cada grabación de esta carpeta será un .json archivo que captura el tráfico HTTP que se generó mientras se ejecuta la prueba que coincide con el nombre del archivo. Si establece la AZURE_TEST_MODE variable de entorno en "PLAYBACK" y vuelve a ejecutar las pruebas, deben pasar de nuevo, esta vez, en modo de reproducción (es decir, sin realizar solicitudes HTTP reales, mediante los datos grabados del archivo de grabación JSON).

Ejecución de pruebas con grabaciones fuera del repositorio

Si el paquete que se está probando almacena sus grabaciones fuera del azure-sdk-for-java repositorio, es decir, se ha seguido la guía de migración de grabación y el paquete contiene un assets.json archivo, no habrá una src/test/resources/session-records carpeta en el tests directorio. En su lugar, el archivo del assets.json paquete apuntará a una etiqueta en el azure-sdk-assets repositorio que contiene las grabaciones. Esta es la configuración de grabación preferida.

La ejecución de pruebas en vivo o de reproducción es la misma en esta configuración que en la sección anterior. Los únicos cambios son para el proceso de actualización de grabaciones.

Actualizar grabaciones de prueba

Requisitos previos

La biblioteca de destino ya está migrada para usar el proxy de prueba.
La versión > 2.30.0 de Git está en el equipo y en la ruta de acceso. Git lo usa el script y el proxy de prueba.
Las opciones de configuración de Git globales se configuran para user.name y .user.email
- Esta configuración también se establece con variables GIT_COMMIT_OWNER de entorno y GIT_COMMIT_EMAIL, respectivamente (en el entorno o en el archivo local .env ).
Pertenencia al grupo de azure-sdk-write GitHub.

Las grabaciones de prueba se actualizarán si se ejecutan pruebas y la variable AZURE_TEST_MODE de entorno se establece en RECORD. Dado que las grabaciones ya no están en el azure-sdk-for-java repositorio, estas actualizaciones se reflejarán en una carpeta excluida .assets de Git en la raíz del repositorio.

La .assets carpeta contiene uno o varios directorios con nombres aleatorios, que cada uno es un directorio git que contiene grabaciones. Si se encuentra cd en la carpeta que contiene las grabaciones del paquete, puede usar git status para ver las actualizaciones de grabación que ha realizado. También puede usar otros git comandos; por ejemplo, git diff {file name} para ver cambios de archivo específicos o git restore {file name} para deshacer los cambios que no desea conservar.

Para buscar el directorio que contiene las grabaciones del paquete, abra el .breadcrumb archivo en la .assets carpeta . Este archivo enumera un nombre de paquete en cada línea, seguido del nombre del directorio de grabación; por ejemplo:

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

En este caso, el directorio de grabación es 2Wm2Z8745, la cadena entre los dos punto y coma.

Después de comprobar que las actualizaciones de grabación son correctas, puede usar el test-proxy push -a assets.json comando para insertar estas grabaciones en el azure-sdk-assets repositorio. Este comando debe proporcionarse una ruta de acceso relativa al archivo del assets.json paquete. Por ejemplo, desde la raíz del azure-sdk-for-java repositorio:

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

Los verbos que se pueden proporcionar a este script son "push", "restore" y "reset":

push: inserta actualizaciones de grabación en una nueva etiqueta de repositorio de recursos y actualiza el puntero de etiqueta en assets.json.
restore: captura las grabaciones del repositorio de recursos, en función del puntero de etiqueta en assets.json.
reset: descarta los cambios pendientes en las grabaciones, en función del puntero de etiqueta en assets.json.

Después de insertar las grabaciones, el assets.json archivo del paquete se actualizará para que apunte a un nuevo Tag que contenga las actualizaciones. Incluya esta assets.json actualización en cualquier solicitud de incorporación de cambios para actualizar el puntero de grabaciones en el repositorio ascendente.

Sanear secretos

Los .json archivos creados a partir de la ejecución de pruebas en modo de registro pueden incluir detalles de autorización, nombres de cuenta, firmas de acceso compartido y otros secretos. Las grabaciones se incluyen en nuestro repositorio público de GitHub, lo que nos hace importante quitar los secretos de estas grabaciones antes de confirmarlos en el repositorio.

Hay dos formas principales de evitar que los secretos se escriban en grabaciones:

Los saneadores predeterminados, de forma similar al uso de RecordingRedactor ya están registrados en TestProxyUtils para redacciones predeterminadas.

Los saneadores personalizados se pueden agregar mediante [TestProxySanitizer]test_proxy_sanitizer&interceptorManager.addSanitizers() método para abordar necesidades específicas de saneamiento del servicio. Por ejemplo, el registro de un saneador personalizado para censurar el valor de json key modelId del cuerpo de la respuesta es similar al siguiente:


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

Nota: Los saneadores solo se deben agregar una vez registrado el cliente de reproducción o la directiva de registro. Examine la clase TableClientTestBase por ejemplo.

Puede encontrar información detallada sobre los saneadores admitidos por el proxy de prueba aquí.

Personalización de lo que se registra

Algunas pruebas envían cuerpos de solicitud grandes que no son significativos y no deben almacenarse en los registros de sesión. Para deshabilitar el almacenamiento del cuerpo de la solicitud para una solicitud específica, agregue la RecordWithoutRequestBody anotación al método de prueba.

Ejemplos

Solución de problemas

Si encuentra algún error con estos SDK, envíe problemas a través de problemas o desproteger StackOverflow para el SDK de Java de Azure.

Pasos siguientes

Otros paquetes útiles son:

azure-core: contiene las clases principales y la funcionalidad que usan todas las bibliotecas cliente.

Contribuciones

Para obtener más información sobre cómo contribuir a este repositorio, consulte la [guía de contribución][cg].

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo tendrá que hacerlo una vez en todos los repositorios mediante nuestra CLA.

Este proyecto ha adoptado el [Código de conducta de código abierto de Microsoft][coc]. Para obtener más información, consulte [Preguntas más frecuentes sobre el código de conducta][coc_faq] o póngase en contacto con opencode@microsoft.com cualquier pregunta o comentario adicionales.

Impresiones

Compartir a través de