콘텐츠로 이동

코드를 작성하고, 실행하고, 테스트하기

버그를 수정하거나 기능을 구현하려면 새로운 코드를 작성해야 합니다.

코드를 작업하기 시작하려면 개발 환경을 설정하고 브랜치에서 작업 중인지 확인하십시오.

BeeWare용 코드 작성 지침을 정리한 코드 스타일 가이드가 마련되어 있습니다.

테스트 주도 개발

코드가 의도한 대로 동작하는지 확인하는 좋은 방법은 먼저 해당 기능을 테스트할 테스트 케이스를 작성하는 것입니다. 테스트 대상 코드가 아직 구현되지 않았기 때문에, 이 테스트 케이스는 처음에는 실패해야 합니다. 그런 다음 테스트가 통과되도록 필요한 코드 수정을 가하면, 작성한 코드가 의도한 문제를 해결하고 있음을 확인할 수 있습니다.

코드를 실행하세요

코드를 작성한 후에는 제대로 실행되는지 확인해야 합니다. 코드를 직접 실행하여 예상한 대로 동작하는지 검증해야 합니다. 아직 하지 않았다면, 변경 사항에 대한 테스트 케이스를 작성하는 것이 좋습니다. 앞서 언급했듯이, 코드가 주석 처리되었거나 존재하지 않을 경우 이 테스트는 실패해야 합니다.

테스트 케이스를 테스트 스위트에 추가하면 다른 테스트들과 함께 실행할 수 있습니다. 다음 단계는 테스트 스위트를 실행하는 것입니다.

테스트 실행 및 커버리지

BeeWare는 테스트 프로세스를 관리하기 위해 tox를 사용하고, 자체 테스트 스위트에는 pytest를 사용합니다.

기본 tox 명령어에는 다음 작업이 포함됩니다:

  • 커밋 전 훅
  • towncrier 릴리스 노트 확인

  • 문서 코드 검사

  • 사용 가능한 Python 버전을 위한 테스트 모음

  • 코드 커버리지 보고

이것이 바로 풀 리퀘스트를 제출할 때 CI에서 실행되는 작업의 핵심입니다.

전체 테스트 모음을 실행하려면 다음 명령을 실행하십시오:

(.venv) $ tox

(.venv) $ tox

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

전체 테스트 스위트를 실행하는 데는 시간이 다소 걸릴 수 있습니다. tox을 병렬로 실행하거나 tox p (또는 tox run-parallel)을 실행하면 속도를 상당히 높일 수 있습니다. 테스트 스위트를 병렬로 실행하면 진행 상황에 대한 피드백은 줄어들지만, 테스트 실행이 끝난 후에는 발견된 문제에 대한 요약 정보를 여전히 확인할 수 있습니다. 테스트가 실행되었음을 나타내는 출력 결과가 표시되어야 합니다. SKIPPED 테스트가 표시될 수는 있지만, FAIL 또는 ERROR 테스트 결과는 절대 나타나지 않아야 합니다. 우리는 모든 패치를 병합하기 전에 전체 테스트 스위트를 실행합니다. 이 과정에서 문제가 발견되면 해당 패치는 병합하지 않습니다. 만약 테스트 오류나 실패를 발견했다면, 테스트 환경에 문제가 있거나 우리가 이전에 보지 못했던 극단적인 사례를 발견한 것입니다. 어느 쪽이든 저희에게 알려주세요!

테스트가 통과되는 것 외에도, 100% 테스트 커버리지가 보고되어야 합니다.

테스트 변형 실행

여러 버전의 파이썬에 대해 테스트 실행하기

기본적으로 많은 tox 명령어는 BeeWare가 지원하는 각 Python 버전에 대해 한 번씩, 총 여러 번 테스트 스위트를 실행하려고 시도합니다. 하지만 이를 위해서는 각 Python 버전이 사용자의 컴퓨터에 설치되어 있어야 하며, tox의 Python 탐색 프로세스에서 이를 감지할 수 있어야 합니다. 일반적으로, 특정 Python 버전이 PATH를 통해 사용 가능한 경우, tox는 이를 찾아서 사용할 수 있어야 합니다.

