Scrivere, eseguire e testare il codice¶

Per correggere un bug o implementare una funzionalità dovrai scrivere del codice nuovo.

Per iniziare a lavorare sul codice, assicurati di avere un ambiente di sviluppo configurato e di lavorare su un ramo.

Abbiamo una guida allo stile del codice che illustra le nostre linee guida per la scrittura del codice per BeeWare.

Sviluppo guidato dai test¶

Un buon modo per assicurarsi che il codice funzioni come previsto è quello di scrivere innanzitutto un caso di test per verificarlo. Inizialmente questo caso di test dovrebbe fallire, poiché il codice che sta verificando non è ancora presente. A quel punto è possibile apportare le modifiche necessarie affinché il test abbia esito positivo, con la certezza che ciò che è stato scritto risolva effettivamente il problema previsto.

Esegui il tuo codice¶

Una volta scritto il codice, devi assicurarti che funzioni. Dovrai eseguire manualmente il codice per verificare che faccia ciò che ti aspetti. Se non l'hai già fatto, ti consigliamo di scrivere un caso di test per le modifiche apportate; come accennato in precedenza, questo test dovrebbe fallire se il codice è commentato o non è presente.

Aggiungi il tuo caso di test alla suite di test, in modo che possa essere eseguito insieme agli altri test. Il passo successivo consiste nell'eseguire la suite di test.

Esecuzione dei test e della copertura¶

BeeWare utilizza tox per gestire il processo di test e pytest per la propria suite di test.

Il comando predefinito tox prevede l'esecuzione di:

hook pre-commit
towncrier Verifica delle note di rilascio
controllo della documentazione
suite di test per le versioni disponibili di Python
reportistica sulla copertura del codice

Questo è sostanzialmente ciò che viene eseguito da CI quando si invia una pull request.

Per eseguire l'intera suite di test, digitare:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

L'esecuzione della suite di test completa può richiedere un po' di tempo. È possibile accelerarla notevolmente eseguendo tox in parallelo, ovvero tox p (o tox run-parallel). Quando si esegue la suite di test in parallelo, si riceveranno meno aggiornamenti sullo stato di avanzamento durante l'esecuzione, ma alla fine della sessione di test si otterrà comunque un riepilogo di eventuali problemi rilevati. Dovresti ricevere un messaggio che indica che i test sono stati eseguiti. Potresti vedere SKIPPED test, ma non dovresti mai ottenere risultati di test FAIL o ERROR. Eseguiamo la nostra suite di test completa prima di unire ogni patch. Se tale processo rileva dei problemi, non uniamo la patch. Se trovi un errore o un fallimento nel test, o c'è qualcosa di strano nel tuo ambiente di test, oppure hai trovato un caso limite che non abbiamo mai visto prima: in entrambi i casi, faccelo sapere!

Oltre al superamento dei test, questo dovrebbe indicare una copertura dei test del 100%.

Esecuzione delle varianti di test¶

Eseguire i test su più versioni di Python¶

Per impostazione predefinita, molti dei comandi tox tenteranno di eseguire la suite di test più volte, una volta per ciascuna versione di Python supportata da BeeWare. Per farlo, tuttavia, ciascuna versione di Python deve essere installata sul tuo computer ed essere disponibile per il processo di [rilevamento]tox di Python da parte di (https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery). In generale, se una versione di Python è disponibile tramite PATH, allora tox dovrebbe essere in grado di individuarla e utilizzarla.

Esegui solo la suite di test¶

Se stai sviluppando rapidamente una nuova funzionalità, non è necessario eseguire l'intera suite di test; puoi eseguire solo i test unitari. Per farlo, esegui:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

Eseguire un sottoinsieme di test¶

Per impostazione predefinita, tox esegue tutti i test della suite di test unitari. Quando si sviluppa un nuovo test, può essere utile eseguire solo quel test specifico. Per farlo, è possibile passare qualsiasi specificatore pytest come argomento a tox. Questi percorsi dei test sono relativi alla directory briefcase. Ad esempio, per eseguire solo i test contenuti in un singolo file, digitare:

macOSLinuxWindows

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

Anche se esegui solo una parte della suite di test, riceverai comunque un rapporto sulla copertura; tuttavia, i risultati della copertura riporteranno solo le righe di codice eseguite dai test specifici che hai eseguito.

Esegui la suite di test per una versione specifica di Python¶

Per impostazione predefinita, tox -e py verrà eseguito utilizzando l'interprete che il sistema riconosce come python sul tuo computer. Se hai installato più versioni di Python e desideri testare una versione specifica tra quelle installate, puoi specificare la versione di Python da utilizzare. Ad esempio, per eseguire la suite di test su Python 3.10, digita:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

È possibile eseguire un insieme parziale di test aggiungendo -- e una specifica di test alla riga di comando.

Esegui la suite di test senza copertura (veloce)¶

