Biblioteca compartilhada de teste do Azure Core para Java – versão 1.22.0

Essa biblioteca contém classes principais usadas para testar bibliotecas de clientes do SDK do Azure.

Os testes mais recentes do SDK utilizam o Proxy de Teste das Ferramentas do SDK do Azure para registrar e reproduzir interações HTTP. Para migrar do TestBase existente para usar o proxy de teste ou para saber mais sobre como usar o proxy de teste, consulte o guia de migração de proxy de teste.

Sumário

• Guia de Introdução
• Principais conceitos
• Gravar ou executar testes
  • Configurar recursos de teste
  • Configurar credenciais
  • Iniciar o servidor proxy de teste
  • Escrever seus testes
  • Configurar o modo de teste ao vivo ou de reprodução
  • Executar e registrar testes
  • Executar testes com gravações fora do repositório
  • Limpar segredos
    • Personalizando o que é gravado
• Solução de problemas
• Próximas etapas
• Contribuição

Introdução

Para usar esse pacote, adicione o seguinte ao seupom.xml.

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

Principais conceitos

• Executar testes no Record modo: para registrar significa interceptar qualquer solicitação HTTP, armazená-la em um arquivo e armazenar a resposta recebida do recurso dinâmico que foi originalmente direcionado.
• Executar testes no Playback modo: para reproduzir significa interceptar qualquer solicitação HTTP e responder a ela com a resposta armazenada de uma solicitação correspondente registrada anteriormente.
• Executar testes no Live modo: para executar live significa não interceptar nenhuma solicitação HTTP e enviá-las diretamente ao serviço do Azure.
• Limpar informações confidenciais: informações confidenciais significam que conteúdo como senhas, identificadores exclusivos ou informações pessoais devem ser limpos das gravações.
• TestProxyTestBase: classe de teste base que cria um InterceptorManager e permite que o teste seja usado test-proxy para executar o teste. Ele reproduz os dados da sessão de teste ou registra a sessão de teste.
• InterceptorManager: uma classe que controla as chamadas de rede lendo os dados de um registro de sessão de teste existente ou gravando as chamadas de rede na memória. Os registros de sessão de teste são salvos ou lidos em ".assets/{library-level}/src/test/resources/session-records/TestFileName.testName}.json".
• TestProxyRecordPolicy: política de pipeline que registra chamadas de rede usando o test-proxy.
• TestProxyPlaybackClient: cliente HTTP que reproduz respostas dos dados gravados do registro de sessão usando o proxy de teste.

Gravar ou executar testes

Configurar recursos de teste

Os recursos dinâmicos do Azure serão necessários para executar testes ao vivo e produzir gravações.

Se você ainda não configurou um test-resources.json arquivo para a implantação de recursos de teste e/ou deseja usar recursos de teste próprios, basta configurar credenciais para direcionar esses recursos.

Para criar um test-resources.json arquivo:

1. Crie um Modelo de Gerenciamento de Recursos do Azure para seu serviço específico e a configuração necessária. Isso pode ser feito no Portal criando um recurso e, na última etapa (Examinar + Criar), clicando em "Baixar um modelo para automação".
2. Salve esse modelo em um test-resources.json arquivo no diretório que contém o arquivo de pacote (sdk/<my-service>/test-resources.json). Você pode se referir a Table's como um exemplo.
3. Adicione modelos para quaisquer recursos adicionais em uma seção agrupada "resources" de test-resources.json (exemplo).
4. Adicione uma "outputs" seção para test-resources.json que descreva todas as variáveis de ambiente necessárias para acessar esses recursos (exemplo).

Configurar credenciais

Os testes do SDK do Java usam EnvironmentVariables para armazenar credenciais de teste.

Se estiver usando um New-TestResources script de /eng/common/TestResources, o script deverá gerar todas as variáveis de ambiente necessárias para executar testes dinâmicos para o serviço. Depois de armazenar essas variáveis em suas variáveis de ambiente local , com formatação apropriada , suas credenciais e variáveis de configuração de teste serão definidas em seu ambiente ao executar testes.

Se o serviço não tiver um test-resources.json arquivo para implantação de teste, você precisará definir variáveis de ambiente para AZURE_SUBSCRIPTION_ID, AZURE_TENANT_ID, AZURE_CLIENT_IDe AZURE_CLIENT_SECRET no mínimo.

1. Defina a AZURE_SUBSCRIPTION_ID variável como a ID da assinatura da sua organização. Você pode encontrá-lo na seção "Visão geral" da folha "Assinaturas" no Portal do Azure.
2. Defina o AZURE_TENANT_ID, AZURE_CLIENT_IDe AZURE_CLIENT_SECRET de uma entidade de serviço de teste. Se você não tiver uma entidade de serviço, use o comando az ad sp create-for-rbac da CLI do Azure ( idealmente, usando seu alias como prefixo de nome da entidade de serviço):

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

O comando produzirá um conjunto de credenciais. Defina valores para AZURE_TENANT_ID, AZURE_CLIENT_IDe AZURE_CLIENT_SECRET em suas variáveis de ambiente.

Iniciar o servidor proxy de teste

O proxy de teste deve estar disponível para que os testes funcionem; isso é feito automaticamente quando o teste é estendido de TestProxyTestBase. O com.azure.core.test.TestProxyTestBase#setupTestProxy() método é responsável por iniciar o proxy de teste.

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

Para obter mais detalhes sobre como isso inicia o proxy de teste ou o proxy de teste em si, consulte o guia de migração de proxy de teste.

Escrever seus testes

Cada um dos SDKs deve incluir a sincronização do cliente e o teste assíncrono em seu tests diretório (sdk/{service}/{package}/tests) com o padrão {ServiceName}ClientTest.java de nomenclatura e {ServiceName}AsyncClientTest.java. O {ServiceName}ClientTest será responsável por testar o cliente síncrono e o {ServiceName}AsyncClientTest será responsável por testar o cliente assíncrono. O {ServiceName}ClientTest e os {ServiceName}AsyncClientTest dois estenderão o {ServiceName}ClientTestBase que, em seguida, estende a TestProxyTestBase classe . O {ServiceName}ClientTestBase será responsável por inicializar os clientes, preparar dados de teste, registrar sanitizadores/correspondentes etc. (neste exemplo, usamos o SDK de Tabelas para fins de demonstração):

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

Configurar o modo de teste ao vivo ou de reprodução

Testes "dinâmicos" referem-se a testes que fazem solicitações para recursos reais do Azure. Os testes de "Reprodução" exigem uma gravação para cada teste; o proxy de teste comparará as solicitações/respostas que seriam feitas durante cada teste com solicitações/respostas na gravação.

Para executar testes ao vivo, defina a variável AZURE_TEST_MODE de ambiente como LIVE. Para executar testes na reprodução, defina AZURE_TEST_MODE como PLAYBACK ou deixe-o desconjunto.

Executar e registrar testes

Defina a variável AZURE_TEST_MODE de ambiente como RECORD para executar seus testes no modo de registro.

Depois que os testes terminarem de ser executados, deve haver uma pasta chamada src/test/resources/session-records no diretório do pacote. Cada gravação nessa pasta será um .json arquivo que captura o tráfego HTTP que foi gerado durante a execução do teste que corresponde ao nome do arquivo. Se você definir a AZURE_TEST_MODE variável de ambiente como " PLAYBACK" e executar novamente os testes, eles deverão passar novamente -- desta vez, no modo de reprodução (ou seja, sem fazer solicitações HTTP reais, usando os dados gravados do arquivo de gravação json).

Executar testes com gravações fora do repositório

Se o pacote que está sendo testado armazenar suas gravações fora do azure-sdk-for-java repositório , ou seja, o guia de migração de gravação foi seguido e o pacote contém um assets.json arquivo – não haverá uma src/test/resources/session-records pasta no tests diretório. Em vez disso, o arquivo do assets.json pacote apontará para uma marca no azure-sdk-assets repositório que contém as gravações. Essa é a configuração de gravação preferencial.

A execução de testes ao vivo ou de reprodução é a mesma nessa configuração que era na seção anterior. As únicas alterações são no processo de atualização de gravações.

Atualizar gravações de teste

Pré-requisitos

• A biblioteca de destino já está migrada para usar o proxy de teste.
• A versão > do Git 2.30.0 é para no computador e no caminho. O Git é usado pelo proxy de script e teste.
• As configurações globais do git são definidas para user.name e user.email.
  • Essas configurações também são definidas GIT_COMMIT_OWNER com variáveis de ambiente e GIT_COMMIT_EMAIL, respectivamente (em seu ambiente ou no arquivo local .env ).
