本頁說明如何設定及執行 CTS 驗證器 (CTS-V) 主機端 Android 16 QPR2 和 Android 17 測試。主機端測試分為兩種:多裝置測試 (Android 17 之前推出) 和互動式測試 (Android 17 新推出):
- 多裝置測試是全自動測試。
- 互動式測試是半自動化測試,需要您在受測裝置 (DUT) 上執行一些手動步驟。
除了新的互動式測試外,手動測距準確度和電信測試現在也改為多裝置主機端測試,且必須執行 Wi-Fi 連線測試。
設定主機端測試
請按照下列步驟設定主機端測試 (多裝置測試需要額外設定):
確認桌上型電腦符合 CTS 的作業系統需求。
按照「安裝電腦軟體」的步驟 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套件。
如果只執行主機端互動式測試,請前往「執行主機端測試」。不過,如要執行多裝置測試,請前往「設定主機端多裝置測試」。
設定主機端多裝置測試
請按照下列步驟設定主機端多裝置測試:
確認桌上型電腦符合 CTS 的作業系統需求。
按照「安裝電腦軟體」的步驟 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套件。
- 部分測試需要主機具備 Python
準備兩個相符的待測裝置,並分別設定 CTS-V。
請參閱所用測試類型的設定章節:
- 如要進行 NFC 測試,請參閱「設定 NFC 測試」。
- 如要進行 Wi-Fi AP 連線測試,請參閱「設定 Wi-Fi AP 連線測試」。
- 如要進行測距準確度測試,請參閱「設定測距準確度測試」。
- 如要測試 CDM 模組,請參閱「設定標準雙裝置測試」,然後參閱「設定 CDM 測試」。
如果測試不在這份清單中,請前往「設定標準雙裝置測試」。
設定 NFC 測試
NFC 測試會使用一個待測裝置和一個 PN532 NFC 晶片。
如何設定 NFC 測試:
- 購買 PN532 NFC 晶片。建議使用 All-In-One PN532。
- 在受測裝置上,前往「設定」應用程式。
- 啟用 NFC。
將 NFC 晶片對準:
如果是手機,請將待測裝置的 NFC 讀取器放在圖 1 所示的位置:

圖 1. NFC 晶片位置。
如果是其他類型的裝置,請將晶片放在裝置的 NFC 天線旁。
使用 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 連線測試,請按照下列步驟操作:
購買 Banana Pi R3 AP 並完成設定。如要瞭解如何購買及設定 Banana Pi R3 AP,請參閱「設定 Banana Pi BPI-R3 AP」。
(選用) 如果沒有遮蔽箱,建議使用 JTP-SR101 遮蔽箱。請使用下列資訊購買這個盒子:
東莞市正勝電子科技有限公司LTD
中國廣東省東莞市寮步鎮蟠龍路博輝工業園
聯絡人:Forest Pan
電子郵件:forest.pan@jtpmak.cn
電話 (中國):+86 18676993556
將待測裝置和 AP 連接至主機,並放入射頻屏蔽箱。待測裝置和 AP 應至少相距 10 公分。圖 2 顯示這項設定:

圖 2. 待測裝置和 AP 位於屏蔽箱中。
使用 SSH 確認可以從主機存取 AP。
設定測距準確度測試
如要設定測距準確度測試,請按照下列步驟操作:
將兩部相符的 Android 待測裝置放在同一高度,相距 1 公尺,彼此之間沒有障礙物,且裝置背面相對。圖 3 顯示這種方向:

圖 3. 裝置螢幕方向。
使用 USB 傳輸線將兩部裝置連接到桌上型電腦。
設定標準雙裝置測試
預設的雙裝置設定:
將兩個相符的 Android 待測裝置放在相距約 20 公分的位置。
強烈建議:將兩部裝置放入屏蔽箱。屏蔽箱可提高測試穩定性,並簡化測試失敗的偵錯作業。
如要進行電信測試,每個 DUT 都必須有 SIM 卡和行動網路訊號。如果待測裝置位於屏蔽箱中,則必須將行動網路訊號耦合至箱內。否則,請將裝置移出屏蔽箱。
選用:設定 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 測試) 需要額外設定。如果測試需要額外設定,則會個別執行。如果測試不需要額外設定,則可以群組形式執行。
在測試工作站上,從 CTS-V ZIP 套件解壓縮後的目錄啟動
cts-v-host控制台:./android-cts-verifier/android-cts-v-host/tools/cts-v-host-tradefed在 DUT 上,點選 CTS-V 應用程式中的「主機端測試」。圖 4 顯示 CTS-V 應用程式中的主機端測試:
圖 4. CTS-V 應用程式中的主機端測試。
系統會顯示主機端多裝置測試模組清單。
在 CTS-V 主機控制台中,使用下列指令執行多裝置測試,並採用標準雙裝置設定:
run cts-v-host-multidevice-default結果會顯示在 DUT 上 CTS-V 應用程式的各個測試模組下方。標示為綠色的測試代表通過,標示為紅色的測試代表失敗。
圖 5 顯示 CtsCompanionDeviceManager 測試的結果範例:
圖 5. CTS-V 應用程式中的主機端多裝置測試結果。
在 CTS-V 主機控制台中,使用下列指令執行互動式測試:
run cts-v-host-interactive結果會顯示在 DUT 上 CTS-V 應用程式的各個測試模組下方。標示為綠色的測試代表通過,標示為紅色的測試代表失敗。
針對需要額外設定的測試,請使用下列指令分別執行:
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 連線測試,請按照下列步驟操作:
編輯測試平台設定檔 (
WifiConnectionTestbed.yaml)。這個檔案位於 CTS-Verifier 解壓縮後的目錄中。例如:./android-cts-verifier/android-cts-v-host/testcases/CtsWifiConnectionTests/x86_64/connection/WifiConnectionTestbed.yaml將
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在 CTS-V 主機控制台中,執行下列指令:
run cts-v-host -m CtsWifiConnectionTests
選項 2:使用可程式化 AP 執行
如要在可程式化 AP 上執行 Wi-Fi AP 連線測試,請按照下列步驟操作:
編輯測試平台設定檔 (
WifiConnectionTestbed.yaml)。這個檔案位於 CTS-Verifier 解壓縮後的目錄中。例如:./android-cts-verifier/android-cts-v-host/testcases/CtsWifiConnectionTests/x86_64/connection/WifiConnectionTestbed.yaml根據本機 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在 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。
透過 Wi-Fi 使用
adb連線至 DUT。如需設定詳情,請參閱「透過 Wi-Fi 連線至裝置」。拔除裝置的所有 USB 連接線。如果執行測試指令時,裝置連接到任何 USB 主機或配件,測試就會失敗。
執行下列測試指令:
run cts-v-host -m CtsUsbTypecTestCases
測試完成後,結果會顯示在 CTS-V 應用程式的「主機端測試」下方,如下圖所示:
圖 6. CTS-V 應用程式中的主機端 USB 測試。
圖 7. 主機端 USB CTS-V 應用程式中的 CtsUsbTypecTestCases 套件。
排解多裝置測試問題
本節說明常見問題的疑難排解方式。
在 CtsTelecomTest 期間無法取得電話號碼
如果收到錯誤訊息 Failed to get phone number for <serial>,請按照下列步驟操作:
確認每個待測裝置都已安裝 SIM 卡。
如果錯誤持續發生,表示 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 裝置與主機的連線。