Pisanie, uruchamianie i testowanie kodu¶
Naprawienie błędu lub wdrożenie nowej funkcji będzie wymagało napisania nowego kodu.
Aby rozpocząć pracę nad kodem, upewnij się, że masz skonfigurowane środowisko programistyczne i pracujesz na gałęzi.
Mamy przewodnik stylistyczny dotyczący kodu, w którym przedstawiono wytyczne dotyczące pisania kodu dla BeeWare.
Programowanie sterowane testami¶
Dobrym sposobem na upewnienie się, że kod będzie działał zgodnie z oczekiwaniami, jest najpierw napisanie przypadku testowego, który to sprawdzi. Ten przypadek testowy powinien początkowo zakończyć się niepowodzeniem, ponieważ kod, który ma sprawdzić, jeszcze nie istnieje. Następnie można wprowadzić zmiany w kodzie niezbędne do pomyślnego przejścia testu i mieć pewność, że napisany kod rozwiązuje problem zgodnie z oczekiwaniami.
Uruchom swój kod¶
Po napisaniu kodu musisz upewnić się, że działa. Będziesz musiał ręcznie uruchomić kod, aby sprawdzić, czy działa zgodnie z oczekiwaniami. Jeśli jeszcze tego nie zrobiłeś, warto napisać przypadek testowy dla wprowadzonych zmian; jak wspomniano powyżej, test ten powinien zakończyć się niepowodzeniem, jeśli kod zostanie zakomentowany lub nie będzie obecny.
Dodaj swój przypadek testowy do zestawu testów, aby można go było uruchomić razem z pozostałymi testami. Następnym krokiem jest uruchomienie zestawu testów.
Uruchamianie testów oraz pokrycie¶
BeeWare wykorzystuje tox do
zarządzania procesem testowania oraz
pytest do obsługi własnego zestawu
testów.
Domyślne polecenie tox obejmuje wykonanie:
- haki przed zatwierdzeniem
- Sprawdzenie informacji o wydaniu
-
sprawdzanie poprawności kodu
-
zestaw testów dla dostępnych wersji języka Python
-
raportowanie pokrycia kodu
W zasadzie właśnie to uruchamia CI po przesłaniu pull requestu.
Aby uruchomić pełny zestaw testów, wpisz:
(.venv) $ tox
(.venv) $ tox
(.venv) C:\...>tox
Uruchomienie pełnego zestawu testów może chwilę potrwać. Można to znacznie
przyspieszyć, uruchamiając tox równolegle, czyli korzystając z opcji tox p
(lub tox run-parallel). W przypadku równoległego uruchamiania zestawu testów
otrzymasz mniej informacji zwrotnych na temat postępów w trakcie działania, ale
na koniec cyklu testowego nadal pojawi się podsumowanie wszelkich wykrytych
problemów. Powinieneś zobaczyć komunikat potwierdzający, że testy zostały
przeprowadzone. Możesz zobaczyć SKIPPED testów, ale nigdy nie powinieneś
otrzymać żadnych wyników testów FAIL lub ERROR. Przed scaleniem każdej
poprawki uruchamiamy nasz pełny zestaw testów. Jeśli proces ten wykryje
jakiekolwiek problemy, nie scalamy poprawki. Jeśli znajdziesz błąd lub
niepowodzenie testu, oznacza to, że albo coś jest nie tak w Twoim środowisku
testowym, albo znalazłeś skrajny przypadek, którego wcześniej nie widzieliśmy —
w każdym razie daj nam znać!
Oprócz pomyślnego zakończenia testów powinno to wykazać 100% pokrycie testowe.
Przeprowadzanie różnych wariantów testów¶
Przeprowadź testy dla wielu wersji języka Python¶
Domyślnie wiele poleceń tox próbuje uruchomić zestaw testów wielokrotnie – po
jednym razie dla każdej wersji języka Python obsługiwanej przez BeeWare. Aby było to możliwe, każda z tych wersji musi być zainstalowana na
komputerze użytkownika i dostępna dla procesu [wykrywania]tox języka Python
realizowanego przez
(https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery).
Ogólnie rzecz biorąc, jeśli dana wersja języka Python jest dostępna za
pośrednictwem PATH, to tox powinno być w stanie ją znaleźć i wykorzystać.
Uruchom tylko zestaw testów¶
Jeśli szybko wprowadzasz kolejne wersje nowej funkcji, nie musisz uruchamiać pełnego zestawu testów; możesz uruchomić tylko testy jednostkowe. Aby to zrobić, wpisz:
(.venv) $ tox -e py
(.venv) $ tox -e py
(.venv) C:\...>tox -e py
Uruchom podzbiór testów¶
Domyślnie polecenie tox uruchamia wszystkie testy z zestawu testów
jednostkowych. Podczas tworzenia nowego testu przydatne może być uruchomienie
tylko tego jednego testu. W tym celu można przekazać dowolny specyfikator
pytest
jako argument polecenia tox. Ścieżki do testów są podawane względem katalogu
briefcase. Na przykład, aby uruchomić tylko testy zawarte w jednym pliku,
należy wpisać:
(.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
Nawet jeśli uruchomisz tylko część zestawu testów, nadal otrzymasz raport pokrycia – jednak wyniki pokrycia będą obejmowały wyłącznie te linie kodu, które zostały wykonane przez konkretne testy, które uruchomiłeś.
Uruchom zestaw testów dla konkretnej wersji języka Python¶
Domyślnie tox -e py zostanie uruchomione przy użyciu interpretera, który na
danym komputerze zostanie rozpoznany jako python. Jeśli masz zainstalowanych
kilka wersji Pythona i chcesz przetestować konkretną wersję spośród
zainstalowanych, możesz wskazać konkretną wersję Pythona do użycia. Na przykład,
aby uruchomić zestaw testów w Pythonie 3.10, wpisz:
(.venv) $ tox -e py310
(.venv) $ tox -e py310
(.venv) C:\...>tox -e py310
Podzbiór testów [test-subset] można uruchomić, dodając do wiersza poleceń znak
-- oraz specyfikację testu.
Uruchom zestaw testów bez sprawdzania pokrycia (szybko)¶
Domyślnie polecenie tox uruchamia zestaw testów pytest w trybie jednowątkowym.
Można przyspieszyć wykonywanie zestawu testów, uruchamiając go równolegle. Tryb
ten nie generuje plików pokrycia ze względu na trudności związane z
rejestrowaniem pokrycia w uruchomionych procesach. Aby uruchomić pojedynczą
wersję Pythona w trybie „szybkim”, należy wpisać:
(.venv) $ tox -e py-fast
(.venv) $ tox -e py-fast
(.venv) C:\...>tox -e py-fast
Aby uruchomić podzbiór testów, należy dodać -- oraz
specyfikację testu do wiersza poleceń; aby użyć określonej wersji
Pythona, należy dodać tę wersję do celu testu (np. py310-fast w celu uruchomienia testu fast w Pythonie 3.10).
Pokrycie kodu¶
BeeWare zapewnia 100% pokrycie gałęzi w swoim kodzie źródłowym. Dodając lub modyfikując kod w projekcie, należy dodać kod testowy, aby zapewnić pokrycie wszystkich wprowadzonych zmian.
Jednak BeeWare jest przeznaczony dla wielu platform, a także dla wielu
wersji języka Python, więc nie da się zweryfikować pełnego pokrycia na jednej
platformie i w jednej wersji języka Python. Aby temu zaradzić, w sekcji
tool.coverage.coverage_conditional_plugin.rules pliku pyproject.toml
zdefiniowano kilka reguł warunkowego pokrycia (np. no-cover-if-is-windows może
służyć do oznaczenia bloku kodu, który nie zostanie wykonany podczas
uruchamiania zestawu testów w systemie Windows). Reguły te służą do
identyfikacji fragmentów kodu, które są objęte pokryciem tylko na określonych
platformach lub w określonych wersjach Pythona.
Warto zauważyć, że generowanie raportów pokrycia w różnych wersjach Pythona może przebiegać nieco nieprzewidywalnie. Na przykład, jeśli pliki pokrycia zostały utworzone przy użyciu jednej wersji Pythona, a raportowanie pokrycia odbywa się w innej, raport może zawierać fałszywe alarmy dotyczące pominiętych gałęzi. Z tego powodu do generowania raportów pokrycia należy zawsze używać najstarszej wersji Pythona, w której utworzono pliki pokrycia.
Interpretacja wyników badań¶
Na końcu wyników testu pokrycia powinno znaleźć się zestawienie zebranych danych dotyczących pokrycia:
Nazwa Wypowiedzi Nieobecności Oddziały Część Pokrycie Brakujące
---------------------------------------------------
RAZEM 7540 0 1040 0 100,0%
Oznacza to, że zestaw testów sprawdził wszystkie możliwe ścieżki rozgałęzień w kodzie. Nie daje to stuprocentowej gwarancji, że nie ma żadnych błędów, ale oznacza, że sprawdzamy każdą linię kodu w całym kodzie źródłowym.
Jeśli wprowadzisz zmiany w kodzie, może to spowodować powstanie luki w pokryciu.
W takim przypadku raport pokrycia wskaże, które linie nie są wykonywane. Załóżmy
na przykład, że wprowadziliśmy zmianę w some/interesting_file.py, dodając nową
logikę. Raport pokrycia mógłby wyglądać mniej więcej tak:
Nazwa Stmts Miss Branch BrPart Cover Brakujące
-------------------------------------------------------------------------------
src/some/interesting_file.py 111 1 26 0 98,1% 170, 302-307, 320->335
-------------------------------------------------------------------------------
RAZEM 7540 1 1726 0 99,9%
Oznacza to, że wiersz 170, wiersze 302–307 oraz skok rozgałęzienia z wiersza 320 do wiersza 335 nie są wykonywane przez zestaw testów. Aby przywrócić ten poziom pokrycia, należy dodać nowe testy (lub zmodyfikować istniejący test).
Raport dotyczący obsługi platformy hosta i wersji języka Python¶
Możesz wygenerować raport pokrycia dla swojej platformy i wersji języka Python. Na przykład, aby uruchomić zestaw testów i wygenerować raport pokrycia dla języka Python 3.10, wpisz:
(.venv) $ tox -m test310
(.venv) $ tox -m test310
(.venv) C:\...>tox -m test310
Raport dotyczący zasięgu dla platformy hostującej¶
Jeśli wszystkie obsługiwane wersje języka Python są dostępne dla tox, wówczas
pokrycie dla platformy hosta można sprawdzić, uruchamiając:
(.venv) $ tox p -m test-platform
(.venv) $ tox p -m test-platform
(.venv) C:\...>tox p -m test-platform
Raportowanie zasięgu w formacie HTML¶
Raport pokrycia HTML można wygenerować, dodając -html do dowolnej nazwy
środowiska pokrycia tox, na przykład:
(.venv) $ tox -e coverage-platform-html
(.venv) $ tox -e coverage-platform-html
(.venv) C:\...>tox -e coverage-platform-html
Nie chodzi tylko o pisanie testów!¶
Chociaż dbamy o to, by przetestować cały nasz kod, zadanie to nie polega tylko na utrzymaniu tego poziomu testowania. Częścią tego zadania jest bieżąca kontrola kodu. Można by napisać obszerny zestaw testów dla konkretnej kamizelki ratunkowej… ale taka kamizelka nadal byłaby bezużyteczna w zamierzonym celu!
Podczas tworzenia testów należy również sprawdzać, czy moduł podstawowy jest
spójny wewnętrznie. Jeśli zauważysz nazwy metod, które nie są spójne
wewnętrznie (np. coś nazywa się on_select w jednym module, a on_selected w
innym) lub dane nie są przetwarzane w spójny sposób, zaznacz to i zgłoś nam ten
problem, tworząc zgłoszenie. Jeśli natomiast jesteś pewien, co należy zrobić,
utwórz pull request, który naprawi znaleziony problem.
Gdy wszystko będzie już działać, możesz przesłać pull request ze swoimi zmianami.