Python API 테스트 환경 구축 가이드｜pytest・requests를 pip install해서 동작 확인까지

Python으로 API 테스트를 시작하려고 할 때 「pytest나 requests는 무엇을 설치하면 되나요?」「가상 환경은 필요한가요?」라고 고민하는 분들이 많습니다. 처음 막히기 쉬운 것이 환경 구축입니다.

이 글에서는 Python으로 API 테스트에 필요한 라이브러리 설치부터 동작 확인까지를 꼼꼼하게 해설합니다. 커맨드를 그대로 복사 붙여넣기만 하면 환경이 갖춰집니다.

00. Python API 테스트 환경 구축에 필요한 라이브러리 일람

API 테스트에 사용하는 라이브러리는 크게 3종류입니다.

💡 포인트：requests와 Playwright는 둘 중 하나만으로 OK입니다. 간단하게 API 테스트만 한다면 requests, UI 테스트와 조합한다면 Playwright 를 선택하세요.

01. 가상 환경 생성（권장）

가상 환경을 사용하면 프로젝트별로 라이브러리를 분리할 수 있습니다. 다른 프로젝트에 영향을 주지 않기 위해 먼저 설정해두는 것을 강력히 권장합니다.

가상 환경 생성 및 활성화

# 가상 환경 생성
python -m venv venv

# 활성화（Windows）
venv\Scripts\activate

# 활성화（Mac/Linux）
source venv/bin/activate

활성화하면 터미널 앞에 (venv) 가 표시됩니다.

(venv) PS C:\Users\HP\Desktop\upwork>

💡 포인트：가상 환경을 활성화한 상태에서 설치하면 그 프로젝트에만 라이브러리가 설치됩니다. 프로젝트를 종료할 때는 deactivate 로 비활성화할 수 있습니다.

02. pip install로 Python API 테스트 라이브러리 설치

① requests 기반의 경우（심플 구성）

pip install requests pytest pytest-html

② Playwright 기반의 경우（UI+API 모두 대응）

pip install playwright pytest pytest-playwright pytest-html
playwright install chromium

⚠️ 주의：playwright install chromium 은 브라우저 다운로드가 필요하기 때문에 최초에는 몇 분이 걸립니다. API 테스트만이라면 생략할 수 있지만, 나중에 UI 테스트와 조합할 경우를 위해 미리 설치해두면 편리합니다.

03. 설치 확인

버전 확인 커맨드

# pytest 버전 확인
pytest --version

# requests 버전 확인
python -c "import requests; print(requests.__version__)"

# playwright 버전 확인
playwright --version

정상적으로 설치된 경우의 표시

pytest 9.0.2
2.32.3
Version 1.50.0

💡 포인트：버전 번호가 표시되면 설치 성공입니다. 오류가 나온 경우는 다음 섹션의 자주 겪는 문제를 참고해주세요.

04. HTML 리포트 자동 생성을 위한 pytest.ini 설정

프로젝트 루트에 pytest.ini 를 작성해두면 테스트 실행 때마다 HTML 리포트가 자동 생성되어 편리합니다.

폴더 구성

project/
├── pytest.ini        ← 여기에 작성
├── test_api.py
└── report.html       ← 실행 후 자동 생성됨

pytest.ini 내용

# pytest.ini
[pytest]
addopts = --html=report.html --self-contained-html

설정 후 실행 방법

# 이 커맨드만으로 HTML 리포트가 자동 생성된다
pytest test_api.py -v

💡 포인트：--self-contained-html 을 붙이면 CSS나 이미지가 HTML에 내장되어 파일 하나로 완결됩니다. GitHub나 클라이언트와의 공유가 쉬워집니다.

05. 동작 확인 테스트

환경 구축이 완료되면 아래 코드로 동작 확인을 해봅시다.

# test_check.py
import requests

def test_environment_check():
    """환경 구축 동작 확인 테스트"""
    response = requests.get("https://jsonplaceholder.typicode.com/users/1")

    assert response.status_code == 200
    assert response.json()["id"] == 1
    print("\n✅ 환경 구축 성공！API 테스트가 동작하고 있습니다")

# 실행 커맨드
pytest test_check.py -v -s

성공 시 출력

test_check.py::test_environment_check
✅ 환경 구축 성공！API 테스트가 동작하고 있습니다
PASSED

1 passed in 1.23s ✅

💡 포인트：-s 옵션을 붙이면 print() 의 출력이 터미널에 표시됩니다. 동작 확인 시에 편리합니다.

06. 자주 겪는 문제 & 해결법

구현 중 실제로 겪었던 문제들을 정리했습니다. 같은 곳에서 막히는 분들께 도움이 되면 좋겠습니다.

① pip install 후에 import 오류가 발생한다

설치했을 텐데 ModuleNotFoundError 가 나오는 경우가 있습니다. 원인은 여러 Python이 설치되어 있고 pip와 python이 서로 다른 것을 가리키고 있는 경우입니다.

# ❌ pip와 python이 다른 버전을 가리키는 경우
pip install requests   # Python3.11에 설치
python test.py         # Python3.9로 실행 → ModuleNotFoundError

# ✅ python -m pip를 사용하면 같은 Python에 확실히 설치됨
python -m pip install requests

💡 포인트：pip 대신 python -m pip 를 사용하면 실행 중인 Python과 같은 환경에 설치되어 확실합니다.

② 가상 환경 활성화를 잊어버린다

가상 환경을 만들었는데 활성화를 잊고 글로벌 환경에 설치해버리는 경우가 자주 있습니다. 터미널 앞을 확인하는 습관을 들이세요.

# ❌ 가상 환경이 활성화되지 않은 상태
PS C:\upwork> pip install requests  # 글로벌에 설치되어버림

# ✅ (venv)가 앞에 붙어 있으면 OK
(venv) PS C:\upwork> pip install requests

⚠️ 주의：VSCode를 사용하는 경우 터미널을 새로 열 때마다 가상 환경이 비활성화되는 경우가 있습니다. .vscode/settings.json 에 설정을 추가하면 자동 활성화할 수 있습니다.

③ playwright install을 잊어서 브라우저 오류가 발생한다

pip install playwright 만으로는 브라우저가 설치되지 않아 실행 시 오류가 발생합니다.

# ❌ 브라우저가 없는 상태로 실행하면 오류
# playwright._impl._errors.Error: Executable doesn't exist

# ✅ 브라우저도 별도 설치가 필요
pip install playwright
playwright install chromium  ← 이것도 필요!

💡 포인트：API 테스트만이라면 playwright install 은 불필요합니다. UI 테스트가 필요해진 타이밍에 실행하면 됩니다.

④ pytest-html 없이 –html 옵션을 사용한다

pytest.ini 에 --html=report.html 을 작성해도 pytest-html 이 설치되어 있지 않으면 오류가 발생합니다.

# ❌ pytest-html 없이 실행하면 오류
# ERROR: unrecognized arguments: --html=report.html

# ✅ pytest-html을 설치하고 나서 실행
pip install pytest-html
pytest test_api.py -v

💡 포인트：한꺼번에 설치해두면 잊어버리지 않습니다. pip install requests pytest pytest-html 을 한 번에 실행하세요.

⑤ requirements.txt로 환경을 공유한다

팀으로 개발하는 경우나 다른 PC에서 같은 환경을 재현하고 싶은 경우는 requirements.txt 를 사용합시다.

# 현재 환경을 requirements.txt에 내보내기
pip freeze > requirements.txt

# requirements.txt에서 일괄 설치
pip install -r requirements.txt

💡 포인트：GitHub에 코드를 업로드할 때 requirements.txt 도 함께 커밋해두면 다른 사람이 바로 같은 환경을 재현할 수 있습니다. 포트폴리오로서의 완성도도 높아집니다.

07. 자주 묻는 질문（FAQ）

Q. Python 버전은 무엇을 사용하면 좋나요？
A. Python 3.9 이상에서 동작합니다. 가능하면 Python 3.11 이상을 사용하는 것을 권장합니다. 또한 pytest 9는 Python 3.9 이상을 권장합니다. python --version 으로 현재 버전을 확인할 수 있습니다.

Q. 가상 환경은 반드시 사용해야 하나요？
A. 필수는 아니지만 강력히 권장합니다. 가상 환경을 사용하지 않으면 라이브러리 버전 충돌이 발생하기 쉽고 나중에 환경이 망가지는 원인이 됩니다. 처음부터 사용하는 습관을 들여두면 안심입니다.

Q. requests와 Playwright 어느 것을 사용하면 좋나요？
A. API 테스트만이라면 requests, UI 테스트와 API 테스트를 둘 다 한다면 Playwright 가 추천입니다. UI와 API 모두 커버하는 포트폴리오를 만든다면 Playwright로 통일하면 코드베이스가 심플해집니다.

Q. pip install이 느린데요？
A. 네트워크 환경에 따라 시간이 걸리는 경우가 있습니다. pip install --upgrade pip 로 pip 자체를 최신으로 하면 개선되는 경우가 있습니다. 또 pip install -i https://pypi.org/simple/ requests 처럼 명시적으로 리포지토리를 지정하는 방법도 있습니다.

Q. requirements.txt와 pyproject.toml 어느 것을 사용하면 좋나요？
A. 개인 프로젝트나 학습용이라면 requirements.txt 가 심플해서 충분합니다. 팀 개발이나 본격적인 패키지 관리가 필요해지면 pyproject.toml（Poetry 등）를 검토해보세요. 포트폴리오용으로는 requirements.txt 로 충분합니다.

08. 정리

Python으로 API 테스트를 시작하는 경우, 먼저 환경 구축을 올바르게 하는 것이 중요합니다. pytest와 requests를 설치하고 가상 환경을 설정하면 바로 API 테스트를 작성하기 시작할 수 있습니다.

이 글에서는 Python API 테스트에 필요한 환경 구축 절차를 해설했습니다.

환경 구축은 한 번 해두면 이후는 쾌적합니다. 가상 환경 생성・라이브러리 설치・pytest.ini 설정의 3단계를 익혀두면 바로 API 테스트를 작성하기 시작할 수 있습니다💪