Kod yazma, çalıştırma ve test etme¶

Bir hatayı düzeltmek veya bir özelliği eklemek için yeni kod yazmanız gerekecektir.

Kod üzerinde çalışmaya başlamak için, geliştirme ortamınızın kurulduğundan ve bir dal üzerinde çalıştığınızdan emin olun.

BeeWare için kod yazma kurallarımızı özetleyen bir kod stil kılavuzumuz bulunmaktadır.

Test odaklı geliştirme¶

Kodunuzun beklediğiniz şekilde çalışacağından emin olmanın iyi bir yolu, öncelikle bunu test etmek için bir test senaryosu yazmaktır. Test edilen kod henüz mevcut olmadığı için bu test senaryosu başlangıçta başarısız sonuç vermelidir. Ardından, testin başarılı olması için gereken kod değişikliklerini yazabilir ve yazdığınız kodun, beklediğiniz sorunu çözdüğünden emin olabilirsiniz.

Kodunu çalıştır¶

Kodunuzu yazdıktan sonra, kodun çalıştığından emin olmanız gerekir. Kodun beklediğiniz şekilde çalıştığını doğrulamak için onu manuel olarak çalıştırmanız gerekecektir. Henüz yapmadıysanız, yaptığınız değişiklikler için bir test senaryosu yazmanızda fayda var; yukarıda da belirtildiği gibi, kodunuz yorum satırına alınmışsa veya mevcut değilse bu test başarısız olmalıdır.

Test senaryonuzu test paketine ekleyeceksiniz, böylece diğer testlerle birlikte çalıştırılabilecektir. Bir sonraki adım, test paketini çalıştırmaktır.

Testleri çalıştırma ve kapsama oranı¶

BeeWare test sürecini yönetmek için tox'yi, kendi test paketini ise pytest'yi kullanır.

Varsayılan tox komutu aşağıdakileri içerir:

pre-commit kancaları
towncrier sürüm notu kontrolü
belge denetimi
mevcut Python sürümleri için test paketi
kod kapsamı raporlaması

Bir çekme isteği gönderdiğinizde CI tarafından çalıştırılan işlem temel olarak budur.

Tüm test paketini çalıştırmak için şunu girin:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

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

Test paketinin tamamının çalıştırılması biraz zaman alabilir. tox komutunu paralel olarak çalıştırarak veya tox p (ya da tox run-parallel) komutunu kullanarak bu süreci önemli ölçüde hızlandırabilirsiniz. Test paketini paralel olarak çalıştırdığınızda, testler devam ederken ilerleme durumuna ilişkin daha az geri bildirim alırsınız, ancak test çalışmasının sonunda tespit edilen sorunların bir özetini yine de görürsünüz. Testlerin çalıştırıldığını belirten bir çıktı almalısınız. SKIPPED testlerini görebilirsiniz, ancak hiçbir zaman FAIL veya ERROR test sonuçları almamalısınız. Her yamayı birleştirmeden önce tam test paketimizi çalıştırırız. Bu işlemde herhangi bir sorun tespit edilirse, yamayı birleştirmeyiz. Bir test hatası veya başarısızlığı bulursanız, ya test ortamınızda garip bir durum vardır ya da daha önce görmediğimiz bir sınır durumu bulmuşsunuzdur - her iki durumda da bize bildirin!

Testlerin başarılı olmasının yanı sıra, bu durum %100 test kapsamı olarak raporlanmalıdır.

Test varyasyonlarını çalıştırma¶

Python'un farklı sürümleri için testler çalıştırın¶

Varsayılan olarak, tox komutlarının çoğu, BeeWare tarafından desteklenen her Python sürümü için birer kez olmak üzere test paketini birden fazla kez çalıştırmaya çalışır. Ancak bunun için, her bir Python sürümünün bilgisayarınızda yüklü olması ve tox'nin Python keşif işlemi tarafından algılanabilmesi gerekir. Genel olarak, bir Python sürümü PATH aracılığıyla erişilebilirse, tox bu sürümü bulup kullanabilmelidir.

Yalnızca test paketini çalıştır¶

Yeni bir özellik üzerinde hızlı bir şekilde yineleme yapıyorsanız, test paketinin tamamını çalıştırmanıza gerek yoktur; sadece birim testlerini çalıştırabilirsiniz. Bunu yapmak için şu komutu çalıştırın:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Testlerin bir kısmını çalıştır¶

