ROBOT FRAMEWORK VỚI ANDROID: CÀI APPIUM VÀ KẾT NỐI THIẾT BỊ

Sau 11 bài Robot Framework, chúng ta đã biết file .robot gồm những gì, keyword chạy ra sao, biến nằm ở đâu và lúc test toang thì nên đọc log nào. Bây giờ mới tới đoạn lôi điện thoại ra cắm vào máy.

Phần mobile khó chịu hơn browser automation ở chỗ giữa test case và ứng dụng có khá nhiều thằng đứng chen giữa. Chỉ cần một thằng chưa cài, sai version hoặc trỏ nhầm đường dẫn là Robot Framework sẽ báo lỗi ở đầu bên này, trong khi nguyên nhân thật nằm tận ADB ở đầu bên kia. Bài này sẽ dựng từng lớp một để khi chạy lỗi, bạn còn biết phải túm cổ thằng nào.

Baseline của bài được kiểm tra theo tài liệu và package registry ngày 08/09/2026. Phần cài đặt đã được kiểm tra bằng dry-run và build; smoke flow vẫn cần chạy lại trên thiết bị thật.

Device Manager là nơi tạo, boot và quản lý AVD. Ảnh: Android Developers, sử dụng theo Content License. Giao diện này chỉ minh họa luồng AVD, không phải bằng chứng smoke test của project.

Sáu lớp đang nói chuyện với nhau

Robot Framework đọc test case và điều phối keyword. AppiumLibrary biến các keyword như Click Element thành lệnh của Appium Python Client. Client gửi HTTP request tới Appium Server. Server chuyển lệnh cho UiAutomator2 Driver, còn driver dùng ADB để cài server phụ lên Android và điều khiển giao diện.

Nôm na, Robot Framework không hề tự biết bấm vào màn hình điện thoại. Nó giao việc qua bốn tầng trung gian. Vì vậy pip install robotframework-appiumlibrary thành công mới chỉ có nghĩa là tầng Python đã xong, không có nghĩa là điện thoại đã sẵn sàng.

Bộ version dùng trong bài

Version trong bảng không phải chân lý truyền đời. Nó là một bộ đã được chốt để các đoạn phía sau cùng nói một ngôn ngữ. Nếu bạn tự update riêng Appium nhưng giữ driver cũ từ ba mùa trước, đến lúc lỗi thì đừng vội kết luận Robot Framework ghét mình.

Cài Python dependency trong virtual environment

Tạo thư mục project, virtual environment và kích hoạt nó:

New-Item -ItemType Directory -Path robot-android
Set-Location robot-android
py -3.13 -m venv .venv
.\.venv\Scripts\Activate.ps1

Nếu PowerShell chặn script kích hoạt, chỉ đổi policy cho process terminal hiện tại:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1

Không cần đổi policy toàn máy chỉ để bật một virtual environment. Cầm dao gọt hoa quả thì đừng tiện tay chặt luôn cái bàn.

Tạo requirements.txt:

robotframework==7.4.2
robotframework-appiumlibrary==3.2.1

Sau đó cài và kiểm tra:

python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python --version
robot --version
python -m pip show robotframework-appiumlibrary

Dùng python -m pip giúp chắc chắn pip đang thuộc đúng Python trong .venv. Nếu gõ một pip trôi nổi trên PATH, hoàn toàn có thể bạn cài thư viện vào Python A nhưng VS Code và Robot Framework lại chạy Python B. Ông nói gà, bà import AppiumLibrary.

Cài Node.js, Appium và UiAutomator2

Sau khi cài Node.js 22, kiểm tra:

node --version
npm --version

Cài đúng Appium baseline rồi cài driver Android riêng:

npm install --global appium@3.7.0
appium driver install uiautomator2@8.6.1
appium --version
appium driver list --installed

Appium 3 không tự mang UiAutomator2 theo. npm install --global appium chỉ cài server; appium driver install mới cài thứ biết điều khiển Android. Đây là chỗ người mới hay dừng sớm nhất rồi nhìn dòng Could not find a driver for automationName 'UiAutomator2' bằng ánh mắt tổn thương.

Cài JDK và Android SDK

Cài JDK 17, sau đó mở Android Studio và vào Settings → Languages & Frameworks → Android SDK. Trong SDK Manager, cài:

