執行 CTS 驗證器主機端測試

本頁說明如何設定及執行 CTS 驗證器 (CTS-V) 主機端 Android 16 QPR2 和 Android 17 測試。主機端測試分為兩種:多裝置測試 (Android 17 之前推出) 和互動式測試 (Android 17 新推出):

  • 多裝置測試是全自動測試。
  • 互動式測試是半自動化測試,需要您在受測裝置 (DUT) 上執行一些手動步驟。

除了新的互動式測試外,手動測距準確度和電信測試現在也改為多裝置主機端測試,且必須執行 Wi-Fi 連線測試。

設定主機端測試

請按照下列步驟設定主機端測試 (多裝置測試需要額外設定):

  1. 確認桌上型電腦符合 CTS 的作業系統需求。

  2. 按照「安裝電腦軟體」的步驟 2 和 5,安裝並確認 adb、AAPT2 和 Python 已正確安裝在電腦上。

    • 電腦 Python 版本應為 3.11 以上。如要確認 Python 版本,請執行 python3 --version。如果版本低於 3.11,請安裝最新的官方 Python 版本。詳情請參閱 python.org 的「下載」部分。

    • 部分測試需要主機具備 Python venv 模組。在 Debian 和 Ubuntu 系統上,預設可能不會安裝這個模組。如要判斷電腦 Python 版本是否含有 venv 模組,請執行 python3 -m venv venv。如果這個指令失敗,系統會顯示錯誤訊息。按照提示安裝 python3.x-venv 套件。

如果只執行主機端互動式測試,請前往「執行主機端測試」。不過,如要執行多裝置測試,請前往「設定主機端多裝置測試」。

設定主機端多裝置測試

請按照下列步驟設定主機端多裝置測試:

  1. 確認桌上型電腦符合 CTS 的作業系統需求。

  2. 按照「安裝電腦軟體」的步驟 2 和 5,安裝並確認 adb、AAPT2 和 Python 已正確安裝在電腦上。

    • 電腦 Python 版本應為 3.11 以上。如要確認 Python 版本,請執行 python3 --version。如果版本低於 3.11,請安裝最新的官方 Python 版本。詳情請參閱 python.org 的「下載」部分。

      • 部分測試需要主機具備 Python venv 模組。在 Debian 和 Ubuntu 系統上,預設可能不會安裝這個模組。如要判斷電腦 Python 版本是否含有 venv 模組,請執行 python3 -m venv venv。如果這個指令失敗,系統會顯示錯誤訊息。按照提示安裝 python3.x-venv 套件。
  3. 準備兩個相符的待測裝置,並分別設定 CTS-V。

    • 如要進一步瞭解如何設定 DUT,請參閱「設定 DUT」。
    • 如要進一步瞭解如何設定 CTS-V,請參閱「設定」。
  4. 請參閱所用測試類型的設定章節:

如果測試不在這份清單中,請前往「設定標準雙裝置測試」。

設定 NFC 測試

NFC 測試會使用一個待測裝置和一個 PN532 NFC 晶片。

如何設定 NFC 測試:

  1. 購買 PN532 NFC 晶片。建議使用 All-In-One PN532。
  2. 在受測裝置上,前往「設定」應用程式。
  3. 啟用 NFC。
  4. 將 NFC 晶片對準:

    • 如果是手機,請將待測裝置的 NFC 讀取器放在圖 1 所示的位置:

      NFC 晶片位置

      圖 1. NFC 晶片位置。

    • 如果是其他類型的裝置,請將晶片放在裝置的 NFC 天線旁。

  5. 使用 USB 傳輸線將 PN532 NFC 晶片連接到測試工作站。

設定 Wi-Fi AP 連線測試

Wi-Fi 存取點 (AP) Connectivity Tests (CtsWifiConnectionTests) 會測試 DUT 與 AP 之間的連線。您可以透過下列兩種方式設定這些測試:

  • 方法 1:使用您為 CTS-V 設定的現有 Wi-Fi 網路。
  • 方法 2:設定可程式化的存取點 (AP)。

對於 Android 17,我們強烈建議採用選項 2,但並非必要。以下兩節將說明各個選項。

方法 1:使用為 CTS-V 設定的現有 Wi-Fi 網路

選項 1 需要一部位於 Wi-Fi 網路涵蓋範圍內的 Android 待測裝置。如果待測裝置位於屏蔽箱內,且無法連上 Wi-Fi 網路,請將其從屏蔽箱中取出。

方法 2:設定可程式化 AP

