Appium(Windows)

1. Appium 개요

1.1. Appium란?

• 모바일 자동화 테스트 프레임워크
• Android / iOS 앱 자동화 테스트 지원
• Native 앱, Hybrid 앱, Mobile Web 모두 테스트 가능
• 테스트 코드는 Java, Python, JavaScript, C#, Ruby 등 여러 언어로 작성 가능

 

1.2. 사용하는 이유

Appium은 테스트 스크립트를 이용하여 앱을 자동으로 실행하고, 사람의 직접적인 조작 없이 버튼 클릭, 화면 이동 여부 확인 등의 사용자 동작을 수행할 수 있다.

따라서 반복적으로 수행해야 하는 로그인 테스트나 기능 테스트를 빠르고 일관되게 진행할 수 있으며, 여러 기기를 동시에 테스트할 수 있는 이점이 있다. 또한 테스트 결과의 정확성과 재현성을 높여 QA 업무를 효율적으로 수행할 수 있다는 점에서 편리하다.

 

1.3. 작동 방식

테스트 코드 → Appium Server → 모바일 기기

• 작성한 테스트 스크립트가 Appium Server에 요청을 보냄
• Appium Server가 기기에게 ‘이 버튼 클릭해’, ‘텍스트 입력해’ 등을 지시
• 기기가 응답을 Appium에게 주고, Appium은 테스트 코드를 실행한 쪽에 결과 전달

 

1.4. 설치 목록

• Node.js
• Java JDK
• Android Studio
• Appium Server
• uiautomator2
• Appium Doctor(선택)
• Appium Inspector
• Appium Python Client(실습)

---

 

2. Node.js 설치

2.1. Node.js란

Node.js는 JavaScript를 브라우저 밖에서도 실행할 수 있게 해주는 실행 환경(플랫폼)이다.

원래 JavaScript는 주로 브라우저에서 실행되지만, Node.js를 사용하면 PC 환경에서도 JavaScript를 실행할 수 있다.

 

2.2. Appium 사용에 필요한 이유

Appium은 JavaScript(Node.js)로 만들어진 프로그램이다.

Appium 서버는 Node.js 기반으로 동작하기 때문에 Node.js가 설치되어 있어야 실행할 수 있다.

 

2.3. 설치 방법

◎ 공식 사이트에서 설치파일 다운로드  https://nodejs.org/ko/download

Node.js — Node.js® 다운로드

 

◎ 다운 받은 파일 실행하여 설치

 

◎ 설치 확인

node -v
npm -v

---

 

3. Java JDK 설치

3.1. Java JDK란

 자바 개발 키트(Java Development Kit)로, Java 실행 환경(JRE)과 컴파일러(javac)를 함께 포함하고 있다.

 

3.2. Appium 사용에 필요한 이유

Android 자동화 테스트를 수행하려면 Android 개발 환경이 필요한데 Android 개발 생태계는 모두 Java 기반이다.

ADB 실행, Android automation engine 실행, Appium Android driver 빌드 모든 부분에 Java가 필요하다.

 

3.3. 설치 방법

◎ JDK 다운로드 https://www.oracle.com/java/technologies/downloads/#java17

Download the Latest Java LTS Free

 

◎ 설치 파일 실행하여 JDK 설치 후 버전 확인

java --version

 

◎ JDK 경로 환경 변수 등록 (JAVA_HOME=C:\Program Files\Java\jdk-17)

---

 

4. Android Studio 설치

4.1. Android Studio란

Android Studio는 Android 앱 개발에 필요한 도구들을 한 번에 제공하는 개발 환경이다.

이 안에는 Android 기기를 제어하기 위한 Android SDK도 함께 포함되어 있다.

 

4.2. Appium 사용에 필요한 이유

엄밀히 말하면 Appium에 꼭 필요한 것은 Android Studio 자체가 아니라 Android SDK이다.

다만 Android Studio를 설치하면 SDK가 함께 설치되기 때문에 주로 이를 통해 환경을 구성한다.

Appium은 Android 자동화 테스트를 위해 ADB를 사용해 실제 기기나 에뮬레이터와 통신하며, SDK Platforms, Platform-Tools, Build-Tools를 통해 앱 설치, 실행, 분석 작업을 수행한다.

 

