Escrever, executar e testar código¶
Corrigir um bug ou implementar uma funcionalidade vai requerer escrever algum código novo.
Para começar a trabalhar em código, certifique-se de ter um ambiente de desenvolvimento configurado e de estar a trabalhar num ramo
Temos um guia de estilo de código que descreve as nossas diretrizes para escrever código para o BeeWare.
Desenvolvimento orientado por testes¶
Uma boa maneira de garantir que o seu código funciona conforme o esperado é, primeiro, escrever um caso de teste para verifica-lo. Esse caso de teste deve falhar inicialmente, já que o código que ele está a testar ainda não está presente. Pode então fazer as alterações necessárias no código para que o teste seja aprovado e ter a certeza de que o que escreveu está a resolver o problema que espera resolver.
Correr o seu código¶
Depois de escrever o código, é preciso garantir que ele funciona. Vai precisar executa-lo manualmente para verificar se ele está a fazer o que espera. Se ainda não o fez, é recomendável escrever um caso de teste para as alterações; conforme mencionado acima, esse teste deve falhar se o seu código estiver comentado ou ausente.
Vai adicionar o seu caso de teste ao conjunto de testes, para que ele possa ser executado junto com os outros testes. O próximo passo é executar o conjunto de testes.
Correr testes e cobertura¶
BeeWare utiliza tox para gerir o processo de testes e pytest para o seu próprio conjunto de testes.
O comando predefinido tox inclui a execução de:
- ganchos de pré-submissão
- Verificação das notas de lançamento do
towncrier -
verificação de conformidade da documentação
-
conjunto de testes para as versões disponíveis do Python
-
relatórios de cobertura de código
Isso é basicamente o que a CI executa quando envia um pedido de puxar.
Para executar o conjunto completo de testes, corra:
(.venv) $ tox
(.venv) $ tox
(.venv) C:\...>tox
A execução do conjunto completo de testes pode demorar algum tempo. Pode acelerar consideravelmente o processo executando tox em paralelo, ao correr tox p (ou tox run-parallel). Ao executar o conjunto de testes emparalelo, vai receber menos retorno sobre a evolução dos testes durante a execução, mas mesmo assim vai obter um resumo de quaisquer problemas encontrados no final da execução. Deverá ver algum resultado a indicar que os testes foram executados. Pode ver testes SALTADOS, mas nunca deve receber resultados de teste FALHOU ou ERRO. Executamos o nosso conjunto completo de testes antes de fundir cada patch. Se esse processo detetar algum problema, não fundimos o patch. Se encontrar um erro ou falha no teste, ou há algo estranho no seu ambiente de teste, ou encontrou um caso extremo que não vimos antes — de qualquer forma, comunique-nos isso!
Além da aprovação dos testes, isto deve indicar 100% de cobertura de teste.
Executar variações de teste¶
Executar testes para várias versões do Python¶
Por predefinição, muitos dos comandos tox tentam executar o conjunto de testes várias vezes, uma vez para cada versão do Python compatível com o BeeWare. No entanto, para fazer isto, cada uma das versões do Python deve estar instalada no seu computador e disponível para o processo de deteção do Python do tox. Em geral, se uma versão do Python estiver disponível via PATH, então o tox deverá ser capaz de a encontrar e utilizar.
Executar apenas o conjunto de testes¶
Se estiver a iterar rapidamente uma nova funcionalidade, não precisa executar o conjunto completo de testes; pode executar apenas os testes de unidade. Para fazer isso, execute:
(.venv) $ tox-epy
(.venv) $ tox-epy
(.venv) C:\...>tox -e py
Executar um subconjunto de testes¶
Por predefinição, tox vai executar todos os testes do conjunto de testes de unidade. Ao desenvolver um novo teste, pode ser útil executar apenas esse teste específico. Para isso, pode passar qualquer especificador pytest como argumento para o tox. Estes caminhos de teste são relativos ao diretório briefcase. Por exemplo, para executar apenas os testes contidos num único ficheiro, execute:
(.venv) $ tox-epy--tests/path_to_test_file/test_some_test.py
(.venv) $ tox-epy--tests/path_to_test_file/test_some_test.py
(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py
Vai ainda receber um relatório de cobertura ao executar uma parte do conjunto de testes — mas os resultados de cobertura vão mostrar apenas as linhas de código que foram executadas pelos testes específicos que executou.
Executar o conjunto de testes para uma versão específica do Python¶
Por predefinição, tox -e py vai correr usando qualquer interpretador que resolver como python no seu computador. Se tiver várias versões do Python instaladas e quiser testar uma versão específica entre as que estão instaladas, é possível especificar a versão do Python a ser usada. Por exemplo, para executar o conjunto de testes no Python 3.10, execute:
(.venv) $ tox-epy310
(.venv) $ tox-epy310
(.venv) C:\...>tox -e py310
Pode ser executado um subconjunto de testes ao adicionar -- e uma especificação de teste à linha de comando.
Executar o conjunto de testes sem cobertura (rápido)¶
Por predefinição, tox vai correr o conjunto de testes pytest no modo de única linha de execução. Pode acelerar a execução do conjunto de testes executando-o em paralelo. Esse modo não gera ficheiros de cobertura devido às complexidades envolvidas na captura de cobertura dentro dos processos criados. Para executar uma única versão do Python no modo "rápido", execute:
(.venv) $ tox-epy-fast
(.venv) $ tox-epy-fast
(.venv) C:\...>tox -e py-fast
Pode ser executado um subconjunto de testes ao adicionar -- e uma especificação de teste à linha de comando; é possível usar uma versão específica do Python adicionando a versão ao destino do teste (por exemplo, py310-fast para executar rápido em Python 3.10).
Cobertura de código¶
BeeWare mantém 100% de cobertura de ramo no seu código-fonte. Ao adicionar ou modificar código no projeto, é necessário adicionar código de teste para garantir a cobertura de todas as alterações realizadas.
No entanto, BeeWare visa várias plataformas, bem como várias versões do Python, pelo que não é possível verificar a cobertura total numa única plataforma e versão do Python. Para contornar isso, várias regras de cobertura condicional são definidas na secção tool.coverage.coverage_conditional_plugin.rules do pyproject.toml (por exemplo, no-cover-if-is-windows pode ser usado para sinalizar um bloco de código que não será executado ao rodar o conjunto de testes no Windows). Essas regras são usadas para identificar secções de código que são cobertas apenas em plataformas ou versões específicas do Python.
De notar que a geração de relatórios de cobertura entre diferentes versões do Python pode apresentar algumas peculiaridades. Por exemplo, se os ficheiros de cobertura forem gerados usando uma versão do Python, mas a geração do relatório for feita noutra, o relatório poderá incluir falsos positivos para ramos não verificados. Por esse motivo, a geração de relatórios de cobertura deve sempre utilizar a versão mais antiga do Python usada para gerar os ficheiros de cobertura.
Compreender os resultados da cobertura¶
No final do resultado do teste de cobertura, deve haver um relatório com os dados de cobertura recolhidos:
Name Stmts Miss Branch BrPart Cover Missing
---------------------------------------------------
TOTAL 7540 0 1040 0 100.0%
Isto indica-nos que o conjunto de testes executou todos os caminhos de ramo possíveis no código. Isto não é uma garantia de 100% de que não há bugs, mas significa que estamos a testar cada linha de código da base de código.
Se fizer alterações no código-fonte, é possível que surja uma lacuna nessa cobertura. Quando isso acontecer, o relatório de cobertura indicará quais linhas não estão a ser executadas. Por exemplo, digamos que fizemos uma alteração em some/interesting_file.py, adicionando uma nova lógica. O relatório de cobertura poderia ficar mais ou menos assim:
Name Stmts Miss Branch BrPart Cover Missing
-------------------------------------------------------------------------------
src/some/interesting_file.py 111 1 26 0 98.1% 170, 302-307, 320->335
-------------------------------------------------------------------------------
TOTAL 7540 1 1726 0 99.9%
Isto diz-nos que a linha 170, as linhas 302 a 307 e um salto de ramo desde linha 320 para a linha 335 não estão a ser executados pelo conjunto de testes. Vai precisar adicionar novos testes (ou modificar um teste existente) para restaurar essa cobertura.
Relatório de cobertura para a plataforma anfitriã e a versão do Python¶
Pode gerar um relatório de cobertura para a sua plataforma e versão do Python. Por exemplo, para correr o conjunto de testes e gerar um relatório de cobertura no Python 3.10, execute:
(.venv) $ tox-mtest310
(.venv) $ tox-mtest310
(.venv) C:\...>tox -m test310
Relatório de cobertura para a plataforma anfitriã¶
Se todas as versões suportadas do Python estiverem disponíveis para tox, a cobertura para a plataforma anfitriã pode ser reportada executando:
(.venv) $ toxp-mtest-platform
(.venv) $ toxp-mtest-platform
(.venv) C:\...>tox p -m test-platform
Relatórios de cobertura em HTML¶
Pode ser gerado um relatório de cobertura HTML acrescentando -html a qualquer um dos nomes de ambiente de cobertura tox, por exemplo:
(.venv) $ tox-ecoverage-platform-html
(.venv) $ tox-ecoverage-platform-html
(.venv) C:\...>tox -e coverage-platform-html
Não se trata apenas de escrever testes!¶
Embora nos certificamos de testar todo o nosso código, a tarefa não se resume apenas a manter esse nível de testes. Parte da tarefa consiste em rever o código à medida que se avança. Podemos escrever um conjunto compreensível de testes para um colete salva-vidas de betão… mas um colete salva-vidas de betão continuava a ser inútil para o objetivo pretendido!
À medida que desenvolve testes, deve verificar se o módulo principal também é consistente internamente. Se notar algum nome de método que não seja internamente consistente (por exemplo, algo chamado on_select num módulo, mas chamado on_selected noutro), ou onde os dados não estejam sendo tratados de forma consistente, sinalize isso e nos informe criando um bilhete. Ou, se tiver certeza do que precisa ser feito, crie um pedido de puxar que corrija o problema que encontrou.
Depois de ter tudo a funcionar, pode submeter um pedido de puxar com as suas alterações.