Per impostazione predefinita, tox esegue la suite di test pytest in modalità a thread singolo. È possibile velocizzare l'esecuzione della suite di test eseguendola in parallelo. Questa modalità non genera file di copertura a causa delle difficoltà nel rilevare la copertura all'interno dei processi generati. Per eseguire una singola versione di Python in modalità "fast", digitare:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

È possibile eseguire un sottoinsieme di test aggiungendo -- e una specifica di test alla riga di comando; è possibile utilizzare una versione specifica di Python aggiungendo la versione al target di test (ad es., py310-fast per eseguire fast su Python 3.10).

Copertura del codice¶

BeeWare garantisce una copertura del codice del 100% nel proprio codice sorgente. Quando si aggiunge o si modifica del codice nel progetto, è necessario aggiungere del codice di test per garantire la copertura di tutte le modifiche apportate.

Tuttavia, BeeWare è destinato a più piattaforme e a più versioni di Python, pertanto non è possibile verificare la copertura completa su una singola piattaforma e versione di Python. Per ovviare a questo problema, nella sezione tool.coverage.coverage_conditional_plugin.rules di pyproject.toml sono definite diverse regole di copertura condizionali (ad esempio, no-cover-if-is-windows può essere utilizzato per contrassegnare un blocco di codice che non verrà eseguito durante l'esecuzione della suite di test su Windows). Queste regole vengono utilizzate per identificare sezioni di codice coperte solo su particolari piattaforme o versioni di Python.

È importante notare che la generazione dei report di copertura tra diverse versioni di Python può presentare alcune anomalie. Ad esempio, se i file di copertura vengono generati utilizzando una versione di Python ma la generazione dei report avviene su un'altra versione, il report potrebbe includere falsi positivi relativi a rami non eseguiti. Per questo motivo, per la generazione dei report di copertura si dovrebbe sempre utilizzare la versione più vecchia di Python impiegata per generare i file di copertura.

Comprendere i risultati della copertura¶

Alla fine dell'output del test di copertura dovrebbe comparire un rapporto contenente i dati di copertura raccolti:

Nome    Dichiarazioni   Mancato Branch BrPart   Copertura   Mancanti
 ---------------------------------------------------
 TOTALE    7540 0   1040 0  100,0%

Questo ci indica che la suite di test ha eseguito ogni possibile percorso di ramificazione nel codice. Non è una garanzia al 100% dell'assenza di bug, ma significa che stiamo verificando ogni riga di codice del codice sorgente.

Se apporti modifiche al codice, è possibile che si crei una lacuna nella copertura. In tal caso, il rapporto sulla copertura ti indicherà quali righe non vengono eseguite. Ad esempio, supponiamo di aver apportato una modifica a some/interesting_file.py, aggiungendo una nuova logica. Il rapporto sulla copertura potrebbe apparire più o meno così:

Nome Istr.   Errore Ramo BrPart  Copertura   Mancante
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98,1%   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 TOTALE 7540 1   1726 0  99,9%

Questo ci indica che la riga 170, le righe da 302 a 307 e un salto di ramo dalla riga 320 alla riga 335 non vengono eseguiti dalla suite di test. Per ripristinare questa copertura, dovrai aggiungere nuovi test (o modificare un test esistente).

Rapporto sulla copertura per la piattaforma ospitante e la versione di Python¶

È possibile generare un rapporto di copertura per la propria piattaforma e versione di Python. Ad esempio, per eseguire la suite di test e generare un rapporto di copertura su Python 3.10, eseguire:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

Rapporto sulla copertura per la piattaforma ospitante¶

Se tutte le versioni supportate di Python sono disponibili per tox, è possibile ottenere un rapporto sulla copertura per la piattaforma ospitante eseguendo:

macOSLinuxWindows

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

Reportistica sulla copertura in HTML¶

È possibile generare un rapporto di copertura HTML aggiungendo -html a uno qualsiasi dei nomi degli ambienti di copertura tox, ad esempio:

macOSLinuxWindows

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

Non si tratta solo di scrivere test!¶

Sebbene ci assicuriamo di testare tutto il nostro codice, il compito non consiste solo nel mantenere quel livello di test. Parte del lavoro consiste nel verificare il codice man mano che si procede. Si potrebbe scrivere una serie completa di test per un giubbotto di salvataggio di cemento… ma un giubbotto di salvataggio di cemento sarebbe comunque inutile per lo scopo a cui è destinato!

Mentre sviluppi i test, dovresti verificare che anche il modulo principale sia coerente al suo interno. Se noti nomi di metodi che non sono internamente coerenti (ad esempio, qualcosa chiamato on_select in un modulo, ma chiamato on_selected in un altro), o casi in cui i dati non vengono gestiti in modo coerente, segnalacelo aprendo un ticket. Oppure, se sei sicuro di sapere cosa bisogna fare, crea una pull request che risolva il problema che hai trovato.

Una volta che tutto funziona, puoi inviare una richiesta pull con le tue modifiche.