[Appium 자동화 #1] Python + Appium 모바일 테스트 환경 구축하기

Android 앱 UI 자동화 테스트를 위한 Appium + Python 환경을 처음부터 구축하는 방법을 정리했습니다. (Windows / Mac 모두 지원)

---

시리즈 목차

1. 환경 구축 가이드 ← 현재 글
2. Appium Inspector로 요소 찾기
3. 첫 번째 테스트 코드 작성하기
4. pytest fixture 활용하기
5. 여러 디바이스에서 병렬 테스트 실행하기
6. 실무에서 바로 쓰는 테스트 자동화 개선 팁

---

개요

이 글의 대상

• 모바일 앱 자동화 테스트를 처음 시작하는 QA 엔지니어
• Appium 환경 구축이 처음인 개발자
• Python 기반 테스트 프레임워크를 구축하려는 분

구축할 환경

구성 요소	역할
Python	테스트 스크립트 작성 언어
Appium	모바일 앱 자동화 서버 (WebDriver 프로토콜 지원)
UiAutomator2	Android 디바이스 제어 드라이버
ADB	Android 디바이스와 PC 간 통신
pytest	Python 테스트 프레임워크

전체 구조

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Python Test    │────▶│  Appium Server  │────▶│ Android Device  │
│  (pytest)       │     │  (Node.js)      │     │ (UiAutomator2)  │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                                               │
        └───────────────── ADB ─────────────────────────┘

---

1. 필수 소프트웨어 설치

1.1 Python 설치

테스트 스크립트를 작성하고 실행하는 데 사용합니다.

• 권장 버전: Python 3.10 이상
• 다운로드: https://www.python.org/downloads/

설치 시 주의사항

"Add Python to PATH" 반드시 체크!

설치 후 확인:

python --version
# 출력 예: Python 3.10.x

---

1.2 Node.js 설치

Appium은 Node.js 기반으로 동작합니다.

• 권장 버전: Node.js 18 이상 (LTS 권장)
• 다운로드: https://nodejs.org/

설치 후 확인:

node --version
# 출력 예: v18.x.x

npm --version
# 출력 예: 9.x.x

---

1.3 Java JDK 설치

Android 빌드 도구와 UiAutomator2가 Java를 필요로 합니다.

• 권장 버전: JDK 11 이상
• 다운로드: https://adoptium.net/ (무료, 오픈소스)

환경변수 설정

Windows:
1. 시스템 환경변수에 JAVA_HOME 추가:

JAVA_HOME = C:\Program Files\Eclipse Adoptium\jdk-11.x.x

2. Path에 추가:

%JAVA_HOME%\bin

Mac:
1. ~/.zshrc (또는 ~/.bash_profile)에 추가:

export JAVA_HOME=$(/usr/libexec/java_home)
export PATH=$JAVA_HOME/bin:$PATH

2. 설정 적용:

source ~/.zshrc

설치 후 확인:

java -version
# 출력 예: openjdk version "11.x.x"

---

1.4 Android SDK / ADB 설치

ADB(Android Debug Bridge)는 PC와 Android 디바이스 간 통신을 담당합니다.

방법 1: Android Studio 설치 (권장)

1. https://developer.android.com/studio 에서 다운로드
2. 설치 후 SDK Manager에서 필요한 SDK 설치

방법 2: Command-line tools만 설치 (경량)

1. https://developer.android.com/studio#command-tools 에서 다운로드
2. 압축 해제 후 sdkmanager로 필요한 도구 설치

환경변수 설정

Windows:
1. 시스템 환경변수에 ANDROID_HOME 추가:

ANDROID_HOME = C:\Users\{사용자명}\AppData\Local\Android\Sdk

2. Path에 추가:

%ANDROID_HOME%\platform-tools
%ANDROID_HOME%\tools

Mac:
1. ~/.zshrc (또는 ~/.bash_profile)에 추가:

export ANDROID_HOME=~/Library/Android/sdk
export PATH=$ANDROID_HOME/platform-tools:$ANDROID_HOME/tools:$PATH

2. 설정 적용:

source ~/.zshrc

설치 후 확인:

adb version
# 출력 예: Android Debug Bridge version 1.0.xx

---

1.5 Appium 설치

Appium은 모바일 앱 자동화를 위한 오픈소스 서버입니다.

# Appium 전역 설치
npm install -g appium

# UiAutomator2 드라이버 설치 (Android용)
appium driver install uiautomator2

설치 후 확인:

appium --version
# 출력 예: 2.x.x

appium driver list --installed
# 출력 예: uiautomator2

---

2. 프로젝트 설정

2.1 프로젝트 디렉토리 생성

mkdir my-appium-project
cd my-appium-project

2.2 Python 가상환경 생성

가상환경을 사용하면 프로젝트별로 패키지를 독립적으로 관리할 수 있습니다.

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

# 가상환경 활성화 (Windows)
.venv\Scripts\activate

# 가상환경 활성화 (Mac/Linux)
source .venv/bin/activate

2.3 필수 패키지 설치

requirements.txt 파일 생성:

Appium-Python-Client==2.10.0
pytest
pytest-html

패키지 설치:

pip install -r requirements.txt

---

3. 디바이스 연결 설정

3.1 Android 디바이스 준비

1. 개발자 옵션 활성화

   • 설정 > 휴대전화 정보 > 소프트웨어 정보
   • "빌드 번호"를 7번 연속 탭

2. USB 디버깅 활성화

   • 설정 > 개발자 옵션 > USB 디버깅 ON

3. USB 연결 후 권한 허용

   • PC와 연결 시 "USB 디버깅을 허용하시겠습니까?" 팝업에서 허용

3.2 디바이스 연결 확인

adb devices

정상 출력 예시:

List of devices attached
R5CR21BQGFY    device

"unauthorized" 상태인 경우: 디바이스에서 USB 디버깅 권한을 허용해야 합니다.

3.3 디바이스 정보 확인

# 디바이스 모델명 확인
adb shell getprop ro.product.model

# Android 버전 확인
adb shell getprop ro.build.version.release

# 설치된 앱 패키지 목록 확인
# Windows
adb shell pm list packages | findstr {앱이름}

# Mac / Linux
adb shell pm list packages | grep {앱이름}

---

4. 설치 확인 체크리스트

모든 설치가 완료되면 아래 명령어로 확인합니다:

명령어	예상 결과
python --version	Python 3.10+
node --version	v18+
java -version	11+
adb version	설치 확인
appium --version	2.x.x
adb devices	연결된 디바이스 표시

---

5. 자주 발생하는 문제

문제	원인	해결 방법
adb devices 결과 없음	USB 드라이버 미설치	디바이스 제조사 USB 드라이버 설치
"unauthorized" 상태	USB 디버깅 미허용	디바이스에서 팝업 허용
Appium 서버 시작 실패	포트 충돌	다른 포트 사용 (--port 4724)
한글 깨짐 (Windows)	인코딩 문제	터미널에서 chcp 65001 실행

Mac 전용 문제

문제	원인	해결 방법
adb 명령어 미인식	PATH 미설정	~/.zshrc에 PATH 추가 후 source ~/.zshrc
java 명령어 미인식	JDK 미설치 또는 PATH 미설정	Adoptium JDK 설치 후 JAVA_HOME 설정
디바이스 인식 안됨	ADB 서버 문제	adb kill-server && adb start-server

---

환경변수 설정 요약

Windows

변수명	값
JAVA_HOME	C:\Program Files\Eclipse Adoptium\jdk-11.x.x
ANDROID_HOME	C:\Users\{사용자명}\AppData\Local\Android\Sdk

Path에 추가:

%JAVA_HOME%\bin
%ANDROID_HOME%\platform-tools
%ANDROID_HOME%\tools

Mac

~/.zshrc에 추가:

export JAVA_HOME=$(/usr/libexec/java_home)
export ANDROID_HOME=~/Library/Android/sdk
export PATH=$JAVA_HOME/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/tools:$PATH

설정 적용:

source ~/.zshrc

---

마치며

이번 글에서는 Appium + Python 자동화 테스트를 위한 기본 환경을 구축했습니다.

다음 글에서는 Appium Inspector를 사용해서 앱의 UI 요소를 찾는 방법을 알아보겠습니다.

---

참고 자료

• Appium 공식 문서
• Appium Python Client GitHub
• UiAutomator2 Driver