docurun

DocuRun

DocuRun é uma ferramenta para executar sua documentação como testes de integração.

Por que ?

Aposto que seus testes de integração e sua documentação são decepcionantes.

• Seus testes de integração provavelmente são difíceis de escrever, ler e depurar. Quando algo dá errado, você precisa vasculhar o código e tentar adivinhar em que ponto eles diferem do que você está fazendo manualmente em seu navegador.
• Sua documentação do usuário final provavelmente está desatualizada, porque os desenvolvedores não querem atualizá-la toda vez que alteram o código. Ao alterar o texto de um botão, você deve se lembrar de atualizar as capturas de tela na documentação, e provavelmente não o fará.

Se você fizer uma alteração que interrompa o comportamento documentado da interface do usuário, provavelmente só descobrirá quando os usuários reclamarem.

O que é DocuRun?

DocuRun é uma ferramenta que pega arquivos markdown, incluindo blocos de código do dramaturgo, e os executa como testes de integração. Produz um lindo site de documentação com capturas de tela tiradas durante os testes.

Como usar o DocuRun

1. Escreva sua documentação em arquivos markdown, incluindo blocos de código que descrevem como usar seu aplicativo. Crie um arquivo docurun/index.md parecido com este:
2. Execute o DocuRun em seus arquivos markdown

   npx docurun

3. O Docurun exibirá um bom relatório em sua saída padrão, mostrando quais arquivos markdown foram executados com sucesso e quais falharam. O código de saída será 0 se todos os testes forem aprovados e 1 se alguns testes falharem, o que facilita a integração em seu pipeline de CI/CD. Ele também criará um diretório docurun/website/ contendo um site estático com sua documentação e capturas de tela. Caso alguns testes tenham falhado, a documentação conterá as capturas de tela da página no momento da falha e a mensagem de erro.

Docker

Você também pode executar o DocuRun em um contêiner docker, sem precisar instalar o node.js em sua máquina:

docker run -v $( pwd ) /docurun:/docurun -it lovasoa/docurun

Veja lovaoa/docurun no Docker Hub.

Capturas de tela

SQLPágina

Isso mostra a documentação executável da ferramenta de construção de sites SQLPage.

Estrelas do GitHub

Erros

Uma execução de erro se parece com esta no terminal

 $ npx docurun

> [email protected] start
> node cli.js

Processing all files in ./docurun/:
 - download_sqlpage.md
 - star_a_repository.md.
Saving results to ./docurun/website/.

✅ download_sqlpage
Error while executing code:
await page.getByText('inexistent element').click()

locator.click: Timeout 30000ms exceeded.
Call log:
  - waiting for getByText('inexistent element')

 star_a_repository

E renderizado: