Documentação da Extensão VS Code para Geração de Evidências de Testes TOTVS

1. O Que é?

Esta extensão para o Visual Studio Code (VS Code) foi desenvolvida para facilitar a criação de documentos de evidência de testes para produtos TOTVS, especificamente a linha Datasul. Ela automatiza a coleta de informações importantes sobre o teste e as evidências visuais (screenshots), gerando um arquivo nos formatos Word (.docx) ou PDF, pronto para ser compartilhado. Além disso, oferece a funcionalidade de converter documentos Word de evidência para o formato PDF.

Importante: Para utilizar as opções de geração de evidência no formato Word e para converter documentos Word para PDF, é necessário ter o pandoc instalado no seu sistema. A extensão oferece uma opção para baixar e instalar o pandoc automaticamente em máquinas Windows que possuam o Chocolatey instalado. Caso contrário, você precisará instalar o pandoc manualmente.

2. Como Funciona?

A extensão opera através de um comando que, quando executado, apresenta ao usuário uma série de opções para geração ou conversão de evidências. O fluxo de funcionamento é o seguinte:

1. Seleção da Ação: Ao executar o comando Gerar Evidência de Testes, o usuário pode escolher entre:
   • Gerar evidência TOTVS (Word): Requer a instalação do pandoc.
   • Gerar evidência (PDF): Não requer pandoc.
   • Converter evidência para PDF: Requer a instalação do pandoc.
   • Baixar pandoc para Windows: Utilize esta opção para instalar o pandoc automaticamente (requer Chocolatey).
2. Coleta de Entradas: Para as opções de geração de evidência (Word ou PDF), a extensão utiliza vscode.window.showInputBox e vscode.window.showQuickPick para solicitar informações como versão do produto (com sugestão dinâmica), ambiente de teste (com sugestão baseada no tipo de teste), banco de dados, tipo de teste (com opções predefinidas), objetivo, motivo, link da issue e arquivos modificados.
3. Adição de Evidências via Webview: Em vez da seleção de arquivos, a extensão abre um painel de webview onde o usuário pode colar imagens diretamente na área designada utilizando o atalho Ctrl+V (ou Cmd+V no macOS).
4. Processamento de Imagens Coladas: As imagens coladas são processadas no webview, exibidas para pré-visualização e convertidas para strings base64. O tipo de arquivo (extensão) também é detectado.
5. Solicitação de Título para Cada Evidência: Após colar uma imagem e clicar no botão "Adicionar Esta Imagem", a extensão solicita um título descritivo para essa evidência.
6. Criação do Conteúdo Markdown: Com todas as informações coletadas (incluindo as imagens adicionadas via webview), a extensão monta um conteúdo em formato Markdown. Este conteúdo inclui um cabeçalho com a logo da TOTVS, as informações básicas do teste (produto, versão, ambiente, etc.), os detalhes do teste realizado (objetivo, motivo, issue, arquivos modificados, data, responsável) e as evidências visuais com seus respectivos títulos.
7. Geração do Documento (Word ou PDF):
   • Word: Se a opção "Gerar evidência TOTVS (Word)" for selecionada, a função generateWord (localizada em src/reports/generateWord.ts) é responsável por converter o conteúdo Markdown em um arquivo Word (.docx). Ela utiliza a ferramenta de linha de comando pandoc para realizar a conversão.
   • PDF: Se a opção "Gerar evidência (PDF)" for selecionada, a função generatePDF (localizada em src/reports/generatePdf.ts) é responsável por converter o conteúdo Markdown em um arquivo PDF. Ela utiliza a biblioteca puppeteer para criar um navegador headless (sem interface gráfica), renderizar o conteúdo Markdown como HTML (utilizando a biblioteca marked para a conversão) e, em seguida, salvar a página como um arquivo PDF. Um estilo CSS básico é aplicado para garantir uma formatação adequada do documento.