Varsayılan olarak, tox komutu birim test paketindeki tüm testleri çalıştırır. Yeni bir test geliştirirken, sadece o testi çalıştırmak faydalı olabilir. Bunu yapmak için, pytest komutuna argüman olarak [herhangi bir (https://docs.pytest.org/en/latest/how-to/usage.html#specifying-which-tests-to-run) belirteci]tox geçirebilirsiniz. Bu test yolları, briefcase dizinine göre görelidir. Örneğin, tek bir dosyadaki testleri çalıştırmak için şunu girin:

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

Test paketinin bir bölümünü çalıştırdığınızda yine de bir kapsama raporu alacaksınız; ancak kapsama sonuçları, yalnızca çalıştırdığınız belirli testler tarafından yürütülen kod satırlarını gösterecektir.

Belirli bir Python sürümü için test paketini çalıştır¶

Varsayılan olarak tox -e py, bilgisayarınızda python olarak çözümlenen herhangi bir yorumlayıcı kullanılarak çalıştırılır. Bilgisayarınızda birden fazla Python sürümü yüklüyse ve yüklü sürümlerden belirli bir Python sürümünü test etmek istiyorsanız, kullanılacak Python sürümünü belirtebilirsiniz. Örneğin, test paketini Python 3.10 üzerinde çalıştırmak için şu komutu çalıştırın:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

Bir test kümesi, komut satırına -- ve bir test tanımı eklenerek çalıştırılabilir.

Test paketini kapsama analizi yapmadan çalıştır (hızlı)¶

Varsayılan olarak, tox test dizisini tek iş parçacıklı modda çalıştırır. Test dizisini paralel olarak çalıştırarak yürütme süresini kısaltabilirsiniz. Bu modda, başlatılan işlemler içinde kapsama oranını yakalamanın karmaşıklığı nedeniyle kapsama dosyaları oluşturulmaz. Tek bir Python sürümünü "hızlı" modda çalıştırmak için şunu çalıştırın:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

Bir test kümesi, komut satırına -- ve bir test tanımı eklenerek çalıştırılabilir; belirli bir Python sürümü, test hedefine sürüm eklenerek kullanılabilir (örneğin, Python py310-fast üzerinde hızlı çalıştırmak için 3.10).

Kod kapsamı¶

BeeWare kod tabanında %100 test kapsamı sağlar. Projeye kod eklediğinizde veya mevcut kodu değiştirdiğinizde, yaptığınız değişikliklerin test kapsamına alınmasını sağlamak için test kodu eklemeniz gerekir.

Ancak, BeeWare hem birden fazla platformu hem de Python'un çeşitli sürümlerini hedeflediğinden, tam kapsam tek bir platform ve Python sürümünde doğrulanamaz. Bunu telafi etmek için, tool.coverage.coverage_conditional_plugin.rules bölümünde birkaç koşullu kapsama kuralı tanımlanmıştır (örneğin, pyproject.toml Windows'ta test takımını çalıştırırken yürütülmeyecek bir kod bloğunu işaretlemek için kullanılabilir). Bu kurallar, yalnızca belirli platformlarda veya Python sürümlerinde kapsanan kod bölümlerini tanımlamak için kullanılır.

Dikkat edilmesi gereken bir nokta, farklı Python sürümleri arasında kod kapsama raporlamasının biraz tuhaf sonuçlar verebilmesidir. Örneğin, kapsama dosyaları bir Python sürümüyle oluşturulmuş ancak raporlama başka bir sürümde yapılmışsa, raporda gözden kaçan dallara ilişkin yanlış pozitif sonuçlar yer alabilir. Bu nedenle, kod kapsama raporlamasında her zaman kapsama dosyalarının oluşturulmasında kullanılan en eski Python sürümü kullanılmalıdır.

Kapsam sonuçlarını anlamak¶

Kapsama testi çıktısının sonunda, toplanan kapsama verilerine ilişkin bir rapor bulunmalıdır:

Adı    Hesaplar   Kayıp Şube BrPart   Kapsam   Eksik
 ---------------------------------------------------
 TOPLAM    7540 0   1040 0  100,0%

Bu, test takımının koddaki tüm olası dallanma yollarını çalıştırdığını gösterir. Bu, hata olmadığına dair %100 bir garanti değildir, ancak kod tabanındaki her satırı test ettiğimiz anlamına gelir.

Kod tabanında değişiklik yaparsanız, bu kapsama alanında bir boşluk oluşabilir. Böyle bir durumda, kapsama raporu hangi satırların çalıştırılmadığını size gösterecektir. Örneğin, some/interesting_file.py içinde bir değişiklik yapıp yeni bir mantık eklediğimizi varsayalım. Kapsama raporu şunun gibi görünebilir:

Adımlar   Hata   Dal   BrPart  Kapsam   Eksik
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  %98,1   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 TOPLAM 7540 1   1726 0  %99,9

Bu, 170. satırın, 302-307. satırların ve 320. satırdan 335. satıra atlayan bir dalın test paketi tarafından çalıştırılmadığını gösteriyor. Bu kapsama oranını geri kazanmak için yeni testler eklemeniz (veya mevcut bir testi değiştirmeniz) gerekecek.

Ana platform ve Python sürümü için uyumluluk raporu¶

Kullandığınız Python platformu ve sürümü için bir kapsama raporu oluşturabilirsiniz. Örneğin, test takımını çalıştırıp Python 3.10 için bir kapsama raporu oluşturmak için şu komutu çalıştırın:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

Ana platform için kapsama raporu¶

Python'un desteklenen tüm sürümleri tox için mevcutsa, ana platformun kapsama oranı şu komut çalıştırılarak raporlanabilir:

macOSLinuxWindows

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

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

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

HTML'de kapsam raporlaması¶

Kapsam -html ortam adlarının herhangi birinin sonuna tox eklenerek bir HTML kapsam raporu oluşturulabilir; örneğin:

macOSLinuxWindows

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

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

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

Mesele sadece test yazmak değil!¶

Her ne kadar tüm kodlarımızı test ettiğimizden emin olsak da, bu iş sadece bu test düzeyini korumaktan ibaret değildir. Bu işin bir parçası da, kod üzerinde çalışırken onu denetlemektir. Somut bir can yeleği için kapsamlı bir test dizisi yazabilirsiniz… ama somut bir can yeleği yine de asıl amacına uygun olarak kullanılamaz!

Testler geliştirirken, çekirdek modülün içsel olarak da tutarlı olup olmadığını kontrol etmelisiniz. İçsel olarak tutarlı olmayan yöntem adları fark ederseniz (örneğin, bir modülde on_select olarak adlandırılan, ancak başka bir modülde on_selected olarak adlandırılan bir şey) veya verilerin tutarlı bir şekilde işlenmediği durumlar varsa, bunu işaretleyin ve bir bilet açarak bize bildirin. Ya da ne yapılması gerektiğini bildiğinizden eminseniz, bulduğunuz sorunu düzelten bir çekme isteği oluşturun.

Her şey çalışır hale geldiğinde, değişikliklerinizi içeren bir çekme isteği gönderin.