如要設定可程式化 AP 進行 Wi-Fi 連線測試,請按照下列步驟操作:

  1. 購買 Banana Pi R3 AP 並完成設定。如要瞭解如何購買及設定 Banana Pi R3 AP,請參閱「設定 Banana Pi BPI-R3 AP」。

  2. (選用) 如果沒有遮蔽箱,建議使用 JTP-SR101 遮蔽箱。請使用下列資訊購買這個盒子:

    東莞市正勝電子科技有限公司LTD

    中國廣東省東莞市寮步鎮蟠龍路博輝工業園

    聯絡人:Forest Pan

    電子郵件:forest.pan@jtpmak.cn

    電話 (中國):+86 18676993556

  3. 將待測裝置和 AP 連接至主機,並放入射頻屏蔽箱。待測裝置和 AP 應至少相距 10 公分。圖 2 顯示這項設定:

    待測裝置和 AP 位於屏蔽箱中

    圖 2. 待測裝置和 AP 位於屏蔽箱中。

  4. 使用 SSH 確認可以從主機存取 AP。

設定測距準確度測試

如要設定測距準確度測試,請按照下列步驟操作:

  1. 將兩部相符的 Android 待測裝置放在同一高度,相距 1 公尺,彼此之間沒有障礙物,且裝置背面相對。圖 3 顯示這種方向:

    裝置螢幕方向

    圖 3. 裝置螢幕方向。

  2. 使用 USB 傳輸線將兩部裝置連接到桌上型電腦。

設定標準雙裝置測試

預設的雙裝置設定:

  1. 將兩個相符的 Android 待測裝置放在相距約 20 公分的位置。

  2. 強烈建議:將兩部裝置放入屏蔽箱。屏蔽箱可提高測試穩定性,並簡化測試失敗的偵錯作業。

  3. 如要進行電信測試,每個 DUT 都必須有 SIM 卡和行動網路訊號。如果待測裝置位於屏蔽箱中,則必須將行動網路訊號耦合至箱內。否則,請將裝置移出屏蔽箱。

  4. 選用:設定 OTA 監聽器,以便進行 Wi-Fi 偵錯。

設定 CDM 測試

test_permissions_sync 測試案例的行為會因執行測試的裝置建構類型而異。OEM 必須測試可偵錯 (userdebug 或 eng) 和不可偵錯 (user) 的版本,且兩者都必須通過測試。

豁免資格

權限同步 API 實作的 CDD 條款僅要求能透過安全管道在裝置之間成功傳輸資料。由於安全管道實作並非 CDD 法規遵循要求,因此在不可偵錯 (使用者) 版本上,可以略過這項測試,但前提是您要選擇不支援 CDM 權限同步功能。

測試必須在可進行偵錯的版本上通過,不得有例外狀況。

在不可偵錯版本上進行測試的事前準備

如果您不符合豁免資格,請確認您符合下列必要條件。

安全管道會使用 AVF (AttestationVerificationFramework) 驗證硬體的可信度。雙方產生的認證包含多項關於自身的資訊,可驗證系統是否未經授權遭到任何修改。AVF 會在驗證程序中檢查下列狀態:

  • 裝置可連上網際網路

  • 裝置使用驗證開機程序,且版本是以發布金鑰 (而非開發金鑰) 簽署

  • 裝置的系統啟動載入程式已鎖定。詳情請參閱「鎖定系統啟動載入程式」。

  • OS、金鑰啟動和金鑰供應商修補程式等級在 12 個月內。請勿使用超過一年的版本。

  • 裝置認證由供應商核准的其中一個根憑證支援。在 vendor_required_attestation_certificates.xml 資源疊加層中指定信任的根憑證。

執行主機端測試

