feat: run doctests as a part of the test suit

[thepabloaguilar]

Descrição

A issue original fala sobre alguns exemplos da documentação que estão errados, isso afeta diretamente a experiência do usuário da biblioteca.

Mudanças Propostas

Para resolver esse problema e tentar evitar esses errors futuramente minha proposta é utilizarmos o pytest apenas como o runner dos testes, ou seja, os testes continuarão a serem escritos utilizando o módulo unittest mas sendo executados com o pytest.

O pytest facilita bastante a nossa vida com o descobrimento automático dos doctests não só em arquivos Python mas também em arquivos Markdown, para termos o mesmo efeito com o unittest teríamos que fazer algo mais manual o que talvez aumentaria um pouco o risco de existir exemplos errados novamente. E além dessa facilidade ele também tem ótimos plugins que podemos utilizar e tomei a liberdade de colocar dois:

• pytest-randomly: esse plugin executa os testes em ordem aleatória cada vez que rodamos os testes, isso nos previne (ou pelo menos tenta) de escrevermos testes que dependam entre si
• pytest-cov: automaticamente gera o relatório de cobertura após rodarmos os testes

Com a introdução do pytest eu rodei todos os testes e fui arrumando cada um que não estava adequado e coloquei o comentário # doctest: +SKIP para previnir que funções que tenham efeitos colaterias (exemplo: fazer um request) rodem como parte do suite de testes.

Como tinha que modificar o workflow de testes para rodar o pytest ao invés do unittest fiz alguns ajustes:

• Permissionamento explicito na pipeline agora
• Adicionei a versão 3.14 do Python na matriz de teste
• Coloquei para o upload do cobertura dos testes ser apenas para um versão do Python isso porque diferentes versões são medidas de formas diferentes

Checklist de Revisão

• Eu li o Contributing.md
• Os testes foram adicionados ou atualizados para refletir as mudanças (se aplicável).
• Foi adicionada uma entrada no changelog / Meu PR não necessita de uma nova entrada no changelog.
• A documentação em português foi atualizada ou criada, se necessário.
• Se feita a documentação, a atualização do arquivo em inglês.
• Eu documentei as minhas mudanças no código, adicionando docstrings e comentários. Instruções
• O código segue as diretrizes de estilo e padrões de codificação do projeto.
• Todos os testes passam. Instruções
• O Pull Request foi testado localmente. Instruções
• Não há conflitos de mesclagem.

Declaração de Uso de IA (OBRIGATÓRIA)

• Nenhuma ferramenta de IA foi utilizada na preparação deste PR.
• Se ferramentas de IA foram utilizadas, eu informei quais foram e revisei e verifiquei completamente os resultados gerados.

Comentários Adicionais (opcional)

Nos arquivos Markdown eu troquei os blocos python por blocos pycon (pyconsole) que é o recomendado nesse caso que estamos "simulando" o REPL e tem um highlight diferente:

>>> 'PYTHON'
>>> 1 + 1
2

>>> 'PYCON'
>>> 1 + 1
2

Issue Relacionada

Closes #765

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.47%. Comparing base (703da13) to head (198097b).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #776      +/-   ##
==========================================
+ Coverage   99.09%   99.47%   +0.38%     
==========================================
  Files          26       26              
  Lines         775      765      -10     
  Branches        0       98      +98     
==========================================
- Hits          768      761       -7     
+ Misses          7        2       -5     
- Partials        0        2       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[thepabloaguilar]

Aparentemente deu uma quedinha de ~0.67% na cobertura dos testes porquê não estava sendo considerado o branching (que vira o partial), vou escrever os testes restantes para aumentar a cobertura novamente e mantendo o branching