• Associação no grupo do azure-sdk-write GitHub.

As gravações de teste serão atualizadas se os testes forem executados e a variável AZURE_TEST_MODE de ambiente estiver definida como RECORD. No entanto, como as gravações em si não estão mais no azure-sdk-for-java repositório, essas atualizações serão refletidas em uma pasta excluída .assets pelo git na raiz do repositório.

A .assets pasta contém um ou mais diretórios com nomes aleatórios, que cada um é um diretório git que contém gravações. Se você cd entrar na pasta que contém as gravações do pacote, poderá usar git status para exibir as atualizações de gravação feitas. Você também pode usar outros git comandos; por exemplo, git diff {file name} para ver alterações específicas de arquivo ou git restore {file name} para desfazer alterações que não deseja manter.

Para localizar o diretório que contém as gravações do pacote, abra o .breadcrumb arquivo na .assets pasta . Esse arquivo lista um nome de pacote em cada linha, seguido pelo nome do diretório de gravação; por exemplo:

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

O diretório de gravação nesse caso é 2Wm2Z8745, a cadeia de caracteres entre os dois ponto e vírgula.

Depois de verificar se as atualizações de gravação parecem corretas, você pode usar o test-proxy push -a assets.json comando para enviar essas gravações por push para o azure-sdk-assets repositório. Esse comando deve receber um caminho relativo para o arquivo do assets.json pacote. Por exemplo, na raiz do azure-sdk-for-java repositório:

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

Os verbos que podem ser fornecidos a esse script são "push", "restore" e "reset":

• push: envia atualizações de gravação por push para uma nova marca de repositório de ativos e atualiza o ponteiro de marca no assets.json.
• restore: busca gravações do repositório de ativos, com base no ponteiro de marca em assets.json.
• reset: descarta as alterações pendentes nas gravações, com base no ponteiro de marca em assets.json.

Depois de enviar suas gravações por push, o assets.json arquivo do pacote será atualizado para apontar para um novo Tag que contém as atualizações. Inclua essa assets.json atualização em qualquer solicitação de pull para atualizar o ponteiro de gravações no repositório upstream.

Limpar segredos

Os .json arquivos criados com base na execução de testes no modo de registro podem incluir detalhes de autorização, nomes de conta, assinaturas de acesso compartilhado e outros segredos. As gravações são incluídas em nosso repositório Público do GitHub, tornando importante remover todos os segredos dessas gravações antes de as comprometermos com o repositório.

Há duas maneiras principais de impedir que segredos sejam gravados em gravações:

1. Os sanitizadores padrão, semelhantes ao uso do RecordingRedactor, já estão registrados no TestProxyUtils para redações padrão.
2. Os sanitizadores personalizados podem ser adicionados usando [TestProxySanitizer]test_proxy_sanitizer&interceptorManager.addSanitizers() método para atender a necessidades específicas de limpeza de serviço. Por exemplo, registrar um desinfetante personalizado para redigir o valor de json key modelId do corpo da resposta é semelhante ao seguinte:.

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

Observação: os sanitizadores só devem ser adicionados depois que o cliente de reprodução ou a política de registro for registrado. Examine a classe TableClientTestBase , por exemplo.

Informações detalhadas sobre os sanitizadores compatíveis com o Proxy de Teste podem ser encontradas aqui.

Personalizando o que é gravado

Alguns testes enviam corpos de solicitação grandes que não são significativos e não devem ser armazenados nos registros de sessão. Para desabilitar o armazenamento do corpo da solicitação para uma solicitação específica, adicione a RecordWithoutRequestBody anotação ao método de teste.

Exemplos

Solução de problemas

Se você encontrar bugs com esses SDKs, registre problemas por meio de Problemas ou check-out do StackOverflow para o SDK do Java do Azure.

Próximas etapas

Outros pacotes úteis são:

• azure-core: contém classes principais e funcionalidades usadas por todas as bibliotecas de cliente.

Participante

Para obter detalhes sobre como contribuir para esse repositório, consulte o [guia de contribuição][cg].

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios usando nosso CLA.

Este projeto adotou o [Código de Conduta de Software Livre da Microsoft][coc]. Para obter mais informações, consulte as perguntas frequentes sobre o [Código de Conduta][coc_faq] ou entre em contato opencode@microsoft.com com perguntas ou comentários adicionais.