部分多裝置測試 (例如 NFC 測試) 需要額外設定。如果測試需要額外設定,則會個別執行。如果測試不需要額外設定,則可以群組形式執行。

  1. 在測試工作站上,從 CTS-V ZIP 套件解壓縮後的目錄啟動 cts-v-host 控制台:

    ./android-cts-verifier/android-cts-v-host/tools/cts-v-host-tradefed
    
  2. 在 DUT 上,點選 CTS-V 應用程式中的「主機端測試」。圖 4 顯示 CTS-V 應用程式中的主機端測試:

    CTS-V 應用程式中的主機端測試

    圖 4. CTS-V 應用程式中的主機端測試。

    系統會顯示主機端多裝置測試模組清單。

  3. 在 CTS-V 主機控制台中,使用下列指令執行多裝置測試,並採用標準雙裝置設定:

    run cts-v-host-multidevice-default
    

    結果會顯示在 DUT 上 CTS-V 應用程式的各個測試模組下方。標示為綠色的測試代表通過,標示為紅色的測試代表失敗。

    圖 5 顯示 CtsCompanionDeviceManager 測試的結果範例:

    CTS-V 應用程式中的主機端多裝置測試結果

    圖 5. CTS-V 應用程式中的主機端多裝置測試結果。

  4. 在 CTS-V 主機控制台中,使用下列指令執行互動式測試:

    run cts-v-host-interactive
    

    結果會顯示在 DUT 上 CTS-V 應用程式的各個測試模組下方。標示為綠色的測試代表通過,標示為紅色的測試代表失敗。

  5. 針對需要額外設定的測試,請使用下列指令分別執行:

    run cts-v-host -m test_module_name
    

    舉例來說,如要執行 NFC 測試,請使用下列指令:

    run cts-v-host -m CtsNfcHceMultiDeviceTestCases
    

    結果會顯示在 DUT 上 CTS-V 應用程式的各個測試模組下方。標示為綠色的測試代表通過,標示為紅色的測試代表失敗。

執行 Wi-Fi AP 連線測試

您可以透過下列兩種方式執行 Wi-Fi AP 連線測試:

  • 方法 1:使用您為 CTS-V 設定的現有 Wi-Fi 網路。
  • 方法 2:設定可程式化 AP。

方法 1:使用為 CTS-V 設定的現有 Wi-Fi 網路

如要在現有 Wi-Fi 網路上執行 Wi-Fi AP 連線測試,請按照下列步驟操作:

  1. 編輯測試平台設定檔 (WifiConnectionTestbed.yaml)。這個檔案位於 CTS-Verifier 解壓縮後的目錄中。例如:

    ./android-cts-verifier/android-cts-v-host/testcases/CtsWifiConnectionTests/x86_64/connection/WifiConnectionTestbed.yaml
    
  2. 將 wifi_ssid 和 wifi_password 欄位的值變更為 Wi-Fi 網路的 SSID 和密碼。以下範例顯示這些設定的位置:

    TestBeds:
    -   Name: WifiConnectionTestbed
    Controllers:
      AndroidDevice: '*'
    TestParams:
      use_programmable_ap: False
      wifi_ssid: WIFI-SSID
      wifi_password: WIFI-PASSWORD
    
  3. 在 CTS-V 主機控制台中,執行下列指令:

    run cts-v-host -m CtsWifiConnectionTests
    

選項 2:使用可程式化 AP 執行

如要在可程式化 AP 上執行 Wi-Fi AP 連線測試,請按照下列步驟操作:

  1. 編輯測試平台設定檔 (WifiConnectionTestbed.yaml)。這個檔案位於 CTS-Verifier 解壓縮後的目錄中。例如:

    ./android-cts-verifier/android-cts-v-host/testcases/CtsWifiConnectionTests/x86_64/connection/WifiConnectionTestbed.yaml
    
  2. 根據本機 SSH 設定,將 hostname 的值變更為 AP 的 IP 位址。如要找出 IP 位址,請參閱「找出 AP 的 IP 位址」一節。以下範例顯示 hostname 設定的位置:

    TestBeds:
    -   Name: WifiConnectionTestbed
      Controllers:
        AndroidDevice: '*'
        # Specify settings for the AP.
        OpenWrtDevice:
        -   hostname: AP-IP
          skip_init_reboot: True
      TestParams:
        use_programmable_ap: True
    
  3. 在 CTS-V 主機控制台中,執行下列指令:

    run cts-v-host -m CtsWifiConnectionTests
    

執行 USB 主機端測試

Android 17 包含 USB CTS-V 主機端測試,需要透過 Wi-Fi 執行 adb。

部分 USB 測試需要使用 CTS-V 主機,才能存取一般 CTS-V 應用程式無法存取的 SystemAPI 權限。這些測試不需連接裝置,且必須透過 Wi-Fi 使用 adb。

