Psaní, spouštění a testování kódu¶

Oprava chyby nebo implementace nové funkce bude vyžadovat, abyste napsali nový kód.

Než začnete pracovat na kódu, ujistěte se, že máte nastavené vývojové prostředí a že pracujete na větvi.

Máme příručku pro psaní kódu, která obsahuje pokyny pro psaní kódu pro BeeWare.

Vývoj řízený testy¶

Dobrým způsobem, jak zajistit, že váš kód bude fungovat podle vašich představ, je nejprve napsat testovací případ, který to ověří. Tento testovací případ by měl zpočátku selhat, protože kód, který má otestovat, ještě neexistuje. Poté můžete provést změny v kódu potřebné k tomu, aby test proběhl úspěšně, a mít jistotu, že to, co jste napsali, řeší problém tak, jak jste očekávali.

Spusťte svůj kód¶

Jakmile kód napíšete, musíte se ujistit, že funguje. Budete jej muset spustit ručně, abyste ověřili, zda dělá to, co očekáváte. Pokud jste tak ještě neučinili, měli byste pro své změny napsat testovací případ; jak již bylo zmíněno výše, tento test by měl selhat, pokud je váš kód zakomentován nebo chybí.

Svůj testovací případ přidáte do testovací sady, aby mohl být spuštěn společně s ostatními testy. Dalším krokem je spuštění testovací sady.

Spuštění testů a pokrytí¶

BeeWare využívá tox ke správě testovacího procesu a pytest pro svou vlastní sadu testů.

Výchozí příkaz tox zahrnuje spuštění:

háčky před potvrzením
towncrier kontrola poznámek k verzi
kontrola dokumentace
sada testů pro dostupné verze jazyka Python
zprávy o pokrytí kódu

To je v podstatě to, co spustí CI, když odešlete žádost o začlenění.

Chcete-li spustit celou sadu testů, zadejte:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

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

Spuštění celé testovací sady může chvíli trvat. Můžete jej výrazně urychlit spuštěním tox paralelně, a to pomocí příkazu tox p (nebo tox run-parallel). Při paralelním spuštění testovací sady budete dostávat méně informací o jejím průběhu, ale na konci testování se vám i tak zobrazí souhrn všech zjištěných problémů. Měl by se zobrazit výpis potvrzující, že testy proběhly. Můžete vidět SKIPPED testů, ale nikdy byste neměli dostat žádné výsledky testů FAIL nebo ERROR. Před sloučením každé opravy spouštíme naši kompletní sadu testů. Pokud tento proces odhalí nějaké problémy, opravu nesloučíme. Pokud narazíte na chybu nebo selhání testu, buď je ve vašem testovacím prostředí něco v nepořádku, nebo jste narazili na okrajový případ, který jsme dosud nezaznamenali – v každém případě nám to dejte vědět!

Kromě úspěšného absolvování testů by mělo být vykazováno 100% pokrytí testy.

Spouštění různých variant testů¶

Spustit testy pro více verzí jazyka Python¶

Ve výchozím nastavení se mnoho příkazů tox pokusí spustit sadu testů několikrát, a to jednou pro každou verzi jazyka Python, kterou BeeWare podporuje. K tomu je však nutné, aby byly všechny tyto verze jazyka Python nainstalovány ve vašem počítači a byly dostupné pro proces [vyhledávání]tox jazyka Python v (https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery). Obecně platí, že pokud je nějaká verze jazyka Python dostupná prostřednictvím PATH, měl by ji tox dokázat najít a použít.

Spustit pouze sadu testů¶

Pokud na nové funkci pracujete v rychlém cyklu, nemusíte spouštět celou sadu testů; stačí spustit pouze jednotkové testy. K tomu zadejte:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Spustit podmnožinu testů¶

