Viết, chạy và kiểm thử mã nguồn¶
Để sửa lỗi hoặc triển khai một tính năng, bạn sẽ cần phải viết một số đoạn mã mới.
Để bắt đầu viết mã, hãy đảm bảo rằng bạn đã thiết lập xong môi trường phát triển và đang làm việc trên một nhánh
Chúng tôi có một hướng dẫn phong cách viết mã nêu rõ các nguyên tắc viết mã cho BeeWare.
Phát triển hướng kiểm thử¶
Một cách hiệu quả để đảm bảo mã nguồn của bạn sẽ hoạt động đúng như mong đợi là trước tiên hãy viết một trường hợp kiểm thử để kiểm tra chức năng đó. Trường hợp kiểm thử này ban đầu sẽ không thành công, vì đoạn mã cần kiểm tra vẫn chưa được triển khai. Sau đó, bạn có thể thực hiện các thay đổi cần thiết để trường hợp kiểm thử này thành công, và từ đó biết chắc rằng những gì bạn đã viết đang giải quyết đúng vấn đề mà bạn mong đợi.
Chạy mã của bạn¶
Sau khi đã viết xong mã, bạn cần đảm bảo rằng nó hoạt động bình thường. Bạn sẽ phải chạy mã thủ công để kiểm tra xem nó có hoạt động đúng như mong đợi hay không. Nếu chưa làm, bạn nên viết một trường hợp kiểm thử cho các thay đổi của mình; như đã đề cập ở trên, trường hợp kiểm thử này sẽ báo lỗi nếu mã của bạn bị bỏ qua (commented out) hoặc không tồn tại.
Bạn sẽ thêm trường hợp kiểm thử của mình vào bộ kiểm thử để nó có thể được chạy cùng với các bài kiểm thử khác. Bước tiếp theo là chạy bộ kiểm thử.
Chạy các bài kiểm tra và độ bao phủ¶
BeeWare Docs Tools sử dụng tox để quản lý quy
trình kiểm thử và pytest cho bộ kiểm thử
của riêng mình.
Lệnh tox mặc định bao gồm việc thực thi:
- các hook trước khi commit
towncrierKiểm tra ghi chú phát hành-
kiểm tra cú pháp tài liệu
-
bộ kiểm thử cho các phiên bản Python hiện có
-
báo cáo độ bao phủ mã
Đây chính là quy trình mà CI thực hiện khi bạn gửi yêu cầu pull.
Để chạy toàn bộ bộ kiểm thử, hãy thực hiện lệnh sau:
(.venv) $ tox
(.venv) $ tox
(.venv) C:\...>tox
Việc chạy toàn bộ bộ kiểm thử có thể mất một thời gian. Bạn có thể tăng tốc đáng
kể bằng cách chạy tox song song, bằng cách chạy tox p (hoặc tox
run-parallel). Khi chạy bộ kiểm thử song song, bạn sẽ nhận được ít thông tin
phản hồi hơn về tiến trình của bộ kiểm thử trong khi chạy, nhưng vẫn sẽ nhận
được bản tóm tắt về bất kỳ vấn đề nào được phát hiện vào cuối quá trình chạy
kiểm thử. Bạn sẽ thấy một số kết quả cho biết các bài kiểm thử đã được chạy. Bạn
có thể thấy các bài kiểm tra SKIPPED, nhưng không bao giờ nhận được kết quả
kiểm tra FAIL hoặc ERROR. Chúng tôi chạy bộ kiểm tra đầy đủ trước khi hợp
nhất mọi bản vá. Nếu quá trình đó phát hiện bất kỳ vấn đề nào, chúng tôi sẽ
không hợp nhất bản vá. Nếu bạn phát hiện lỗi hoặc thất bại trong kiểm tra, hoặc
là có điều gì đó bất thường trong môi trường kiểm tra của bạn, hoặc bạn đã phát
hiện một trường hợp ngoại lệ mà chúng tôi chưa từng gặp trước đây - dù là trường
hợp nào, hãy cho chúng tôi biết!
Ngoài việc các bài kiểm tra đã vượt qua, điều này cũng nên cho thấy độ bao phủ kiểm tra 100%.
Chạy các biến thể thử nghiệm¶
Chạy các bài kiểm tra cho nhiều phiên bản Python¶
Theo mặc định, nhiều lệnh tox sẽ cố gắng chạy bộ kiểm thử nhiều lần, mỗi lần
tương ứng với một phiên bản Python được BeeWare Docs Tools hỗ trợ. Tuy nhiên, để
thực hiện điều này, mỗi phiên bản Python phải được cài đặt trên máy tính của bạn
và có thể được quá trình [phát hiện]tox Python của
(https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery) tìm
thấy. Nói chung, nếu một phiên bản Python có sẵn thông qua PATH, thì tox sẽ
có thể tìm thấy và sử dụng nó.
Chỉ chạy bộ kiểm thử¶
Nếu bạn đang liên tục cải tiến một tính năng mới, bạn không cần phải chạy toàn bộ bộ kiểm thử; bạn có thể chỉ chạy các bài kiểm thử đơn vị. Để thực hiện việc này, hãy chạy lệnh:
(.venv) $ tox -e py
(.venv) $ tox -e py
(.venv) C:\...>tox -e py
Chạy một tập hợp con các bài kiểm tra¶
Theo mặc định, tox sẽ chạy tất cả các bài kiểm thử trong bộ kiểm thử đơn vị.
Khi bạn đang phát triển bài kiểm thử mới, việc chỉ chạy duy nhất bài kiểm thử
đó có thể rất hữu ích. Để thực hiện điều này, bạn có thể truyền bất kỳ chỉ định
pytest
nào
làm tham số cho tox. Các đường dẫn kiểm thử này được tính theo thư mục
briefcase. Ví dụ: để chỉ chạy các bài kiểm thử trong một tệp duy nhất, hãy
chạy:
(.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
Bạn vẫn sẽ nhận được báo cáo độ bao phủ khi chạy một phần của bộ kiểm thử — nhưng kết quả độ bao phủ sẽ chỉ liệt kê các dòng mã đã được thực thi bởi các bài kiểm thử cụ thể mà bạn đã chạy.
Chạy bộ kiểm thử cho một phiên bản Python cụ thể¶
Theo mặc định, tox -e py sẽ chạy bằng trình thông dịch nào được xác định là
python trên máy của bạn. Nếu bạn đã cài đặt nhiều phiên bản Python và muốn
kiểm tra một phiên bản cụ thể trong số các phiên bản đã cài đặt, bạn có thể chỉ
định phiên bản Python cụ thể để sử dụng. Ví dụ: để chạy bộ kiểm thử trên Python
3.10, hãy chạy lệnh:
(.venv) $ tox -e py310
(.venv) $ tox -e py310
(.venv) C:\...>tox -e py310
Có thể chạy một tập con các bài kiểm tra bằng cách thêm -- và
thông số kỹ thuật của bài kiểm tra vào dòng lệnh.
Chạy bộ kiểm thử mà không tính độ bao phủ (nhanh)¶
Theo mặc định, tox sẽ chạy bộ kiểm thử pytest ở chế độ một luồng. Bạn có thể
tăng tốc độ thực thi bộ kiểm thử bằng cách chạy bộ kiểm thử song song. Chế độ
này không tạo ra các tệp độ bao phủ do sự phức tạp trong việc thu thập dữ liệu
độ bao phủ trong các tiến trình được khởi tạo. Để chạy một phiên bản Python duy
nhất ở chế độ "nhanh", hãy thực thi lệnh:
(.venv) $ tox -e py-fast
(.venv) $ tox -e py-fast
(.venv) C:\...>tox -e py-fast
Có thể chạy một tập con các bài kiểm thử bằng cách thêm -- và
thông số kỹ thuật của bài kiểm thử vào dòng lệnh; có thể sử dụng một phiên bản
Python cụ thể bằng cách thêm phiên bản đó vào mục tiêu kiểm
thử (ví dụ: py310-fast để chạy nhanh trên Python 3.10).
Độ bao phủ mã¶
BeeWare Docs Tools duy trì độ bao phủ nhánh 100% trong cơ sở mã của mình. Khi bạn thêm hoặc sửa đổi mã trong dự án, bạn phải thêm mã kiểm thử để đảm bảo độ bao phủ cho mọi thay đổi mà bạn thực hiện.
Tuy nhiên, BeeWare Docs Tools nhắm đến nhiều nền tảng cũng như nhiều phiên bản
Python, do đó không thể xác minh độ bao phủ đầy đủ trên một nền tảng và phiên
bản Python duy nhất. Để giải quyết vấn đề này, một số quy tắc độ bao phủ có điều
kiện được định nghĩa trong phần
tool.coverage.coverage_conditional_plugin.rules của pyproject.toml (ví dụ:
no-cover-if-is-windows có thể được sử dụng để đánh dấu một khối mã sẽ không
được thực thi khi chạy bộ kiểm thử trên Windows). Các quy tắc này được sử dụng
để xác định các phần mã chỉ được bao phủ trên các nền tảng hoặc phiên bản Python
cụ thể.
Điều cần lưu ý là việc báo cáo độ bao phủ giữa các phiên bản Python có thể gặp một số vấn đề. Ví dụ, nếu các tệp độ bao phủ được tạo ra bằng một phiên bản Python nhưng việc báo cáo lại được thực hiện trên một phiên bản khác, báo cáo có thể chứa các kết quả dương tính giả liên quan đến các nhánh bị bỏ sót. Do đó, khi báo cáo độ bao phủ, nên luôn sử dụng phiên bản Python cũ nhất đã được dùng để tạo ra các tệp độ bao phủ.
Hiểu về kết quả bảo hiểm¶
Ở phần cuối của kết quả kiểm tra độ bao phủ, cần có một báo cáo về dữ liệu độ bao phủ đã thu thập được:
Name Stmts Miss Branch BrPart Cover Missing
---------------------------------------------------
TOTAL 7540 0 1040 0 100.0%
Điều này cho thấy bộ kiểm thử đã thực thi mọi nhánh có thể có trong mã nguồn. Điều này không đảm bảo 100% rằng không có lỗi, nhưng nó có nghĩa là chúng ta đang kiểm tra từng dòng mã trong cơ sở mã.
Nếu bạn thực hiện thay đổi đối với cơ sở mã, có thể sẽ xuất hiện lỗ hổng trong
phạm vi kiểm tra. Khi điều này xảy ra, báo cáo phạm vi kiểm tra sẽ cho bạn biết
những dòng mã nào không được thực thi. Ví dụ, giả sử chúng ta đã thực hiện một
thay đổi đối với some/interesting_file.py, bổ sung một số logic mới. Báo cáo
phạm vi kiểm tra có thể trông như sau:
Name Stmts Miss Branch BrPart Cover Missing
-------------------------------------------------------------------------------
src/some/interesting_file.py 111 1 26 0 98.1% 170, 302-307, 320->335
-------------------------------------------------------------------------------
TOTAL 7540 1 1726 0 99.9%
Điều này cho thấy rằng dòng 170, các dòng 302–307 và một lệnh nhảy từ dòng 320 sang dòng 335 không được bộ kiểm thử thực thi. Bạn cần thêm các bài kiểm thử mới (hoặc sửa đổi bài kiểm thử hiện có) để khôi phục độ bao phủ này.
Báo cáo về nền tảng chủ và phiên bản Python¶
Bạn có thể tạo báo cáo độ bao phủ cho nền tảng và phiên bản Python của mình. Ví dụ: để chạy bộ kiểm thử và tạo báo cáo độ bao phủ trên Python 3.10, hãy thực thi lệnh:
(.venv) $ tox -m test310
(.venv) $ tox -m test310
(.venv) C:\...>tox -m test310
Báo cáo phạm vi hỗ trợ cho nền tảng chủ¶
Nếu tất cả các phiên bản Python được hỗ trợ đều có sẵn cho tox, thì có thể báo
cáo mức độ bao phủ cho nền tảng máy chủ bằng cách chạy:
(.venv) $ tox p -m test-platform
(.venv) $ tox p -m test-platform
(.venv) C:\...>tox p -m test-platform
Báo cáo phạm vi phủ sóng bằng HTML¶
Có thể tạo báo cáo độ bao phủ HTML bằng cách thêm -html vào bất kỳ tên môi
trường độ bao phủ tox nào, ví dụ:
(.venv) $ tox -e coverage-platform-html
(.venv) $ tox -e coverage-platform-html
(.venv) C:\...>tox -e coverage-platform-html
Không chỉ đơn thuần là viết các bài kiểm thử!¶
Mặc dù chúng tôi đảm bảo rằng tất cả mã nguồn đều được kiểm thử, nhưng nhiệm vụ này không chỉ đơn thuần là duy trì mức độ kiểm thử đó. Một phần của nhiệm vụ là kiểm tra mã nguồn trong quá trình phát triển. Bạn có thể viết một bộ kiểm thử toàn diện cho một chiếc áo phao bằng bê tông… nhưng chiếc áo phao bằng bê tông đó vẫn sẽ vô dụng đối với mục đích mà nó được thiết kế!
Khi phát triển các bài kiểm thử, bạn cũng nên kiểm tra xem mô-đun cốt lõi có
nhất quán về mặt nội bộ hay không. Nếu bạn phát hiện bất kỳ tên phương thức
nào không nhất quán bên trong (ví dụ: một phương thức được gọi là on_select
trong một mô-đun, nhưng lại được gọi là on_selected trong mô-đun khác), hoặc
nơi dữ liệu không được xử lý một cách nhất quán, hãy đánh dấu vấn đề đó và thông
báo cho chúng tôi bằng cách tạo một ticket. Hoặc, nếu bạn tự tin rằng mình biết
cần phải làm gì, hãy tạo một pull request để khắc phục vấn đề mà bạn đã phát
hiện.
Khi mọi thứ đã hoạt động bình thường, bạn có thể gửi yêu cầu pull kèm theo các thay đổi của mình.