8. Conversão para PDF: Se a opção "Converter evidência para PDF" for selecionada, a função convertWordToPdf (localizada em src/utils/convertWordToPdf.ts) é chamada. Esta função permite que o usuário selecione um arquivo Word (.docx) e utiliza o pandoc para convertê-lo para o formato PDF.
9. Exibição do Resultado: Após a geração ou conversão bem-sucedida, uma mensagem de informação é exibida no VS Code, e o arquivo gerado (Word ou PDF) é aberto para o usuário.

3. Como Gerar a Evidência?

Para gerar um documento de evidência de testes utilizando esta extensão, siga os passos abaixo:

1. Instale a Extensão: Certifique-se de que a extensão generation-evidence-totvs esteja instalada no seu VS Code.
2. Abra o VS Code: Inicie o Visual Studio Code.
3. Execute o Comando: Abra a paleta de comandos do VS Code (Ctrl+Shift+P ou Cmd+Shift+P) e procure por Gerar Evidência de Testes. Selecione esta opção.
4. Selecione o Formato: Escolha a opção desejada: Gerar evidência TOTVS (Word) ou Gerar evidência (PDF).
5. Preencha as Informações: A extensão irá solicitar as seguintes informações:
   • Versão do produto: Informe a versão do produto TOTVS sendo testado (ex: 12.1.2503, 12.1.2507). A extensão tentará sugerir uma versão com base na data atual.
   • Banco de dados do ambiente: Informe o tipo de banco de dados utilizado (ex: Progress, Oracle).
   • Tipo de teste: Selecione o tipo de teste realizado a partir das opções: Teste unitário, Teste integrado, Teste automatizado.
   • Ambiente de teste: Informe o ambiente onde o teste foi executado (ex: PASOE, SQA). A extensão tentará sugerir um ambiente com base no tipo de teste selecionado.
   • Objetivo: Descreva o objetivo principal do teste (ex: Teste de funcionalidade, Teste de performance).
   • Motivo: Explique a razão pela qual este teste foi realizado (descrição do bug ou da nova funcionalidade).
   • Issue: Informe o link para a issue relacionada (ex: https://jira.totvs.com.br/browse/PROJETO-1234).
   • Arquivos Modificados: Liste os arquivos que foram modificados para este teste, separados por vírgula (ex: arquivo1.p, módulo totvs-hgp-hrc-crud3).
6. Adicione as Evidências: Um painel com o título "Adicionar Evidências (Ctrl+V)" será aberto.
   • Cole as imagens: Utilize o atalho Ctrl+V (ou Cmd+V no macOS) para colar uma imagem na área designada.
   • Visualize a prévia: A imagem colada será exibida abaixo da área de colagem.
   • Adicione a imagem: Clique no botão "Adicionar Esta Imagem".
   • Informe o título: Uma caixa de diálogo aparecerá solicitando um título para a imagem adicionada. Insira um título claro e conciso (ex: Tela de login, Resultado da consulta).
   • Repita o processo: Cole e adicione quantas imagens forem necessárias para sua evidência.
7. Conclua a Adição: Após adicionar todas as imagens, clique no botão "Concluir Adição de Imagens". O painel será fechado.
8. Aguarde a Geração: A extensão irá processar as informações e gerar o arquivo no formato selecionado (Word ou PDF). Uma mensagem de sucesso será exibida.
9. Visualize o Documento: O arquivo gerado será automaticamente aberto no VS Code para sua visualização. O arquivo será salvo na raiz do seu projeto (onde a extensão está sendo executada). O nome do arquivo seguirá o padrão: [ISSUE] - Evidência de [Tipo de Teste] - [Objetivo].[extensão], onde [extensão] será docx para Word e pdf para PDF.

4. Como Testar?

Para garantir que a extensão está funcionando corretamente, você pode realizar os seguintes testes:

1. Teste com Diferentes Tipos de Entrada:
   • Informe diferentes valores para cada um dos prompts (versões de produto variadas, diferentes ambientes, tipos de teste, etc.).
   • Teste com e sem o preenchimento dos campos opcionais (como "Motivo" e "Arquivos Modificados").
   • Verifique se o link da issue é formatado corretamente no documento gerado.
   • Verifique se a sugestão de versão e ambiente funciona conforme o esperado.
   • Teste a seleção de tipo de teste através do Quick Pick.
2. Teste com Diferentes Formatos de Imagem (via Colagem):
   • Cole imagens nos formatos PNG, JPG e JPEG para verificar se todos são processados e exibidos corretamente no documento gerado.
   • Teste colar imagens de diferentes fontes (clipboard, print screen).
3. Teste com Múltiplas Imagens (via Colagem):
   • Cole e adicione várias imagens para garantir que todas sejam incluídas no documento gerado com seus respectivos títulos.
4. Verifique a Formatação do Documento (Word e PDF):
   • Abra o arquivo gerado e verifique se as informações estão dispostas de forma clara e organizada.
   • Confirme se o cabeçalho e o rodapé (logo) estão presentes.
   • Verifique se os títulos das imagens estão corretos e as imagens são exibidas sem distorção.
5. Teste com Títulos de Imagem Complexos:
   • Insira títulos de imagem mais longos para verificar se a formatação do documento se adapta.
6. Simule um Cenário sem Adicionar Imagens:
   • Execute o comando e clique em "Concluir Adição de Imagens" sem colar nenhuma imagem. O documento deve ser gerado com as demais informações, mas sem a seção de evidências.
7. Teste com Conteúdo Não-Imagem Colado:
   • Tente colar texto ou outros tipos de conteúdo no webview para verificar se a extensão lida com isso corretamente (exibindo uma mensagem de erro).
8. Teste a Conversão para PDF:
   • Gere um documento Word utilizando a extensão.
   • Execute o comando Gerar Evidência de Testes novamente e selecione a opção Converter evidência para PDF.
   • Selecione o arquivo Word gerado e verifique se a conversão para PDF ocorre corretamente.
9. Teste a Instalação do Pandoc:
   • Em um ambiente Windows onde o Pandoc não está instalado, execute o comando Gerar Evidência de Testes e selecione a opção Baixar pandoc para Windows. Verifique se a instalação é iniciada e concluída com sucesso (requer o Chocolatey instalado).

5. Como Fazer Manutenção?

A manutenção da extensão pode envolver a atualização de dependências, a correção de bugs, a adição de novas funcionalidades ou a modificação da formatação dos documentos gerados. Abaixo estão algumas dicas para realizar a manutenção:

1. Atualização de Dependências:
   • Verifique regularmente se há novas versões das dependências utilizadas (vscode, fs, path, puppeteer, marked, pandoc-bin).
   • Para atualizar as dependências, navegue até a pasta da extensão no seu terminal e execute o comando npm update ou yarn upgrade.
   • Após a atualização, teste a extensão para garantir que não houve quebras de compatibilidade.
2. Correção de Bugs:
   • Se forem encontrados bugs, analise o código para identificar a causa do problema.
   • Utilize as ferramentas de depuração do VS Code para auxiliar na identificação e correção.
   • Após a correção, realize testes para garantir que o bug foi resolvido e que nenhuma nova falha foi introduzida.
3. Adição de Novas Funcionalidades:
   • Se houver a necessidade de adicionar novos campos de entrada, modifique a função activate em src/extension.ts para incluir os novos prompts utilizando vscode.window.showInputBox ou vscode.window.showQuickPick.
   • Atualize o template Markdown na função activate em src/extension.ts para incluir os novos dados coletados.
   • Para modificar o processo de adição de imagens, altere a lógica dentro do webview (src/webviews/webviewImageInput.ts e templates/templateHtmlImageInput.html) e a comunicação entre o webview e a extensão (src/extension.ts).
4. Modificação da Formatação do PDF:
   • A formatação do PDF é definida no bloco <style> dentro da função generatePDF em src/reports/generatePdf.ts.
   • Para alterar a aparência do PDF (fontes, tamanhos, margens, etc.), modifique as regras CSS neste bloco.
   • Você também pode optar por utilizar um arquivo CSS externo para gerenciar os estilos de forma mais organizada.
5. Modificação da Formatação do Word:
   • A formatação do documento Word é gerenciada pelo pandoc. Para modificar a formatação, você pode precisar ajustar o template Markdown gerado ou utilizar arquivos de estilo de referência do Word com o pandoc.
6. Testes Após Modificações:
   • Após qualquer modificação no código, é fundamental realizar testes completos (conforme descrito na seção "Como Testar?") para garantir que as alterações não introduziram novos problemas e que a extensão continua funcionando como esperado.
7. Publicação de Novas Versões:
   • Se você fez alterações significativas na extensão, considere publicar uma nova versão na VS Code Marketplace para que outros usuários possam se beneficiar das atualizações.

6. Estrutura de Pastas da Extensão

A estrutura de pastas desta extensão é a seguinte:

. ├── .vscode/ │ └── launch.json (Configuração para depuração) ├── src/ │ ├── images/ │ │ ├── totvs-header.jpg │ │ └── totvs-logo.png │ ├── interfaces/ │ │ └── IImagemData.ts (Interface para dados de imagem) │ ├── models/ │ │ └── userInputModel.ts (Modelo para dados de entrada do usuário) │ ├── reports/ │ │ ├── generatePdf.ts (Função para gerar PDF) │ │ └── generateWord.ts (Função para gerar Word) │ ├── services/ │ │ ├── pandocService.ts (Serviços relacionados ao Pandoc) │ │ └── userInputsService.ts (Serviço para coletar entradas do usuário) │ ├── utils/ │ │ ├── convertToBase64.ts (Função para converter arquivo para Base64) │ │ └── convertWordToPdf.ts (Função para converter Word para PDF) │ ├── webviews/ │ │ └── webviewImageInput.ts (Código para a webview de entrada de imagens) │ └── extension.ts (Código principal da extensão) ├── templates/ │ └── templateHtmlImageInput.html (HTML da webview para entrada de imagens) ├── package.json (Arquivo de manifesto da extensão) ├── tsconfig.json (Configuração do TypeScript) └── vsc-extension-quickstart.md (Arquivo Markdown inicial - pode ser removido)

• .vscode/launch.json: Contém as configurações para depurar a extensão dentro do VS Code.
• src/images/: Armazena as imagens utilizadas no template dos documentos gerados (totvs-header.jpg para o cabeçalho e totvs-logo.png para o rodapé).
• src/interfaces/IImagemData.ts: Define a interface IImagemData para representar os dados das imagens adicionadas.
• src/models/userInputModel.ts: Define a classe UserInputModel para armazenar os dados de entrada do usuário.
• src/reports/generatePdf.ts: Contém a função generatePDF responsável por gerar o arquivo PDF.
• src/reports/generateWord.ts: Contém a função generateWord responsável por gerar o arquivo Word.
• src/services/pandocService.ts: Contém funções para verificar e instalar o pandoc.
• src/services/userInputsService.ts: Contém a função UserInputsService que coleta as informações do usuário através de prompts.
• src/utils/convertToBase64.ts: Contém a função convertToBase64 para converter arquivos (como imagens) para o formato Base64.
• src/utils/convertWordToPdf.ts: Contém a função convertWordToPdf para converter um arquivo Word para PDF utilizando o pandoc.
• src/webviews/webviewImageInput.ts: Contém a função getWebviewContent que retorna o conteúdo HTML para a webview de entrada de imagens.
• src/extension.ts: Contém o código fonte principal da extensão, incluindo a lógica para registrar o comando, coletar as informações do usuário, interagir com a webview e chamar as funções de geração de documentos.
• templates/templateHtmlImageInput.html: Contém o código HTML para a webview onde o usuário pode colar as imagens.
• package.json: Define as informações básicas da extensão (nome, versão, descrição, dependências, etc.) e os comandos que ela registra.
• tsconfig.json: Define as opções de compilação para o TypeScript.
• vsc-extension-quickstart.md: Um arquivo Markdown gerado inicialmente ao criar a extensão, pode ser removido se não for necessário.

Ao realizar manutenções ou adicionar funcionalidades, familiarize-se com essa estrutura de pastas para localizar os arquivos relevantes.

Criado por: Lucas Ribeiro - lucas.hsilva@totvs.com.br