Ve výchozím nastavení příkaz tox spustí všechny testy v sadě jednotkových testů. Při vývoji nového testu může být užitečné spustit pouze tento jeden test. K tomu můžete jako argument příkazu pytest předat [libovolný specifikátor (https://docs.pytest.org/en/latest/how-to/usage.html#specifying-which-tests-to-run)]tox. Tyto cesty k testům jsou relativní vůči adresáři briefcase. Chcete-li například spustit pouze testy v jednom souboru, zadejte:

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

I při spuštění pouze části testovací sady obdržíte zprávu o pokrytí – výsledky pokrytí však budou zahrnovat pouze řádky kódu, které byly provedeny konkrétními testy, které jste spustili.

Spustit sadu testů pro konkrétní verzi jazyka Python¶

Ve výchozím nastavení se tox -e py spustí pomocí interpretu, který se na vašem počítači přiřazuje k python. Pokud máte nainstalováno více verzí jazyka Python a chcete otestovat konkrétní verzi z těch, které máte nainstalované, můžete určit konkrétní verzi jazyka Python, která se má použít. Chcete-li například spustit sadu testů v jazyce Python 3.10, zadejte:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

Podskupinu testů [test-subset] lze spustit tak, že do příkazového řádku přidáte -- a specifikaci testu.

Spustit sadu testů bez měření pokrytí (rychle)¶

Ve výchozím nastavení spustí tox sadu testů v jednovláknovém režimu. Spuštěním sady testů paralelně můžete její provedení zrychlit. V tomto režimu se nevytvářejí soubory s pokrytím, a to kvůli složitosti zaznamenávání pokrytí v rámci spuštěných procesů. Chcete-li spustit jednu verzi Pythonu v „rychlém“ režimu, zadejte:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

Podmnožinu testů lze spustit přidáním -- a specifikace testu do příkazového řádku; konkrétní verzi Pythonu lze použít přidáním této verze do cíle testu (např. py310-fast pro spuštění testu fast v Pythonu 3.10).

Pokrytí kódu¶

BeeWare udržuje ve svém kódovém základu 100% pokrytí větví. Pokud v projektu přidáváte nebo upravujete kód, musíte přidat testovací kód, abyste zajistili pokrytí všech provedených změn.

Nicméně BeeWare je určen pro více platforem i pro více verzí jazyka Python, takže úplné pokrytí nelze ověřit pouze na jedné platformě a jedné verzi Pythonu. Aby se tomuto přizpůsobilo, je v sekci tool.coverage.coverage_conditional_plugin.rules definováno několik podmíněných pravidel pokrytí (např. pyproject.toml lze použít k označení bloku kódu, který nebude proveden při spuštění testovací sady na Windows). Tato pravidla se používají k identifikaci částí kódu, které jsou pokryty pouze na určitých platformách nebo verzích Pythonu.

Je třeba poznamenat, že generování zpráv o pokrytí v různých verzích jazyka Python může být poněkud nevyzpytatelné. Pokud jsou například soubory pokrytí vytvořeny v jedné verzi jazyka Python, ale zpráva o pokrytí je generována v jiné verzi, může zpráva obsahovat falešně pozitivní výsledky u vynechaných větví. Z tohoto důvodu by se při generování zpráv o pokrytí měla vždy používat nejstarší verze jazyka Python, která byla použita k vytvoření souborů pokrytí.

Porozumění výsledkům krytí¶

Na konci výstupu testu pokrytí by měla být uvedena zpráva o shromážděných údajích o pokrytí:

Jméno    Výkazy   Chybějící pobočka BrPart   Krytí   Chybějící
 ---------------------------------------------------
 CELKEM    7540 0   1040 0  100,0 %

To nám říká, že testovací sada prověřila všechny možné větvení v kódu. Neznamená to sice stoprocentní záruku, že v kódu nejsou žádné chyby, ale znamená to, že prověřujeme každý řádek kódu v kódové základně.

Pokud provedete změny v kódu, může se stát, že v pokrytí vznikne mezera. V takovém případě vám zpráva o pokrytí ukáže, které řádky se neprovádějí. Řekněme například, že jsme provedli změnu v some/interesting_file.py, kde jsme přidali novou logiku. Zpráva o pokrytí by mohla vypadat například takto:

Název Příkazy   Chybějící větev BrPart  Pokrytí   Chybějící
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98,1 %   170, 302–307, 320–335
 -------------------------------------------------------------------------------
 CELKEM 7540 1   1726 0  99,9 %

Z toho vyplývá, že řádek 170, řádky 302–307 a skok z řádku 320 na řádek 335 nejsou v testovací sadě provedeny. Abyste toto pokrytí obnovili, budete muset přidat nové testy (nebo upravit stávající test).

Zpráva o kompatibilitě s hostitelskou platformou a verzí jazyka Python¶

Můžete vygenerovat zprávu o pokrytí pro vaši platformu a verzi jazyka Python. Chcete-li například spustit sadu testů a vygenerovat zprávu o pokrytí v Pythonu 3.10, zadejte:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

Zpráva o pokrytí pro hostitelskou platformu¶

Pokud má tox k dispozici všechny podporované verze jazyka Python, lze vygenerovat přehled pokrytí pro danou hostitelskou platformu spuštěním následujícího příkazu:

macOSLinuxWindows

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

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

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

Zprávy o pokrytí v HTML¶

Zprávu o pokrytí HTML lze vygenerovat připojením -html k libovolnému názvu prostředí pokrytí tox, například:

macOSLinuxWindows

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

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

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

Nejde jen o psaní testů!¶

I když dbáme na to, abychom otestovali veškerý náš kód, nejde jen o to, udržet tuto úroveň testování. Součástí úkolu je také průběžná kontrola kódu. Mohli byste napsat komplexní sadu testů pro konkrétní záchrannou vestu… ale konkrétní záchranná vesta by i tak byla k zamýšlenému účelu k ničemu!

Při vývoji testů byste měli také kontrolovat, zda je základní modul vnitřně konzistentní. Pokud si všimnete názvů metod, které nejsou vnitřně konzistentní (např. něco, co se v jednom modulu jmenuje on_select, ale v jiném on_selected), nebo kde se s daty nezachází konzistentně, označte to a upozorněte nás na to vytvořením ticketu. Nebo, pokud jste si jisti, že víte, co je třeba udělat, vytvořte pull request, který opraví problém, který jste našli.

Jakmile máte vše funkční, můžete odeslat žádost o stažení se svými změnami.