안드로이드 ADB 입력 자동화 가이드: keyevent 및 터치 스크립트 작성법

안드로이드 애플리케이션 개발 과정에서 UI 테스트를 진행하다 보면 반복적으로 버튼을 누르거나 화면을 넘겨야 하는 번거로운 작업이 발생합니다. 특히 대량의 단말기에 동시에 특정 앱을 실행하거나, 특정 UI 플로우를 지속적으로 검증해야 하는 환경이라면 수동 입력은 물리적인 한계가 명확합니다. 안드로이드 프레임워크는 이러한 문제를 해결하기 위해 ADB(Android Debug Bridge)를 통해 운영체제 레벨의 입력 이벤트를 주입할 수 있는 input 서브 명령어를 제공합니다. 물리적인 터치 없이도 시스템 수준의 키 코드나 화면 좌표 데이터를 주입할 수 있어, 셸 스크립트와 결합하면 누구나 간편하게 나만의 UI 자동화 도구를 만들 수 있습니다. 이번 포스팅에서는 물리 버튼 대응 이벤트부터 화면 좌표 기반의 터치 제어, 그리고 복합 자동화 스크립트 작성법까지 실무 중심으로 정리해 보겠습니다.

Generated by Gemini AI.

핵심 요약

• adb shell input keyevent 명령어를 사용하면 홈, 전원, 볼륨 등 안드로이드의 물리 및 가상 버튼 입력을 커맨드 라인에서 직접 시뮬레이션할 수 있습니다.
• adb shell input tap과 swipe를 조합하면 디바이스 화면의 특정 좌표를 정밀하게 터치하거나 스크롤 동작을 코드 기반으로 구현할 수 있습니다.
• 반복적인 작업은 셸 스크립트 내에 순차적으로 명령어들을 나열하고 sleep 지연 시간을 추가하여 안정적인 자동화 테스트 체계를 구축할 수 있습니다.

1. 물리 버튼 제어를 위한 Keyevent 명령어 구성

시스템 하드웨어 버튼 동작을 강제로 수행하는 명령어들입니다.

키 명칭	실행 명령어	설명
홈(Home)	adb shell input keyevent KEYCODE_HOME	어떤 화면에서든 메인 홈 화면으로 즉시 이동
뒤로가기(Back)	adb shell input keyevent KEYCODE_BACK	이전 액티비티로 돌아가거나 앱 상위 계층으로 이동
전원(Power)	adb shell input keyevent KEYCODE_POWER	화면을 켜거나 끄는 전원 버튼 동작 수행
볼륨 업/다운	adb shell input keyevent KEYCODE_VOLUME_UP	미디어 및 시스템 알림 음량 증가 (DOWN으로 감소)
메뉴 버튼	adb shell input keyevent KEYCODE_MENU	앱 내 설정이나 메뉴 레이어를 호출하는 동작

2. 화면 터치 및 스와이프 제어 명령어 구성

디바이스의 해상도에 따른 좌표 기반 터치 자동화 명령어들입니다.

동작 유형	실행 명령어 형식	비고
단일 터치	adb shell input tap <X> <Y>	지정한 좌표(X, Y)를 짧게 터치합니다.
위로 스와이프	adb shell input swipe <X1> <Y1> <X2> <Y2>	(X1, Y1)에서 (X2, Y2)로 이동하여 화면을 올립니다.
아래로 스와이프	adb shell input swipe <X1> <Y1> <X2> <Y2>	아래 방향으로 스크롤하여 이전 내용을 확인합니다.
좌우 스와이프	adb shell input swipe <X1> <Y1> <X2> <Y2>	페이징 화면을 넘기거나 좌우 슬라이드 UI를 조작합니다.

3. 실무 자동화 스크립트 작성 예시

단순 반복 입력을 넘어, 여러 명령어를 조합하여 앱을 실행하고 특정 기능을 수행하는 스크립트 예제입니다.

Bash

 

#!/bin/bash
# 앱 실행 (패키지명: com.example.app)
adb shell monkey -p com.example.app -c android.intent.category.LAUNCHER 1

# 앱 초기 로딩을 위해 3초 대기
sleep 3

# 특정 좌표(500, 1000)를 터치하여 기능 활성화
adb shell input tap 500 1000

# 추가 작업 후 홈으로 복귀
sleep 1
adb shell input keyevent KEYCODE_HOME

개발을 위한 팁

• 좌표값 확인 방법: 정확한 X, Y 좌표를 알아내기 힘들 때는 안드로이드 개발자 옵션의 포인터 위치 기능을 활성화하십시오. 화면 상단에 현재 터치하는 지점의 정확한 좌표가 표시되어 스크립트 작성 시 시행착오를 줄일 수 있습니다.
• 지연 시간 관리: 자동화 스크립트 작성 시 sleep 명령어는 필수입니다. 기기 사양에 따라 앱 구동 속도가 다르므로, 로딩이 완전히 끝나지 않은 상태에서 터치 명령어가 먼저 들어가면 정상적인 동작을 수행하지 못합니다. 충분한 여유 시간을 주거나, 앱 실행 여부를 판단하는 조건을 스크립트에 추가하는 것이 좋습니다.
• 연결 확인: 명령어가 작동하지 않는다면 가장 먼저 adb devices 명령으로 기기 상태가 device로 제대로 인식되고 있는지 확인하십시오. 간혹 연결은 되어 있어도 권한 문제로 인해 입력이 차단되는 경우가 있습니다.

흔히 하는 실수

• 해상도 차이 고려 미흡: 작성한 자동화 스크립트를 다른 해상도의 기기에 동일하게 적용하면 터치 좌표가 완전히 빗나가는 문제가 발생합니다. 기기별로 화면 비율과 해상도가 다르므로, 절대 좌표 대신 기기 해상도 비율을 계산하여 좌표를 대입하는 방식을 취해야 범용적인 자동화 스크립트를 유지할 수 있습니다.
• 잠금 화면 무시: 디바이스가 잠금 상태라면 아무리 터치 명령어를 날려도 앱 내부 UI를 제어할 수 없습니다. 따라서 스크립트 초반에 전원 버튼을 눌러 화면을 켜고, 위로 스와이프하는 잠금 해제 루틴을 반드시 포함해야 합니다.
• Monkey 도구의 오용: adb shell monkey는 원래 앱 스트레스 테스트를 위한 도구이므로, 단순히 앱 실행 용도로만 쓰기에는 예기치 못한 랜덤 입력이 발생할 수 있습니다. 앱 실행을 위해서는 monkey 대신 adb shell am start -n 패키지명/액티비티명 명령을 사용하는 것이 훨씬 정확하고 안정적입니다.

결론

ADB input 명령어 세트는 별도의 복잡한 테스트 프레임워크를 설치하지 않고도 가장 빠르고 가볍게 안드로이드 UI를 제어할 수 있는 도구입니다. 기본적인 키 이벤트와 좌표 기반 터치만 숙지해도 반복적인 QA 작업을 수 분 내로 단축할 수 있습니다. 본 가이드에 정리된 표와 스크립트 예시를 활용하여 매일 수행하는 테스트 업무를 자동화하고 개발 생산성을 높여 보시기 바랍니다.