Appium이 Android 테스트를 하기 위해 필요한 것

• ADB (Android Debug Bridge) 실제/가상 기기와 통신(클릭, 스와이프, 파일 push, install 등)
• Android SDK Platforms 특정 API 레벨(Android 10, 11, 12 등)용 플랫폼 도구
• Platform-Tools 핵심: adb, fastboot 등이 포함됨
• Build-Tools aapt, zipalign, apksigner 등 Appium이 APK 설치/분석 시 사용함
• AVD (Android Emulator) 가상 디바이스(에뮬레이터)를 실행하려면 필요

 

4.3. 설치 방법

◎ Android Studio 설치파일 준비 https://developer.android.com/

Android 모바일 앱 개발자 도구 - Android Developers

 

◎ Android Studio 설치 완료 후 Settings 메뉴 클릭

 

◎ Languages&Frameworks > Android SDK 클릭해서 추가 설치

• SDK Platforms, SDK Build-tools, Android SDK Command-line Tools (latest) 필요

 

◎ SDK 경로 환경 변수 설정 (ANDROID_HOME=C:\Users\[사용자]\AppData\Local\Android\Sdk)

 

◎ PATH에 추가

• %ANDROID_HOME%\platform-tools
• %ANDROID_HOME%\tools
• %ANDROID_HOME%\tools\bin

 

◎ 동작 확인

echo %ANDROID_HOME%
adb --version

• 참고로 환경 변수 등록은 시스템 변수 쪽에 해서 재부팅 전에는 관리자 CMD에서만 적용될 수 있음

 

◎ 혹시 위 환경 변수 등록을 완료하였는데도 차후 실행 시 platform-tools를 못 찾으면 별도로 PATH에 추가

• C:\Users\[사용자]\AppData\Local\Android\Sdk\platform-tools

---

 

5. Appium Server 설치

5.1. 왜 필요한가

Appium은 ‘클라이언트-서버 구조’ 라서 클라이언트만으로는 테스트를 수행할 수 없다.

 

5.2. 설치 방법

◎ Appium Server 설치

npm install -g appium

---

 

6. uiautomator2 설치

6.1. uiautomator2란

uiautomator2는 Appium에서 Android 기기를 자동으로 제어하기 위해 사용하는 기본 자동화 드라이버로, Appium이 실제 안드로이드 기기에서 버튼 클릭이나 화면 이동 같은 동작을 수행할 수 있게 해준다.

 

6.2. 왜 필요한가

uiautomator2가 없으면 Appium 서버 실행이나 테스트 코드 자체는 에러 없이 동작할 수 있다. 하지만 Appium이 실제 기기를 조작할 수 없어, 테스트 코드를 실행해도 기기에서는 아무런 동작이 일어나지 않게 된다. 따라서 Android 자동화 테스트를 제대로 수행하기 위해 uiautomator2는 필수 요소이다.

 

6.3. 설치 방법

◎ uiautomator2 설치

appium driver install uiautomator2

 

◎ uiautomator2 설치 확인

appium driver list --installed

---

 

7. Appium Doctor 설치

7.1. Appium Doctor란

Appium Doctor는 Appium을 문제없이 실행할 수 있는 개발 환경이 제대로 갖춰져 있는지 확인해 주는 진단 도구이다.

Node.js, Android SDK 등 필요한 도구의 설치 여부와 환경 변수 설정 상태를 자동으로 점검해 준다.

 

7.2. 설치 방법

◎ 설치

npm install -g appium-doctor

7.3. Appium Doctor 사용

◎ iOS 관련 항목은 빼고 Android에 필요한 것들만 체크

appium-doctor --android

 

 

8. Appium Inspector 설치

8.1. Appium Inspector란

Appium Inspector는 Appium 자동화 테스트를 할 때 화면에 있는 UI 요소를 확인하고, 테스트에 사용할 locator를 쉽게 찾을 수 있도록 도와주는 도구이다.

 

8.2. Appium Inspector 설치

◎ Appium Inspector 설치 파일 준비 https://github.com/appium/appium-inspector/releases