테스트 스위트만 실행

새로운 기능을 빠르게 반복 개발하고 있다면 전체 테스트 스위트를 실행할 필요는 없으며, 단순히 단위 테스트만 실행하면 됩니다. 이를 위해 다음 명령어를 실행하세요:

(.venv) $ tox -e py

(.venv) $ tox -e py

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

테스트의 일부만 실행하기

기본적으로 tox는 단위 테스트 모음에 포함된 모든 테스트를 실행합니다. 새로운 테스트를 개발할 때는 해당 테스트 하나만 실행하는 것이 유용할 수 있습니다. 이를 위해 pytest에 [임의의 (https://docs.pytest.org/en/latest/how-to/usage.html#specifying-which-tests-to-run) 지정자]tox를 인수로 전달할 수 있습니다. 이러한 테스트 경로는 briefcase 디렉터리를 기준으로 합니다. 예를 들어, 단일 파일에 포함된 테스트만 실행하려면 다음 명령을 실행하세요:

(.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

테스트 스위트의 일부만 실행하더라도 커버리지 보고서는 여전히 생성되지만, 커버리지 결과에는 실행한 특정 테스트에서 실제로 실행된 코드 줄만 표시됩니다.

특정 Python 버전에 대한 테스트 모음을 실행합니다

기본적으로 tox -e py는 사용자의 컴퓨터에서 python로 해석되는 인터프리터를 사용하여 실행됩니다. 여러 버전의 파이썬이 설치되어 있고, 설치된 버전 중 특정 버전을 사용하여 테스트를 실행하려면 사용할 파이썬 버전을 명시적으로 지정할 수 있습니다. 예를 들어, 파이썬 3.10에서 테스트 모음을 실행하려면 다음 명령을 실행하십시오:

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

명령줄에 --와 테스트 사양을 추가하면 테스트 집합을 실행할 수 있습니다.

커버리지 분석 없이 테스트 스위트 실행 (빠름)

기본적으로 tox는 단일 스레드 모드에서 pytest 테스트 스위트를 실행합니다. 테스트 스위트를 병렬로 실행하면 실행 속도를 높일 수 있습니다. 이 모드는 생성된 프로세스 내에서 커버리지를 캡처하는 것이 복잡하기 때문에 커버리지 파일을 생성하지 않습니다. 단일 Python 버전을 "fast" 모드로 실행하려면 다음 명령을 실행하십시오:

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

명령줄에 --와 테스트 사양을 추가하면 테스트의 일부를 실행할 수 있으며, 테스트 대상에 버전을 추가하면 특정 Python 버전을 사용할 수 있습니다(예: Python py310-fast에서 fast를 실행하려면 3.10를 추가).

코드 커버리지

BeeWare는 코드베이스에서 100%의 브랜치 커버리지를 유지하고 있습니다. 프로젝트에서 코드를 추가하거나 수정할 때는, 변경 사항이 모두 테스트를 통과하도록 테스트 코드를 반드시 추가해야 합니다.

그러나 BeeWare는 여러 플랫폼과 다양한 Python 버전을 대상으로 하므로, 단일 플랫폼 및 Python 버전에서만으로는 전체 커버리지를 검증할 수 없습니다. 이를 해결하기 위해 tool.coverage.coverage_conditional_plugin.rules의 pyproject.toml 섹션에는 여러 조건부 커버리지 규칙이 정의되어 있습니다(예: no-cover-if-is-windows는 Windows에서 테스트 스위트를 실행할 때 실행되지 않는 코드 블록을 표시하는 데 사용할 수 있습니다). 이러한 규칙은 특정 플랫폼이나 Python 버전에서만 커버되는 코드 섹션을 식별하는 데 사용됩니다.

특히, 서로 다른 Python 버전을 사용해 커버리지 보고서를 작성할 경우 다소 예기치 않은 결과가 발생할 수 있습니다. 예를 들어, 커버리지 파일을 생성할 때는 특정 버전의 Python을 사용했으나 보고서를 생성할 때는 다른 버전을 사용한 경우, 보고서에 누락된 분기에 대한 오탐이 포함될 수 있습니다. 따라서 커버리지 보고서를 작성할 때는 항상 커버리지 파일을 생성하는 데 사용된 Python 버전 중 가장 오래된 버전을 사용해야 합니다.

보장 범위 결과 이해하기

커버리지 테스트 출력물의 마지막 부분에는 수집된 커버리지 데이터에 대한 보고서가 나와야 합니다:

이름    명세서   미결제 지점   부분결제   대납   누락
 ---------------------------------------------------
 합계    7540 0   1040 0  100.0%

이는 테스트 스위트가 코드 내의 모든 가능한 분기 경로를 실행했음을 의미합니다. 이것이 버그가 전혀 없다는 것을 100% 보장하는 것은 아니지만, 코드베이스의 모든 코드 줄을 실제로 테스트하고 있다는 뜻입니다.

코드베이스에 변경 사항을 적용하면 커버리지에 공백이 생길 수 있습니다. 이런 경우 커버리지 보고서를 통해 어떤 줄이 실행되지 않는지 확인할 수 있습니다. 예를 들어, some/interesting_file.py에 새로운 로직을 추가하는 변경을 가했다고 가정해 봅시다. 커버리지 보고서는 다음과 같이 표시될 수 있습니다:

이름 문장 수   누락 분기 BrPart  커버   누락
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98.1%   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 총계 7540 1   1726 0  99.9%

이는 170행, 302~307행, 그리고 320행에서 335행으로 이동하는 분기문이 테스트 스위트에 의해 실행되지 않고 있음을 의미합니다. 이 커버리지를 복원하려면 새로운 테스트를 추가하거나 기존 테스트를 수정해야 합니다.

호스트 플랫폼 및 Python 버전에 대한 지원 현황 보고서

사용 중인 플랫폼과 Python 버전에 대한 커버리지 보고서를 생성할 수 있습니다. 예를 들어, 테스트 스위트를 실행하고 Python 3.10에 대한 커버리지 보고서를 생성하려면 다음 명령을 실행하세요:

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

호스트 플랫폼에 대한 커버리지 보고서

tox에서 지원되는 모든 Python 버전을 사용할 수 있다면, 다음 명령을 실행하여 호스트 플랫폼에 대한 커버리지 결과를 확인할 수 있습니다:

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

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

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

HTML 형식의 보도 내용

커버리지 -html 환경 이름 뒤에 tox를 추가하면 HTML 커버리지 보고서를 생성할 수 있습니다. 예를 들어:

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

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

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

단순히 테스트를 작성하는 것만이 전부가 아닙니다!

비록 우리가 모든 코드를 철저히 테스트하고는 있지만, 이 작업은 단순히 그 수준의 테스트를 유지하는 데 그치는 것이 아닙니다. 작업의 일부는 개발 과정에서 코드를 지속적으로 점검하는 것입니다. 콘크리트 구명조끼를 위한 포괄적인 테스트 세트를 작성할 수는 있겠지만… 그런 구명조끼는 본래의 용도에는 여전히 쓸모가 없을 테니까요!

테스트를 개발할 때는 핵심 모듈이 내부적으로도 일관성을 유지하는지 확인해야 합니다. 내부적으로 일관성이 없는 메서드 이름(예: 한 모듈에서는 on_select이라고 불리지만 다른 모듈에서는 on_selected이라고 불리는 경우)이나 데이터가 일관성 없이 처리되는 부분을 발견하면, 이를 표시해 두고 티켓을 생성하여 저희에게 알려주십시오. 또는 해결 방법을 확실히 알고 있다면, 발견한 문제를 수정하는 풀 리퀘스트를 생성해 주십시오.

모든 것이 정상적으로 작동하는지 확인한 후에는 변경 사항을 포함한 풀 리퀘스트 제출을 할 수 있습니다.