Python Doctest로 함수의 테스트 코드 작성하기

낱글

2024. 11. 13. PM 2:44:22

#python #test #doctest #테스트 #pytest #문서화

Docstring

Python에서 Docstring은 함수, 클래스, 모듈 또는 메서드의 첫 번째 문장으로 작성되는 문자열이예요. Docstring이 작성된 해당 코드 블록의 목적이나 동작을 설명하는 데 사용되죠. docstring은 코드의 가독성과 유지 관리를 향상시키는 데 중요한 역할을 하며, 다양한 도구를 통해 자동으로 문서를 생성하는 데 활용돼요.

def add(a, b):
    """
    두 숫자 a와 b를 더하는 함수.

    매개변수:
        a (int or float): 첫 번째 숫자.
        b (int or float): 두 번째 숫자.

    반환값:
        int or float: 두 숫자의 합.
    """
    return a + b

Docstring은 Python 객체의 __doc__ 속성으로 존재해요.

>>> print(add.__doc__)

    두 숫자 a와 b를 더하는 함수.

    매개변수:
        a (int or float): 첫 번째 숫자.
        b (int or float): 두 번째 숫자.

    반환값:
        int or float: 두 숫자의 합.

또는 Python 내장 함수인 help()를 사용해도 Docstring을 볼 수 있어요.

>>> help(add)

비주얼 스튜디오 코드처럼 Python을 지원하는 코드 에디터는 Docstring도 참고해 함수 등 객체의 설명을 표시하죠.

Docstring은 명백한 문자열 객체로 주석과는 다릅니다. 하지만 Python 인터프리터를 -OO 옵션을 사용하면 무시(무효화)됩니다.

-O  : remove assert and __debug__-dependent statements; add .opt-1 before
         .pyc extension; also PYTHONOPTIMIZE=x
-OO : do -O changes and also discard docstrings; add .opt-2 before
         .pyc extension

-O 옵션을 사용하면 assert문이 무시되는 것처럼 -OO 사용하면 Docstring이 무시되어 None이 되지요. 만약 Docstring을 비즈니스 로직에 사용한다면 유의해야 해요.

Doctest

개요

Python의

Doctest

기능은 doctest 모듈에서 제공하는데, Docstring에 포함된 예제들이 실제 코드와 일치하는지 검증할 수 있도록 테스팅하는 데 활용해요. Python 대화식 인터프리터(

REPL

)에서 Python 코드 실행을 전개하듯이 코드로 작성하지요.

def add(a, b):
    """
    두 숫자 a와 b를 더하는 함수.

    매개변수:
        a (int or float): 첫 번째 숫자.
        b (int or float): 두 번째 숫자.

    반환값:
        int or float: 두 숫자의 합.

    예시:
        >>> add(2, 3)
        5
        >>> add(2.5, 3.0)
        5.5
    """
    return a + b

Docstring에 Python REPL 프롬프트 기호를 사용하여 add() 함수 동작 예시를 작성하면, 사람이 읽을 때 add() 함수를 어떻게 사용하는지 파악하기 좋습니다. 이렇게 작성한 Doctest는 doctest 모듈의 testmod() 함수를 호출해 작동합니다.

def add(a, b):
    ...

if __name__ == "__main__":
    import doctest
    doctest.testmod()

기본 활용

Doctest라는 이름대로 테스팅에서 활용하는데요. 저는 주로 유틸리티 성격이 있는 함수에 Doctest로 테스트를 작성해요.

def merge_querystring(url: str, extra: dict) -> str:
    """URL QueryString에 dict 객체 값을 반영해 업데이트한다.

    >>> merge_querystring("https://puddingcamp.com?lorem=ipsum", {"foo": "bar"})
    https://puddingcamp.com?lorem=ipsum&foo=bar
    """
    url = urllib.parse.urlparse(url)
    query = dict(urllib.parse.parse_qsl(url.query))
    query.update(extra)

    url_parts = tuple(url)
    url_parts[4] = urllib.parse.urlencode(query, encoding="utf-8")
    return urllib.parse.urlunparse(url_parts)

유틸리티성 함수는 대체로 짧고 간단하지만, 사용하는(의존하는) 곳이 많아서 구현이 변경되면 영향을 크게 미치죠. 유틸리티성 함수를 사용한 사람은 Docstring이나 Doctest를 믿고(신뢰하고) 사용하므로 함수 구현을 수정한다면 가능한 한 Docstring과 Doctest를 유지하면서 테스팅을 통과하도록 하여 문서화된 내용과 실 구현이 일치함을 보장해야하죠. 그래서 Docstring과 Doctest로 문서화와 구현을 최대한 가까이 배치해요.

교육 활용

저는 Python 교육을 하는 데에도 Docstring과 Doctest를 활용해요.

def search_contacts(term, data):
    """
    매개변수:
        term (str): 검색어
        data (list[dict]): 검색할 데이터를 담은 객체

    반환값:
        dict or None: 일치하는 연락처, 또는 None

    >>> data = [
    ...     {"이름": "한날", "email": "hannal@puddingcamp.com"},
    ... ]
    >>> search_contacts("유남", data)
    []
    >>> search_contacts("한날", data)
    [{'이름': '한날', 'email': 'hannal@puddingcamp.com'}]
    """

이와 같이 함수의 인터페이스를, 그리고 어떻게 사용하고 동작하는지 예시를 Doctest로 명기하여 제공하고, 학습자분이 이를 참고하여 실제 구현을 하는 거죠. 구현한 코드는 Doctest로 검증하고요. Python 입문자에겐 타입 각주(type annotation)를 사용하는 것보다는 Docstring이 더 쉽고, 테스팅하며 동작 피드백을 빠르게 받을 수 있어 좋아요.

동작 맥락(Context)

Doctest에 작성된 코드는 해당 Doctest가 위치한 모듈의 맥락을 따라요.

from datetime import datetime

def this_year():
    """
    >>> now = datetime.now()
    >>> assert now.year == 2024
    True
    """

이렇게 Doctest를 작성하면 Doctest 대상인 this_year() 함수가 평가(evaluate)되는 모듈의 맥락을 따르므로 datetime.now() 를 사용할 수 있는 거죠.

하지만 저는 구현체가 의존하는 대상을 바로 알아볼 수 있게 Doctest에 import문도 넣는 편이예요.

def this_year():
    """
	>>> from datetime import datetime
    >>> now = datetime.now()
    >>> assert now.year == 2024
    True
    """

pytest 지원

pytest는 기본적으로 Doctest를 지원해요. 별다른 옵션없이 실행해도 Doctest를 처리하지만, 만약 pytest가 테스팅 대상으로 수집(collect)할 조건을 사용하고 있다면 --doctest-modules이나 --doctest-glob 옵션을 사용해 수행할 수 있어요. --doctest-modules는 파일 확장자가 .py인 모든 파일에 대해서 Doctest를 실행하고, --doctest-glob=<패턴>은 glob 패턴 매칭으로 Doctest 대상 파일을 지정하죠.

pytest로 Doctest를 할 때 좋은 점 중 또 하나는 doctest.testmod()를 넣지 않아도 된다는 점이예요.

푸딩캠프 뉴스레터를 구독하면 학습과 성장, 기술에 관해 요약된 컨텐츠를 매주 편하게 받아보실 수 있습니다.