Teste de interface do usuário ui-testing
Os testes de interface do usuário personalizados são um recurso opcional que permite criar e executar automaticamente testes na interface do usuário para seus aplicativos.
Visão geral custom-ui-testing
O AEM fornece um conjunto integrado de quality gates (portais de qualidade) do Cloud Manager para garantir atualizações tranquilas para aplicativos personalizados. Em especial, os portais de teste de TI já promovem a criação e a automação de testes personalizados usando as APIs do AEM.
Os testes de interface são compactados em uma imagem do Docker para permitir uma variedade de opções de idiomas e estruturas (como Cypress, Selenium, Java e Maven, além do JavaScript). Além disso, um projeto de testes de interface do usuário pode ser facilmente gerado usando o Arquétipo de Projetos AEM.
A Adobe incentiva o uso do Cypress, pois oferece recarregamento em tempo real e espera automática, o que ajuda a economizar tempo e melhorar a produtividade durante os testes. O Cypress também fornece uma sintaxe simples e intuitiva, facilitando a aprendizagem e o uso, até mesmo para aqueles que são novos em testes.
Os testes de interface são executados como parte de uma porta de qualidade específica para cada pipeline do Cloud Manager que contém uma etapa de **Teste de interface personalizada**nos pipelines de produção ou, opcionalmente, nos pipelines de não produção. Quaisquer testes de interface, incluindo regressão e novas funcionalidades, permitem que erros sejam detectados e relatados.
Diferentemente dos testes funcionais personalizados, que são testes HTTP escritos em Java, os testes de interface podem ser uma imagem do Docker com testes escritos em qualquer linguagem, desde que sigam as convenções definidas na seção Compilação de testes de interface.
Introdução aos testes de interface get-started-ui-tests
Esta seção descreve as etapas necessárias para a configuração dos testes de interface para execução no Cloud Manager.
-
Decida sobre a linguagem de programação que deseja usar.
-
Para Cypress, use o código de exemplo do repositório de Exemplos de teste do AEM.
-
Para o JavaScript e o WDIO, use o código de exemplo que é gerado automaticamente na pasta
ui.tests
do seu repositório do Cloud Manager.note note NOTE Se o repositório foi criado antes de o Cloud Manager criar automaticamente as pastas ui.tests
, você também poderá gerar a versão mais recente usando o Arquétipo de Projetos do AEM. -
Para Java e WebDriver, use o código de exemplo do repositório de exemplos de teste do AEM.
-
Para outras linguagens de programação, consulte a seção Criação de testes de interface deste documento para configurar o projeto de teste.
-
-
Certifique-se de que o teste da interface esteja ativado de acordo com a seção Adesão do cliente deste documento.
-
Desenvolva seus casos de teste e execute-os localmente.
-
Confirmar seu código no repositório do Cloud Manager e executar um pipeline do Cloud Manager.
Compilação de testes de interface do usuário building-ui-tests
Um projeto Maven gera um contexto de compilação do Docker. Este contexto de construção do Docker descreve como criar uma imagem do Docker que contenha os testes de interface, que o Cloud Manager usa para gerar uma imagem do Docker contendo os testes de interface reais.
Esta seção descreve as etapas necessárias para adicionar um projeto de testes de interface ao seu repositório.
Gerar um contexto de compilação do Docker generate-docker-build-context
Para gerar um contexto de construção do Docker, você precisará de um módulo Maven que:
- Produza um arquivo que contenha um
Dockerfile
e qualquer outro arquivo necessário para criar a imagem do Docker em seus testes. - Marque o arquivo com o classificador
ui-test-docker-context
.
A maneira mais simples de fazer isso é configurar o Plug-in de compilação do Maven para criar o arquivo de contexto de compilação do Docker e atribuir o classificador correto a ele.
Você pode compilar testes de interface do usuário com diferentes tecnologias e estruturas, mas esta seção presume que o projeto seja apresentado de uma maneira semelhante à descrita a seguir.
├── Dockerfile
├── assembly-ui-test-docker-context.xml
├── pom.xml
├── test-module
│ ├── package.json
│ ├── index.js
│ └── wdio.conf.js
└── wait-for-grid.sh
O arquivo pom.xml
controla a compilação Maven. Adicione uma execução ao Plug-in de compilação do Maven semelhante ao mostrado a seguir.
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-assembly-plugin</artifactId>
<configuration>
<descriptors>
<descriptor>${project.basedir}/assembly-ui-test-docker-context.xml</descriptor>
</descriptors>
<tarLongFileMode>gnu</tarLongFileMode>
</configuration>
<executions>
<execution>
<id>make-assembly</id>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
</execution>
</executions>
</plugin>
Esta execução instrui o Plug-in de compilação Maven a criar um arquivo com base nas instruções contidas em assembly-ui-test-docker-context.xml
, chamado de descritor de compilação no jargão do plug-in. O descritor de compilação lista todos os arquivos que devem fazer parte do arquivamento.
<assembly>
<id>ui-test-docker-context</id>
<includeBaseDirectory>false</includeBaseDirectory>
<formats>
<format>tar.gz</format>
</formats>
<fileSets>
<fileSet>
<directory>${basedir}</directory>
<includes>
<include>Dockerfile</include>
<include>wait-for-grid.sh</include>
</includes>
</fileSet>
<fileSet>
<directory>${basedir}/test-module</directory>
<excludes>
<exclude>node/**</exclude>
<exclude>node_modules/**</exclude>
<exclude>reports/**</exclude>
</excludes>
</fileSet>
</fileSets>
</assembly>
O descritor de compilação instrui o plug-in a criar um arquivamento do tipo .tar.gz
e atribuir o classificador ui-test-docker-context
a ele. Além disso, ele lista os arquivos que devem ser incluídos no arquivamento, incluindo o seguinte:
- Um
Dockerfile
, obrigatório para criar a imagem do Docker - O script
wait-for-grid.sh
, cujos objetivos são descritos abaixo - Os testes reais de interface do usuário, implementados por um projeto Node.js na pasta
test-module
O descritor de compilação também exclui alguns arquivos que podem ser gerados durante a execução local dos testes de interface do usuário. Isso garante que um arquivo menor seja gerado, e consequentemente, resulta em compilações mais rápidas.
O arquivamento que contém o contexto de compilação do Docker é selecionado automaticamente pelo Cloud Manager, que criará a imagem do Docker contendo seus testes durante os pipelines de implantação. Eventualmente, o Cloud Manager executará a imagem do Docker para executar os testes de interface do usuário em seu aplicativo.
A compilação deve produzir zero ou um arquivamento. Se produzir zero arquivamento, a etapa de teste será aprovada por padrão. Se a compilação produzir mais de um arquivamento, o arquivamento selecionado será não determinístico.
Adesão do cliente customer-opt-in
Para que o Cloud Manager compile e execute seus testes de interface, é necessário aderir a esse recurso adicionando um arquivo ao repositório.
- O nome do arquivo deve ser
testing.properties
. - O conteúdo do arquivo deve ser
ui-tests.version=1
. - O arquivo deve estar no submódulo Maven para testes de interface, próximo do arquivo
pom.xml
do submódulo de testes de interface. - O arquivo deve estar na raiz do arquivo de compilação
tar.gz
.
A compilação e a execução dos testes de interface será ignorada se esse arquivo não estiver presente.
Para incluir um arquivo testing.properties
no artefato de compilação, adicione a instrução include
no arquivo assembly-ui-test-docker-context.xml
.
[...]
<includes>
<include>Dockerfile</include>
<include>wait-for-grid.sh</include>
<include>testing.properties</include> <!-- opt-in test module in Cloud Manager -->
</includes>
[...]
Se estiver usando os exemplos fornecidos pela Adobe:
-
Para a pasta
ui.tests
baseada em JavaScript, gerada com base no Arquétipo de projeto do AEM, você pode executar o comando abaixo para adicionar a configuração necessária.code language-shell echo "ui-tests.version=1" > testing.properties if ! grep -q "testing.properties" "assembly-ui-test-docker-context.xml"; then awk -v line=' <include>testing.properties</include>' '/<include>wait-for-grid.sh<\/include>/ { printf "%s\n%s\n", $0, line; next }; 1' assembly-ui-test-docker-context.xml > assembly-ui-test-docker-context.xml.new && mv assembly-ui-test-docker-context.xml.new assembly-ui-test-docker-context.xml fi
-
As amostras de teste Cypress e Java Selenium fornecidas pelo Adobe já têm o sinalizador de aceitação definido.
Gravação de testes da interface do usuário writing-ui-tests
Esta seção descreve as convenções que a imagem do Docker que contém seus testes de interface do usuário deve seguir. A imagem do Docker é criada a partir do contexto de compilação do Docker descrito na seção anterior.
Variáveis de ambiente environment-variables
As seguintes variáveis de ambiente são passadas para a imagem do Docker em tempo de execução, dependendo da estrutura.
SELENIUM_BASE_URL
http://my-ip:4444
SELENIUM_BROWSER
chrome
AEM_AUTHOR_URL
http://my-ip:4502/context-path
AEM_AUTHOR_USERNAME
admin
AEM_AUTHOR_PASSWORD
admin
AEM_PUBLISH_URL
http://my-ip:4503/context-path
AEM_PUBLISH_USERNAME
admin
AEM_PUBLISH_PASSWORD
admin
REPORTS_PATH
/usr/src/app/reports
UPLOAD_URL
http://upload-host:9090/upload
PROXY_HOST
proxy-host
PROXY_HTTPS_PORT
8071
PROXY_HTTP_PORT
8070
PROXY_CA_PATH
/path/to/root_ca.pem
PROXY_OBSERVABILITY_PORT
8081
PROXY_RETRY_ATTEMPTS
12
PROXY_RETRY_DELAY
5
Os exemplos de teste da Adobe fornecem funções auxiliares para acessar os parâmetros de configuração:
- Cypress: use a função padrão
Cypress.env('VARIABLE_NAME')
- JavaScript: Consulte o módulo
lib/config.js
- Java: consulte a classe
Config
Gerar relatórios de teste generate-test-reports
A imagem do Docker deve gerar relatórios de teste no formato XML JUnit e salvá-los no caminho especificado pela variável de ambiente REPORTS_PATH
. O formato XML JUnit é um formato amplamente usado para relatar resultados de testes. Se a imagem do Docker usar Java e Maven, os módulos de teste padrão, como o Plug-in Maven Surefire e o Plug-in Maven Failsafe poderão gerar os relatórios imediatamente.
Se a imagem do Docker for implementada com outras linguagens de programação ou executores de teste, verifique a documentação das ferramentas escolhidas para saber como gerar relatórios XML JUnit.
request.log
.Pré-requisitos prerequisites
- Os testes no Cloud Manager são executados usando um usuário administrador técnico.
- A infraestrutura em container com escopo para testes funcionais apresenta os seguintes limites:
Detalhes específicos do Selenium
Aguardar o Selenium estar pronto waiting-for-selenium
Antes de os testes começarem, é responsabilidade da imagem do Docker garantir que o servidor Selenium esteja funcionando. Aguardar o serviço Selenium é um processo de duas etapas.
- Leia a URL do serviço Selenium na variável de ambiente
SELENIUM_BASE_URL
. - Consulte em intervalos regulares o endpoint de status exposto pela API do Selenium.
Quando o endpoint de status do Selenium responder com uma resposta positiva, os testes poderão ser iniciados.
Os exemplos de teste de interface da Adobe lidam com isso por meio do script wait-for-grid.sh
, que é executado na inicialização do Docker e inicia a execução do teste real somente depois que a grade está pronta.
Capturar imagens de tela e vídeos capture-screenshots
A imagem do Docker pode gerar saídas de teste adicionais (por exemplo, capturas de tela ou vídeos) e salvá-las no caminho especificado pela variável de ambiente REPORTS_PATH
. Qualquer arquivo encontrado abaixo de REPORTS_PATH
é incluído no arquivo de resultados de teste.
Os exemplos de teste fornecidos pela Adobe criam, por padrão, capturas de tela de qualquer teste com falha.
Você pode usar as funções auxiliares para criar capturas de tela nos testes.
- JavaScript: comando takeScreenshot
- Java: comandos
Se um arquivo de resultados de teste for criado durante a execução de um teste de interface, você poderá baixá-lo do Cloud Manager usando o botão Download Details
na etapa Testes de interface personalizados.
Fazer upload de arquivos upload-files
Os testes às vezes devem carregar arquivos no aplicativo que está sendo testado. Para manter a implantação do Selenium flexível em relação aos testes, não é possível fazer upload de um ativo diretamente no Selenium. Em vez disso, o upload de um arquivo exige as etapas descritas a seguir.
-
Faça upload do arquivo na URL especificado pela variável de ambiente
UPLOAD_URL
.-
O upload deve ser realizado em uma solicitação POST com um formulário multipart.
-
O formulário multipart deve ter um único campo de arquivo.
-
É equivalente a
curl -X POST ${UPLOAD_URL} -F "data=@file.txt"
. -
Consulte a documentação e as bibliotecas da linguagem de programação usada na imagem do Docker para saber como executar essa solicitação HTTP.
-
Os exemplos de teste da Adobe fornecem funções auxiliares para fazer o upload de arquivos:
- JavaScript: consulte o comando getFileHandleForUpload.
- Java: consulte a classe FileHandler.
-
-
Se o upload for bem-sucedido, a solicitação retornará uma resposta
200 OK
do tipotext/plain
.- O conteúdo da resposta é um identificador de arquivo opaco.
- Você pode usar esse identificador no lugar de um caminho de arquivo em um elemento
<input>
para testar os uploads de arquivo em seu aplicativo.
Detalhes específicos do Cypress
Configurar proxy HTTP
O ponto de entrada do contêiner Docker precisa verificar o valor da variável de ambiente PROXY_HOST
.
Se esse valor estiver vazio, nenhuma etapa adicional será necessária e os testes deverão ser executados sem o uso do proxy HTTP.
Se não estiver vazio, o script de ponto de entrada precisa:
-
Configure uma conexão proxy HTTP para executar testes de interface. Isso pode ser feito exportando a variável de ambiente
HTTP_PROXY
que é criada usando os seguintes valores:- Host do proxy, que é fornecido pela variável
PROXY_HOST
- Porta de proxy, que é fornecida pela variável
PROXY_HTTPS_PORT
ouPROXY_HTTP_PORT
(a variável com um valor não vazio será usada)
- Host do proxy, que é fornecido pela variável
-
Defina o certificado CA que será usado na conexão com o proxy HTTP. Sua localização é fornecida pela variável
PROXY_CA_PATH
.- Isso pode ser feito exportando a variável de ambiente
NODE_EXTRA_CA_CERTS
.
- Isso pode ser feito exportando a variável de ambiente
-
Aguarde até que o proxy HTTP esteja pronto.
- Para verificar a preparação, as variáveis de ambiente
PROXY_HOST
,PROXY_OBSERVABILITY_PORT
,PROXY_RETRY_ATTEMPTS
ePROXY_RETRY_DELAY
podem ser usadas. - Você pode verificar usando uma solicitação cURL, certificando-se de instalar o cURL em seu
Dockerfile
.
- Para verificar a preparação, as variáveis de ambiente
Um exemplo de implementação pode ser encontrado no ponto de entrada do módulo de teste de amostra Cypress no GitHub.
Detalhes específicos do dramaturgo
Configurar proxy HTTP
Semelhante ao Cypress, os testes precisam usar o proxy HTTP se uma variável de ambiente PROXY_HOST
não vazia for fornecida.
Para fazer isso, as seguintes modificações precisam ser feitas.
Dockerfile
Instalar cURL e libnss3-tools
, que fornece certutil.
RUN apt -y update \
&& apt -y --no-install-recommends install curl libnss3-tools \
&& rm -rf /var/lib/apt/lists/*
Script de ponto de entrada
Inclua um script bash que, caso a variável de ambiente PROXY_HOST
seja fornecida, faça o seguinte:
- Exportar variáveis relacionadas ao proxy, como
HTTP_PROXY
eNODE_EXTRA_CA_CERTS
- Use
certutil
para instalar o certificado de autoridade de certificação de proxy para chromium - Aguarde até que o proxy HTTP esteja pronto (ou saia em caso de falha).
Exemplo de implementação:
# setup proxy environment variables and CA certificate
if [ -n "${PROXY_HOST:-}" ]; then
if [ -n "${PROXY_HTTPS_PORT:-}" ]; then
export HTTP_PROXY="https://${PROXY_HOST}:${PROXY_HTTPS_PORT}"
elif [ -n "${PROXY_HTTP_PORT:-}" ]; then
export HTTP_PROXY="http://${PROXY_HOST}:${PROXY_HTTP_PORT}"
fi
if [ -n "${PROXY_CA_PATH:-}" ]; then
echo "installing certificate"
mkdir -p $HOME/.pki/nssdb
certutil -d sql:$HOME/.pki/nssdb -A -t "CT,c,c" -n "EaaS Client Proxy Root" -i $PROXY_CA_PATH
export NODE_EXTRA_CA_CERTS=${PROXY_CA_PATH}
fi
if [ -n "${PROXY_OBSERVABILITY_PORT:-}" ] && [ -n "${HTTP_PROXY:-}" ]; then
echo "waiting for proxy"
curl --silent --retry ${PROXY_RETRY_ATTEMPTS:-3} --retry-connrefused --retry-delay ${PROXY_RETRY_DELAY:-10} \
--proxy ${HTTP_PROXY} --proxy-cacert ${PROXY_CA_PATH:-""} \
${PROXY_HOST}:${PROXY_OBSERVABILITY_PORT}
if [ $? -ne 0 ]; then
echo "proxy is not ready"
exit 1
fi
fi
fi
Configuração do dramaturgo
Modifique a configuração do playwright (por exemplo, em playwright.config.js
) para usar um proxy caso a variável de ambiente HTTP_PROXY
esteja definida.
Exemplo de implementação:
const proxyServer = process.env.HTTP_PROXY || ''
// enable proxy if set
if (proxyServer !== '') {
cfg.use.proxy = {
server: proxyServer,
}
}
Execução de testes locais de interface run-ui-tests-locally
Antes de ativar os testes de interface em um pipeline do Cloud Manager, é recomendável executá-los localmente no SDK do AEM as a Cloud Service ou em uma instância real do AEM as a Cloud Service.
Exemplo de teste do Cypress cypress-sample
-
Abra um shell e navegue até a pasta
ui.tests/test-module
no repositório -
Instale o Cypress e outros pré-requisitos
code language-shell npm install
-
Defina as variáveis de ambiente necessárias para a execução do teste
code language-shell export AEM_AUTHOR_URL=https://author-<program-id>-<environment-id>.adobeaemcloud.com export AEM_AUTHOR_USERNAME=<user> export AEM_AUTHOR_PASSWORD=<password> export AEM_PUBLISH_URL=https://publish-<program-id>-<environment-id>.adobeaemcloud.com export AEM_PUBLISH_USERNAME=<user> export AEM_PUBLISH_PASSWORD=<password> export REPORTS_PATH=target/
-
Execute testes com um dos comandos a seguir
code language-shell npm test # Using default Cypress browser npm run test-chrome # Using Google Chrome browser npm run test-firefox # Using Firefox browser
target/
do repositório.Exemplo de teste do JavaScript WebdriverIO javascript-sample
-
Abra um shell e navegue até a pasta
ui.tests
no repositório -
Execute o comando abaixo para iniciar os testes usando o Maven
code language-shell mvn verify -Pui-tests-local-execution \ -DAEM_AUTHOR_URL=https://author-<program-id>-<environment-id>.adobeaemcloud.com \ -DAEM_AUTHOR_USERNAME=<user> \ -DAEM_AUTHOR_PASSWORD=<password> \ -DAEM_PUBLISH_URL=https://publish-<program-id>-<environment-id>.adobeaemcloud.com \ -DAEM_PUBLISH_USERNAME=<user> \ -DAEM_PUBLISH_PASSWORD=<password>
- Isso inicia uma instância independente do Selenium e executa os testes nela.
- Os arquivos de log são armazenados na pasta
target/reports
do repositório. - Certifique-se de que sua máquina esteja executando a versão mais recente do Chrome, pois o teste baixa a versão mais recente do ChromeDriver automaticamente.
Exemplo de teste do Java Selenium WebDriver java-sample
-
Abra um shell e navegue até a pasta
ui.tests/test-module
no repositório -
Execute os comandos abaixo para iniciar os testes usando o Maven
code language-shell # Start selenium docker image (for x64 CPUs) docker run --platform linux/amd64 -d -p 4444:4444 selenium/standalone-chrome-debug:latest # Start selenium docker image (for ARM CPUs) docker run -d -p 4444:4444 seleniarm/standalone-chromium # Run the tests using the previously started Selenium instance mvn verify -Pui-tests-local-execution -DSELENIUM_BASE_URL=http://<server>:4444
target/reports
do repositório.