Skrivning, kørsel og test af kode¶

Hvis du skal rette en fejl eller implementere en ny funktion, bliver du nødt til at skrive noget nyt kode.

For at begynde at arbejde med kode skal du sikre dig, at du har en udviklingsmiljø opsat, og at du arbejder på en gren.

Vi har en kodestilguide, der beskriver vores retningslinjer for at skrive kode til BeeWare.

Testdrevet udvikling¶

En god måde at sikre sig på, at din kode kommer til at fungere som forventet, er først at skrive et testscenarie til at teste den. Dette testscenarie bør i første omgang mislykkes, da den kode, det tester, endnu ikke findes. Derefter kan du foretage de nødvendige ændringer i koden, så testen består, og dermed vide, at det, du har skrevet, løser det problem, du havde forventet.

Kør din kode¶

Når du har skrevet din kode, skal du sikre dig, at den fungerer. Du skal køre koden manuelt for at kontrollere, at den opfører sig som forventet. Hvis du ikke allerede har gjort det, bør du skrive en testcase for dine ændringer; som nævnt ovenfor skal denne test mislykkes, hvis koden er kommenteret ud eller mangler.

Du skal tilføje din testtilfælde til testsuiten, så den kan køres sammen med de øvrige tests. Det næste trin er at køre testsuiten.

Kører test og dækning¶

BeeWare bruger tox til at styre testprocessen og pytest til sin egen testsuite.

Standardkommandoen tox omfatter følgende:

pre-commit-hooks
towncrier kontrol af udgivelsesnoter
kontrol af dokumentation
testsuite til tilgængelige Python-versioner
rapportering af kodedækning

Det er i alt væsentligt det, som CI kører, når du indsender en pull-anmodning.

For at køre hele testsuiten skal du skrive:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

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

Det kan tage et stykke tid at køre den fulde testsuite. Du kan gøre det betydeligt hurtigere ved at køre tox parallelt, ved at køre tox p (eller tox run-parallel). Når du kører testsuiten parallelt, får du mindre feedback om testsuitenes fremskridt undervejs, men du får stadig en oversigt over eventuelle fundne problemer ved afslutningen af testkørslen. Du bør få en udskrift, der viser, at testene er blevet kørt. Du kan muligvis se SKIPPED test, men bør aldrig få nogen FAIL eller ERROR testresultater. Vi kører vores fulde testsuite, før vi fletter hver patch. Hvis denne proces opdager problemer, fletter vi ikke patchen. Hvis du finder en testfejl eller et testsvigt, er der enten noget mærkeligt i dit testmiljø, eller også har du fundet et grænsetilfælde, som vi ikke har set før – uanset hvad, så lad os det vide!

Ud over at testene er bestået, bør dette vise 100 % testdækning.

Kørsel af testvarianter¶

Kør test for flere versioner af Python¶

Som standard vil mange af tox-kommandoerne forsøge at køre testsuiten flere gange, én gang for hver Python-version, der understøttes af BeeWare. For at dette skal lykkes, skal hver af disse Python-versioner dog være installeret på din computer og tilgængelig for tox-programmets Python-discovery-proces. Generelt gælder det, at hvis en Python-version er tilgængelig via PATH, bør tox kunne finde og bruge den.

Kør kun testsuiten¶

Hvis du arbejder hurtigt med en ny funktion, behøver du ikke køre hele testsuiten; du kan nøjes med kun at køre enhedstestene. For at gøre dette skal du køre:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Kør en delmængde af testene¶

Som standard kører tox alle testene i enhedstestsuiten. Når du udvikler en ny test, kan det være nyttigt at køre kun den ene test. For at gøre dette kan du angive en hvilken som helst pytest specifikator som et argument til tox. Disse teststier er relative i forhold til briefcase-mappen. Hvis du f.eks. kun vil køre testene i en enkelt fil, skal du køre:

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

Du får stadig en dækningsrapport, når du kører en del af testsuiten – men dækningsresultaterne vil kun vise de kodelinjer, der blev udført af de specifikke tests, du kørte.

Kør testsuiten for en bestemt Python-version¶

Som standard kører tox -e py med den fortolker, der identificeres som python på din computer. Hvis du har flere Python-versioner installeret og ønsker at teste en bestemt version blandt de installerede, kan du angive, hvilken Python-version der skal bruges. Hvis du f.eks. vil køre testsuiten på Python 3.10, skal du køre følgende:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

En delmængde af test kan køres ved at tilføje -- og en testspecifikation til kommandolinjen.

Kør testsuiten uden dækning (hurtigt)¶

