Provavelmente toda dor conhece essa dor - documentação irrelevante. Não importa o quanto a equipe tente, em projetos modernos lançaremos com tanta frequência que é quase impossível descrever todas as mudanças. Nossa equipe de teste, juntamente com analistas de sistemas, decidiu tentar revitalizar a documentação do projeto.
Os projetos da web do Alfa-Bank usam a estrutura de automação de teste do
Akita , usada para scripts BDD. Até o momento, a estrutura ganhou grande popularidade devido ao seu baixo limiar de entrada, usabilidade e capacidade de testar o layout. Mas decidimos ir além - com base nos cenários de teste descritos para gerar documentação, reduzindo bastante o tempo que os analistas gastam no eterno problema de atualizar a documentação.
De fato, junto com o Akita, já foi usado um plug-in de geração de documentação, que passou pelas etapas dos scripts e os carregou no formato html, mas para tornar esse documento popular, precisamos adicionar:
- Screenshots
- valores de variáveis (arquivo de configuração, contas de usuário, etc.);
- status e parâmetros de consulta.
Examinamos nosso plug-in existente, que era, de fato, um analisador estático e geramos documentação com base nos scripts descritos nos arquivos .feature. Decidimos adicionar alto-falantes e, para não tornar o plug-in parecido com um plug-in, decidimos escrever nossos próprios.
Primeiro, decidimos descobrir como podemos coletar capturas de tela e valores de variáveis usadas em scripts de teste a partir de arquivos de recursos. Tudo acabou sendo bastante simples. Pepino, ao executar testes para cada arquivo de recurso, cria um cucumber.json separado.
Dentro deste arquivo contém os seguintes objetos:
Nome e palavra-chave do caso de teste:
Matrizes de elementos - os scripts e as próprias etapas:
O campo de saída contém informações adicionais, por exemplo, variáveis - endereços, links, contas de usuário, etc .:
Os casamentos contêm capturas de tela que o selênio faz durante os testes:
Assim, precisamos apenas examinar os arquivos cucumber.json, coletar os nomes dos conjuntos de testes, scripts de teste, executar as etapas, coletar informações adicionais e capturas de tela.
Para que a documentação exiba solicitações que ocorrem em segundo plano ou para uma ação específica, tivemos que pedir ajuda aos desenvolvedores da frente. Com a ajuda do proxy, conseguimos capturar traceId, que gera solicitações de serviço front-end. Pelo mesmo traceId, os logs são gravados em elástico, de onde extraímos todos os parâmetros de consulta necessários para o relatório de teste e a documentação.
Como resultado, obtivemos um arquivo no formato Asciidoc - um formato de arquivo conveniente, um pouco mais complicado que o analógico de remarcação, mas tem muito mais opções de formatação (você pode inserir uma imagem ou tabela, o que não pode ser feito na remarcação).
Para converter o Asciidoc resultante para outros formatos, usamos o Ascii doctorj, que é a versão oficial da ferramenta Java AsciiDoctor. Como resultado, obtemos documentação pronta em formato html, que pode ser baixada em confluência, enviada a um colega ou colocada no repositório.
Como se conectar?
Agora, para gerar documentação de front-end para seu projeto, você só precisa conectar o plug-in de documentação a ele e, após executar todos os testes, execute o comando
adoc .
O que queremos melhorar?
- Adicione etapas técnicas configuráveis.
Na versão atual do plugin, existem as etapas "E uma captura de tela foi feita ...". Tais etapas não carregam uma carga semântica para a documentação e queremos ocultá-las. Agora nós os costuramos dentro do plug-in e eles são ignorados, mas há uma desvantagem - cada adição dessa etapa leva ao fato de que precisamos criar uma nova versão do plug-in. Para evitar isso, planejamos transferir essas etapas para o arquivo de configuração e anote as etapas que não queremos ver nos scripts. - Faça um plug-in sourse aberto.
Quais equipes são adequadas para nossa implementação?
- use Pepino (ou uma estrutura semelhante);
- deseja ter documentação atualizada para a frente e a base de conhecimento;
- Eles querem envolver analistas em testes.
Resultado:
O piloto de várias equipes mostrou que, com a ajuda do plug-in, conseguimos manter a documentação atualizada, os analistas não precisam mais gastar seu tempo mantendo-a. Além disso, a implementação desse recurso nos fez pensar em continuar implementando o BDD completo dentro das equipes. Hoje, estamos realizando um experimento - analistas formulam um caminho positivo para o cliente, indicam restrições de negócios usando as etapas BDD da Akita, os testadores, por sua vez, escrevem etapas personalizadas e verificações adicionais para esses cenários.
A propósito, sobre o holivar, seja o BDD necessário ou não, na segunda-feira realizaremos uma
reunião especial .