【Python】Allure 리포트 도입 가이드｜pytest × Playwright의 테스트 결과를 아름답게 가시화하는 방법

pytest로 테스트 자동화를 진행하다 보면, 테스트 결과를 더 보기 좋은 리포트로 공유하고 싶어질 때가 있습니다. Allure 리포트를 도입하면 pytest의 테스트 결과를 그래프·스크린샷·스텝 상세가 포함된 풍부한 HTML 리포트로 출력할 수 있습니다. 이 글에서는 Python × pytest 환경에 Allure를 도입하는 방법부터 스크린샷 첨부 리포트 작성, GitHub Actions 연계까지 실무 수준으로 해설합니다.

Allure 리포트를 도입하면 pytest의 테스트 결과를 그래프·스크린샷·스텝 상세가 포함된 아름다운 HTML 리포트로 출력할 수 있어 QA 리포트의 질이 한 단계 올라갑니다.

pytest-html로도 기본적인 리포트는 만들 수 있지만 테스트가 늘어나면 다음과 같은 불만이 생깁니다.

• 어떤 테스트가 실패했는지 목록으로 파악하기 어렵다
• 실패 원인을 스크린샷과 함께 확인할 수 없다
• 테스트 실행 이력·트렌드가 보이지 않는다

Allure는 이런 과제를 해결하는, 테스트 자동화 현장에서 가장 널리 사용되는 리포트 프레임워크입니다. 이 글에서는 설치부터 실제 리포트 생성·CI/CD 연계까지 한 번에 해설합니다.

① pytest-html과 Allure 중 어느 것을 사용해야 할까요？차이점과 선택 방법

먼저 Allure와 pytest-html의 차이를 정리합니다.

② Python × pytest에 Allure를 설치하는 방법

Allure는 「Python 패키지인 Allure 어댑터」와 「리포트를 생성하는 Allure CLI」 2가지를 설치해야 합니다.

Python 패키지 설치

먼저 pytest와 연계하기 위한 Allure 어댑터를 설치합니다.

# allure-pytest 설치
pip install allure-pytest

# requirements.txt에 추가하는 경우
# allure-pytest

Allure CLI 설치

다음으로 HTML 리포트를 생성하는 Allure CLI를 설치합니다. Allure CLI는 Java가 필요합니다. OS별 설치 방법을 확인합니다.

# macOS（Homebrew 사용）
brew install allure

# Windows（Scoop 사용）
scoop install allure

# Linux（수동 설치）
# 1. Allure 공식 사이트에서 zip 다운로드
# 2. 압축 해제 후 bin/에 PATH 추가

# 설치 확인
allure --version

③ pytest로 Allure 리포트를 생성하는 기본적인 사용법

Allure는 테스트 실행 시 먼저 「결과 파일」을 생성하고 그 후 CLI로 HTML 리포트로 변환하는 2단계 흐름입니다.

STEP 1：테스트 실행（결과 파일 생성）

--alluredir 옵션을 붙여 pytest를 실행하면 지정 폴더에 Allure용 결과 파일이 출력됩니다.

# allure-results 폴더에 결과 파일 출력
pytest --alluredir=allure-results

# 스모크 테스트만 실행하여 결과 출력
pytest -m smoke --alluredir=allure-results

# 기존 결과 파일을 초기화하고 실행
pytest --alluredir=allure-results --clean-alluredir

STEP 2：HTML 리포트 생성·표시

결과 파일이 생성되면 Allure CLI로 HTML 리포트로 변환합니다. 로컬 확인용과 CI/CD 저장용 2가지 방법이 있습니다.

# 브라우저에서 자동 기동하여 리포트 표시（로컬 서버 기동）
allure serve allure-results

# HTML 파일로 출력（CI/CD 아티팩트 저장용）
allure generate allure-results -o allure-report --clean

실행 결과 샘플

$ pytest --alluredir=allure-results -v

========================= test session starts ==========================
collected 3 items

tests/smoke/test_login_smoke.py::test_로그인_정상          PASSED  [ 33%]
tests/smoke/test_login_smoke.py::test_로그인_비밀번호_오류   PASSED  [ 66%]
tests/smoke/test_login_smoke.py::test_로그인_잠긴_사용자    PASSED  [100%]

========================== 3 passed in 5.34s ===========================

$ allure serve allure-results
Starting web server...
Server started at: http://127.0.0.1:PORT/

④ pytest 테스트에 Allure 정보（step・severity）를 추가하는 방법

Allure의 진가는 테스트 코드에 데코레이터를 추가하여 리포트에 상세 정보를 부가할 수 있다는 점입니다.

기본 데코레이터

다음 데코레이터를 조합하면 리포트 상에서 테스트를 기능·중요도·스토리로 분류할 수 있습니다.

import allure
import pytest
from pages.login_page import LoginPage

@allure.epic("인증 기능")              # 대분류（프로덕트 기능）
@allure.feature("로그인")             # 중분류（기능명）
@allure.story("정상 로그인")          # 소분류（사용자 스토리）
@allure.severity(allure.severity_level.CRITICAL)  # 중요도
@pytest.mark.smoke
def test_로그인_정상(page, base_url, valid_credentials):
    """정상 로그인 정보로 로그인이 성공하는 것을 확인"""

    with allure.step("로그인 페이지로 이동"):
        login_page = LoginPage(page)
        login_page.navigate(f"https://{base_url}/")

    with allure.step("로그인 정보를 입력하여 제출"):
        login_page.login(
            valid_credentials["username"],
            valid_credentials["password"]
        )

    with allure.step("로그인 후 URL 확인"):
        assert page.url.endswith("/inventory.html"), \
            f"로그인 후 URL이 기대값과 다릅니다: {page.url}"

severity（중요도）의 종류

⑤ Playwright × Allure로 스크린샷을 자동 첨부하는 방법

Playwright × Allure 조합에서 가장 강력한 것이 실패 시 스크린샷 자동 첨부입니다. conftest.py에 작성해 두면 모든 테스트에 자동 적용됩니다.

다음 코드를 tests/conftest.py에 추가합니다. 테스트가 실패한 타이밍에 자동으로 스크린샷을 캡처하여 Allure 리포트에 첨부합니다.

# tests/conftest.py에 추가

import allure
import pytest

@pytest.hookimpl(tryfirst=True, hookwrapper=True)
def pytest_runtest_makereport(item, call):
    """테스트 실패 시 스크린샷을 Allure 리포트에 첨부한다"""
    outcome = yield
    report = outcome.get_result()

    # 테스트가 실패했을 때
    if report.when == "call" and report.failed:
        # 테스트에 page fixture가 사용되고 있는 경우만
        page = item.funcargs.get("page")
        if page:
            screenshot = page.screenshot()
            allure.attach(
                screenshot,
                name="실패 시 스크린샷",
                attachment_type=allure.attachment_type.PNG
            )

임의의 타이밍에 수동으로 스크린샷을 첨부하고 싶은 경우는 다음과 같이 작성합니다：

import allure

def test_카트_추가(logged_in_page):
    page = logged_in_page

    with allure.step("상품을 카트에 추가"):
        page.click("[data-test='add-to-cart-sauce-labs-backpack']")

        # 임의의 타이밍에 스크린샷 첨부
        allure.attach(
            page.screenshot(),
            name="카트 추가 후 화면",
            attachment_type=allure.attachment_type.PNG
        )

    with allure.step("카트 배지 수 확인"):
        badge = page.locator(".shopping_cart_badge").text_content()
        assert badge == "1"

⑥ Allure용 pytest.ini 설정

pytest.ini에 Allure용 설정을 추가합니다. 이렇게 하면 매번 --alluredir 옵션을 수동으로 입력하지 않아도 됩니다.

# pytest.ini
[pytest]
testpaths = tests

addopts =
    -v
    --tb=short
    --alluredir=allure-results
    --clean-alluredir

markers =
    smoke: 스모크 테스트
    regression: 회귀 테스트
    e2e: E2E 테스트

⑦ GitHub Actions에서 Allure 리포트를 자동 생성하는 방법

GitHub Actions에서 Allure 리포트를 자동 생성하여 아티팩트로 저장하는 설정입니다. 다음 YAML 파일을 그대로 복사하여 사용할 수 있습니다.

# .github/workflows/allure.yml

name: E2E Tests with Allure Report

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Python 3.11 설정
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: 의존 패키지 설치
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Playwright 브라우저 설치
        run: playwright install chromium --with-deps

      - name: 테스트 실행（Allure 결과 파일 출력）
        run: pytest --alluredir=allure-results
        continue-on-error: true   # 테스트 실패해도 리포트 생성을 계속

      - name: Allure CLI 설정
        uses: simple-elf/allure-setup-action@master
        with:
          allure_version: "2.27.0"

      - name: Allure HTML 리포트 생성
        run: allure generate allure-results -o allure-report --clean

      - name: 리포트를 아티팩트로 저장
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: allure-report
          path: allure-report/
          retention-days: 30

FAQ

⚠️ Allure 리포트 도입에서 자주 발생하는 함정 7선

Allure는 설정이 많은 만큼 빠지기 쉬운 포인트도 많습니다. 미리 파악해 두면 불필요한 디버깅 시간을 줄일 수 있습니다.

📋 이 글의 정리

먼저 pip install allure-pytest와 Allure CLI를 설치하고 pytest --alluredir=allure-results → allure serve allure-results의 2개 커맨드만으로 리포트를 확인해 보세요. 거기서부터 스텝 추가·스크린샷 첨부를 단계적으로 충실히 해나가는 것을 추천합니다.