Releases · appium/appium-inspector

 

◎ 설치 파일 실행 및 설치

---

 

9. Appium 연결

9.1. 스마트폰 기기 연결

◎ Android 기기를 PC에 USB로 연결

 

◎ 기기 설정 > 개발자 옵션 > USB 디버깅 활성화

USB 디버깅을 허용하시겠습니까? → 확인

USB 디버깅을 허용하시겠습니까? 컴퓨터 RSA 키 지문 : 값 → 허용 (항상 허용 체크)

 

◎ 기기 연결 확인

adb devices

 

 

◎ 만약 기기 연결 확인(adb devices)을 했는데 attached 값이 unauthorized 이면 Windows의 ADB vendor key가 꼬인 상태이기 때문에 인증키 초기화 후 재연결 해야 한다.

> 해결 방법 1

• 기기 설정 > 개발자 옵션 > USB 디버깅 활성화 끄기
• 기기 설정 > 개발자 옵션 > USB 디버깅 권한 승인 취소
• 다시 USB 디버깅 활성화
• 발생하는 알림 모두 허용
• (필요시) ADB 재실행

adb kill-server
adb start-server
adb devices

 

> 해결 방법 2

• 기기 설정 > 개발자 옵션 > USB 디버깅 활성화 끄기
• 아래 경로 접근해서 파일 삭제

C:\Users\**[사용자명]**\.android\adbkey
C:\Users\**[사용자명]**\.android\adbkey.pub

• 다시 USB 디버깅 활성화
• 발생하는 알림 모두 허용
• (필요시) ADB 재실행

adb kill-server
adb start-server
adb devices

 

9.2. Appium Server 실행

◎ Appium Server 실행

appium

 

◎ Appium Server 접속 확인

curl http://127.0.0.1:4723/status

• Appium 서버는 HTTP 기반 API로 돌아가기 때문에 서버가 켜져 있으면 그 주소로 접속할 수 있음

 

9.3. Appium Inspector 연결 확인

◎ 세션 생성

{
  "platformName": "Android",
  "appium:automationName": "UiAutomator2",
  "appium:udid": "R3CN20GQEKP",
  "appium:appPackage": "com.android.settings",
  "appium:appActivity": ".Settings"
}

 

◎ 연결 확인 완료

---

10. 실습(파이썬 코드 사용)

10.1. Android Studio 세팅

◎ Android Studio 실행 후 Settings > Tools > Device Mirroring

• ☑ Activate mirroring when a new physical device is connected
  → 기기 연결 시 자동으로 미러링 창 뜸(필수)
• ☑ Synchronize clipboard
  → PC ↔ 폰 복붙 가능 (선택_편의)

 

◎ 빈 프로젝트 생성 (Projects > New Project > Empty Activity)

 

◎ 빈 프로젝트 생성 완료 (Finish)

 

◎ 자동으로 기기 연결되어 미러링

 

 

10.2. 실습 (파이썬 코드 사용)

◎ Appium Python Client 설치

pip install Appium-Python-Client

 

◎  Appium Python Client 정상 설치 확인

pip show Appium-Python-Client

 

◎ 코드 (소리 및 진동 메뉴 클릭)

from appium import webdriver
from appium.options.android import UiAutomator2Options
import time

# Appium 서버 주소
APPIUM_SERVER_URL = "http://127.0.0.1:4723"

# Capabilities 설정
options = UiAutomator2Options()
options.platform_name = "Android"
options.automation_name = "UiAutomator2"
options.udid = "R3CN20EQKP"   # udid
options.app_package = "com.android.settings"
options.app_activity = ".Settings"

# 드라이버 생성 (앱 자동 실행)
driver = webdriver.Remote(APPIUM_SERVER_URL, options=options)

time.sleep(3)

# 예시: '소리 및 진동' 메뉴 클릭
driver.find_element(
    by="xpath",
    value="//*[@text='소리 및 진동']"
).click()

time.sleep(3)

# 테스트 종료
driver.quit()

 

◎ 코드 실행

python test1.py

 

◎ 안드로이드 기기 동작하는 것 확인하면 된다!