Som standard kører tox pytest-testsuiten i enkeltrådet tilstand. Du kan gøre udførelsen af testsuiten hurtigere ved at køre den parallelt. Denne tilstand genererer ikke dækningsfiler på grund af de tekniske udfordringer, der er forbundet med at registrere dækning i de oprettede processer. For at køre en enkelt Python-version i "hurtig" tilstand skal du køre:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

En delmængde af test kan køres ved at tilføje -- og en testspecifikation til kommandolinjen; en bestemt Python-version kan anvendes ved at tilføje versionen til testmålet (f.eks. py310-fast for at køre fast på Python 3.10).

Kodedækning¶

BeeWare opretholder 100 % testdækning i sin kodebase. Når du tilføjer eller ændrer kode i projektet, skal du tilføje testkode for at sikre, at alle ændringer, du foretager, bliver testet.

Imidlertid er BeeWare beregnet til flere platforme samt flere versioner af Python, så det er ikke muligt at verificere fuld dækning på en enkelt platform og Python-version. For at imødekomme dette er der defineret flere betingede dækningsregler i tool.coverage.coverage_conditional_plugin.rules-sektionen af pyproject.toml (f.eks. kan no-cover-if-is-windows bruges til at markere en kodeblok, der ikke vil blive udført, når testsuiten køres på Windows). Disse regler bruges til at identificere kodestykker, der kun er dækket på bestemte platforme eller Python-versioner.

Det er værd at bemærke, at dækningsrapportering på tværs af Python-versioner kan være lidt uforudsigelig. Hvis dækningsfilerne f.eks. genereres ved hjælp af én Python-version, men dækningsrapporteringen udføres på en anden, kan rapporten indeholde falske positive resultater for oversete forgreninger. Af denne grund bør dækningsrapporteringen altid baseres på den ældste Python-version, der blev brugt til at generere dækningsfilerne.

Forståelse af dækningsresultater¶

I slutningen af dækningsprøvens output bør der være en rapport over de indsamlede dækningsdata:

Navn    Stmts   Miss Branch BrPart   Dækning   Mangler
 ---------------------------------------------------
 I ALT    7540 0   1040 0  100,0 %

Dette fortæller os, at testsuiten har gennemgået alle mulige forgreningsveje i koden. Det er ikke en 100 % garanti for, at der ikke er fejl, men det betyder, at vi tester hver eneste kodelinje i kodebasen.

Hvis du foretager ændringer i kodebasen, kan der opstå et hul i dækningen. Når det sker, vil dækningsrapporten vise dig, hvilke linjer der ikke udføres. Lad os for eksempel sige, at vi har ændret some/interesting_file.py og tilføjet noget nyt logik. Dækningsrapporten kan se sådan ud:

Navn Stmts   Miss Branch BrPart  Cover   Mangler
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98,1 %   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 I ALT 7540 1   1726 0  99,9 %

Dette viser, at linje 170, linjerne 302–307 samt et spring fra linje 320 til linje 335 ikke udføres af testsuiten. Du skal tilføje nye tests (eller ændre en eksisterende test) for at genoprette denne dækning.

Rapport om dækning for værtsplatform og Python-version¶

Du kan generere en dækningsrapport for din platform og version af Python. Hvis du f.eks. vil køre testsuiten og generere en dækningsrapport for Python 3.10, skal du køre følgende kommando:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

Dækningsrapport for værtsplatformen¶

Hvis alle understøttede versioner af Python er tilgængelige for tox, kan dækningen for værtsplatformen rapporteres ved at køre:

macOSLinuxWindows

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

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

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

Rapportering af dækning i HTML¶

Der kan genereres en HTML-dækningsrapport ved at tilføje -html til et hvilket som helst af dækningsmiljønavnene tox, for eksempel:

macOSLinuxWindows

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

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

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

Det handler ikke kun om at skrive tests!¶

Selvom vi sørger for at teste al vores kode, handler opgaven ikke kun om at opretholde det testniveau. En del af opgaven består i at gennemgå koden undervejs. Man kunne godt skrive et omfattende sæt tests til en konkret redningsvest… men en konkret redningsvest ville stadig være ubrugelig til det formål, den var beregnet til!

Når du udvikler test, bør du også kontrollere, at kernemodulet er konsistent internt. Hvis du bemærker metodernavne, der ikke er internt konsistente (f.eks. noget, der hedder on_select i et modul, men on_selected i et andet), eller hvor dataene ikke håndteres konsistent, skal du markere det og gøre os opmærksom på det ved at oprette en ticket. Eller, hvis du er sikker på, at du ved, hvad der skal gøres, kan du oprette en pull-anmodning, der løser det problem, du har fundet.

Når alt fungerer, kan du indsende en pull-anmodning med dine ændringer.