如果 DUT 支援在 UsbPort.java 中回報連接埠合作夥伴 BC 1.2 類型或 USB 電源設定檔,則需要下列 Type-C 配件:

  • USB Type-C Power Delivery (PD) 充電器
  • USB 電池充電 1.2 (BC 1.2) 標準下行連接埠 (SDP)。這些連接埠只能為 DUT 提供 500 mA 或 900 mA 的電流,通常位於外部集線器的 USB 連接埠。
  • USB BC 1.2 充電下游連接埠 (CDP)。這些連接埠可為待測裝置和資料提供 1.5 A 的電流。筆電或電腦上的 Type-C 連接埠可能是 CDP。
  • USB BC 1.2 專用充電埠 (DCP)。這些連接埠可為待測裝置提供 1.5 A 的電流,但無法傳輸資料。這份清單中的 USB Type-C PD 充電器可能是 DCP。
  1. 透過 Wi-Fi 使用 adb 連線至 DUT。如需設定詳情,請參閱「透過 Wi-Fi 連線至裝置」。

  2. 拔除裝置的所有 USB 連接線。如果執行測試指令時,裝置連接到任何 USB 主機或配件,測試就會失敗。

  3. 執行下列測試指令:

    run cts-v-host -m CtsUsbTypecTestCases
    

測試完成後,結果會顯示在 CTS-V 應用程式的「主機端測試」下方,如下圖所示:

CTS-V 應用程式中的主機端 USB 測試

圖 6. CTS-V 應用程式中的主機端 USB 測試。

主機端 USB CTS-V 應用程式中的 CtsUsbTypecTestCases 套件

圖 7. 主機端 USB CTS-V 應用程式中的 CtsUsbTypecTestCases 套件。

排解多裝置測試問題

本節說明常見問題的疑難排解方式。

在 CtsTelecomTest 期間無法取得電話號碼

如果收到錯誤訊息 Failed to get phone number for <serial>,請按照下列步驟操作:

  1. 確認每個待測裝置都已安裝 SIM 卡。

  2. 如果錯誤持續發生,表示 SIM 卡可能不支援自動擷取號碼,此時您必須在指令中明確提供電話號碼。

    舉例來說,如果是 DUT 1 (序號 17011FDEE0002N,電話號碼 555-0000) 和 DUT 2 (序號 R3CN90YNAR,電話號碼 555-1111),請將下列引數附加至 run cts-v-host 指令:

    --module-arg CtsTelecomTest:dut_serial:17011FDEE0002N \
    --module-arg CtsTelecomTest:dut_phone_number:555-0000 \
    --module-arg CtsTelecomTest:ref_phone_number:555-1111
    

執行 CtsMultiDeviceGenericRangingAccuracyTests 時,伺服器沒有回應

如果收到下列錯誤訊息,表示測試應用程式可能在特定裝置上,遭到原始設備製造商 (OEM) 專屬的背景程序管理凍結或終止:

mobly.snippet.errors.ProtocolError: <AndroidDevice|Initiator> No response from server. Check the device logcat for crashes.

如要解決這個問題,請停用背景限制,或將下列套件加入許可清單:

套件 顯示名稱
com.google.snippet.uwb CtsUwbSnippetApp
com.google.snippet.ranging CtsRangingSnippetApp
com.google.snippet.bluetooth CtsBluetoothMultiDeviceSnippetApp
com.google.android.mobly.snippet.bundled androidx.multidex.MultDexApplication

修正 NFC 測試期間 GetFirmwareVersion 無回應的問題

如果在執行多裝置測試時收到 verify_firmware_version RuntimeError: No response for GetFirmwareVersion 訊息,表示測試無法存取 PN532 NFC 板。

如要修正這個問題,請找出主機上 PN532 NFC 板使用的序列路徑 (例如 dev/ttyUSB1),然後在控制台中使用 --module-arg 引數手動指定該路徑:

run cts-v-host -m CtsNfcHceMultiDeviceTestCases --module-arg CtsNfcHceMultiDeviceTestCases:pn532_serial_path:/dev/ttyUSB1

修正 NFC 測試期間的「交易失敗」錯誤訊息

如果所有 NFC 測試案例都收到 Transaction failed, check device logs for more information. 訊息,可能是因為待測裝置的 NFC 晶片無法偵測到 PN532。

如果有多部裝置連線至主機,且其中部分裝置未放置 PN532,則可能選取了錯誤的待測裝置。詳情請參閱「設定 NFC 測試」。

如要修正這個問題,請採取下列任一做法:

  • 使用 -s 旗標,在主機端測試指令中設定正確的待測裝置序號。

  • 中斷所有非 DUT 裝置與主機的連線。

已忽略 CDM 測試案例 test_permissions_sync

如果測試是在不可偵錯的裝置上執行,請確認您是否符合豁免資格。否則,請確認兩部裝置都符合必要條件。