• Android SDK Platform 35;
• Android SDK Platform-Tools;
• Android SDK Command-line Tools;
• Android Emulator nếu bạn dùng AVD;
• một system image API 35 phù hợp CPU nếu bạn dùng AVD.

Giả sử JDK nằm ở C:\Program Files\Eclipse Adoptium\jdk-17 và Android SDK nằm ở %LOCALAPPDATA%\Android\Sdk, đặt biến môi trường cho user hiện tại:

[Environment]::SetEnvironmentVariable(
    'JAVA_HOME',
    'C:\Program Files\Eclipse Adoptium\jdk-17',
    'User'
)

[Environment]::SetEnvironmentVariable(
    'ANDROID_HOME',
    "$env:LOCALAPPDATA\Android\Sdk",
    'User'
)

Thêm các thư mục cần thiết vào Path bằng giao diện Environment Variables của Windows:

%JAVA_HOME%\bin
%ANDROID_HOME%\platform-tools
%ANDROID_HOME%\emulator
%ANDROID_HOME%\cmdline-tools\latest\bin

Mở terminal mới rồi kiểm tra:

java -version
adb version
where.exe java
where.exe adb

JAVA_HOME trỏ tới thư mục JDK, không trỏ thẳng vào java.exe. ANDROID_HOME cũng trỏ tới thư mục SDK, không trỏ vào platform-tools. PATH mới là chỗ đưa các thư mục chứa executable vào để terminal tìm thấy.

Cuối cùng chạy doctor:

appium driver doctor uiautomator2

Mục tiêu là 0 required fixes needed. Các optional fix có thể đọc sau; required fix mà còn đỏ thì chưa nên viết test.

Cách A: thiết bị Android thật qua USB

Trên điện thoại, mở Settings → About phone, bấm nhiều lần vào Build number cho tới khi Developer Options được bật. Quay lại Developer Options và bật USB debugging.

Trên Windows, một số hãng cần OEM USB driver. Nếu Device Manager chỉ nhìn điện thoại như thiết bị media hoặc hiện dấu chấm than, hãy cài driver từ chính nhà sản xuất. Đừng tải một file universal-super-adb-driver-final-final.exe từ góc tối Internet rồi cầu may.

Cắm cáp có truyền dữ liệu, mở khóa điện thoại và chấp nhận hộp thoại RSA Allow USB debugging. Kiểm tra:

adb devices -l

Kết quả tốt có dạng:

List of devices attached
R58M123456A    device product:... model:... transport_id:1

Phần đầu dòng là serial. Nó sẽ được dùng làm udid:

$env:ANDROID_UDID = 'R58M123456A'
$env:ANDROID_TARGET = 'usb'

Capability deviceName không chọn thiết bị trong UiAutomator2. Khi có nhiều target, dùng udid mới là cách chỉ đúng cái máy cần điều khiển.

Cách B: Android Emulator trong Android Studio

Mở Tools → Device Manager → Create Virtual Device, chọn Pixel 7, system image API 35 và đặt tên AVD là Pixel_7_API_35. Khởi động AVD, chờ tới khi màn hình home dùng được rồi kiểm tra:

adb devices -l
adb -s emulator-5554 shell getprop sys.boot_completed

adb devices có thể hiện device trước khi Android boot xong. Chỉ khi lệnh thứ hai trả về 1 thì mới nên mở Appium session.

Đặt target cho terminal chạy Robot:

$env:ANDROID_AVD = 'Pixel_7_API_35'
$env:ANDROID_TARGET = 'avd'

Nếu vừa cắm điện thoại thật vừa mở emulator, luôn truyền udid hoặc avd. Thả cho Appium tự chọn “thiết bị đầu tiên” là một trò may rủi không đem lại phần thưởng gì.

Chuẩn bị ApiDemos

Tải ApiDemos-debug.apk từ sample repository chính thức của AppiumLibrary và đặt vào demoapp\ApiDemos-debug.apk trong project. Có hai cách cài:

adb -s $env:ANDROID_UDID install -r .\demoapp\ApiDemos-debug.apk

Hoặc để Appium cài bằng capability app khi mở session. Bài này dùng cách thứ hai để project mới clone về có thể tự chuẩn bị app.

Smoke test đầu tiên

Tạo smoke.robot:

*** Settings ***
Library    AppiumLibrary
Suite Teardown    Close All Applications

*** Variables ***
${APPIUM_URL}    http://127.0.0.1:4723
${APK}           ${CURDIR}${/}demoapp${/}ApiDemos-debug.apk
${TARGET}        %{ANDROID_TARGET=avd}
${UDID}          %{ANDROID_UDID=}
${AVD}           %{ANDROID_AVD=Pixel_7_API_35}

*** Test Cases ***
ApiDemos Có Thể Mở Màn Hình Search
    Mở ApiDemos Trên Target Đã Chọn
    Wait Until Page Contains Element
    ...    id=io.appium.android.apis:id/txt_query_prefill
    ...    timeout=10s
    Capture Page Screenshot    smoke-search.png

*** Keywords ***
Mở ApiDemos Trên Target Đã Chọn
    IF    $TARGET == 'usb'
        Mở ApiDemos Trên Thiết Bị USB
    ELSE IF    $TARGET == 'avd'
        Mở ApiDemos Trên AVD
    ELSE
        Fail    ANDROID_TARGET must be 'usb' or 'avd', got '${TARGET}'
    END

Mở ApiDemos Trên Thiết Bị USB
    Should Not Be Empty    ${UDID}    ANDROID_UDID is required for USB
    Open Application
    ...    ${APPIUM_URL}
    ...    platformName=Android
    ...    automationName=UiAutomator2
    ...    udid=${UDID}
    ...    app=${APK}
    ...    appPackage=io.appium.android.apis
    ...    appActivity=.app.SearchInvoke
    ...    autoGrantPermissions=${TRUE}

Mở ApiDemos Trên AVD
    Open Application
    ...    ${APPIUM_URL}
    ...    platformName=Android
    ...    automationName=UiAutomator2
    ...    avd=${AVD}
    ...    app=${APK}
    ...    appPackage=io.appium.android.apis
    ...    appActivity=.app.SearchInvoke
    ...    autoGrantPermissions=${TRUE}

Keyword điều phối chọn đúng nhánh từ ANDROID_TARGET. Nhánh USB bắt buộc có ANDROID_UDID; nhánh AVD dùng tên virtual device. Hai keyword Open Application cố ý được viết đầy đủ ở bài cài đặt để bạn nhìn thấy capability khác nhau ở đâu. Sang bài sau phần lặp này sẽ được gom thành dictionary.

Open Application tạo một WebDriver session tại Appium Server. platformName cho biết đây là Android, còn automationName chọn UiAutomator2. app chỉ tới APK trên máy chạy Appium. appPackage và appActivity xác định ứng dụng cùng màn hình cần mở. autoGrantPermissions phù hợp cho sample app; với sản phẩm thật vẫn cần kiểm tra riêng flow từ chối và cấp permission.

Mở terminal thứ nhất và chạy server:

appium

Appium 3 mặc định nghe tại http://127.0.0.1:4723. Không tự thêm /wd/hub; đó là base path kiểu cũ.

Ở terminal thứ hai, kích hoạt .venv rồi chạy:

robot --outputdir results .\smoke.robot

Nếu test pass, results sẽ có output.xml, log.html, report.html và screenshot. Đây mới là mốc “setup chạy được”, không phải mốc cài package không báo đỏ.

Thiết bị thật và emulator khác nhau ở đâu?

Test logic không nên biết mình đang chạy trên dây USB hay AVD. Phần khác nhau chỉ nên nằm trong capability hoặc variable file. Bài sau chúng ta sẽ tách chính phần này ra để cùng một script chạy được trên cả hai.

Checklist cuối cùng

python --version
robot --version
node --version
npm --version
java -version
adb version
adb devices -l
appium --version
appium driver list --installed
appium driver doctor uiautomator2

Nếu tất cả lệnh trên ổn và smoke test tạo được session, phần cài đặt đã xong. Nếu chưa, đừng nhảy thẳng sang sửa XPath. XPath không có tội trong vụ adb còn chưa nhìn thấy điện thoại.

Trạng thái xác minh của bài: cú pháp Robot Framework đã được dry-run và site đã được build; smoke flow chưa được chạy trên thiết bị USB hoặc AVD thật trong lần viết này. Nói thẳng ra để bạn không nhầm một bài compile được với biên bản xác nhận thiết bị đã chạy ngon.

Nguồn tham khảo

• Install Appium
• Install the UiAutomator2 Driver
• Appium UiAutomator2 Driver
• AppiumLibrary
• Run apps on a hardware device
• Create and manage virtual devices