Skip to content

About

Define device tests in YAML. Run commands, validate output files and review results.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Device Test Runner

Device Test Runner

Device Test Runner 使用 YAML 定義裝置測試流程,執行既有的 Bash、Python、ADB 等命令,並保存每次執行的輸出與 JSON 報告。它負責安排測試步驟、驗證輸出檔案,以及依設定重試失敗步驟;裝置操作仍由你的腳本處理。

目前版本為 v1.7.3。支援五階段測試流程、整次執行、清理範圍與步驟逾時、選擇性重試、輸出檔案驗證、程序群組清理、Ctrl+C 取消、靜態變數替換與 host 環境變數引用與裝置 runtime context。

解決的痛點

  • 測試命令散落在不同腳本:用 YAML 統一描述準備、測試與清理順序,沿用既有 Bash、Python 或 ADB 命令。
  • 命令成功不代表產物正確:檢查檔案是否存在、大小、副檔名、目錄內容,以及 CSV/JSON 內容。
  • 偶發失敗難以重現:依失敗類型重試,為每次嘗試保留獨立 stdout/stderr。
  • 測試卡住或中途停止:設定逾時、提出取消請求,並依生命週期規則執行清理。
  • 人工整理結果費時:每次執行產生獨立目錄與 JSON 報告,供檢查與自動化處理。

專案架構

YAML Configuration
        ↓
Config Loader (schema → dataclasses → cross-field validation)
        ↓
RunnerConfig
        ↓
DeviceTestRunner
        ├── StaticVariableResolver (先解析裝置,再解析命令與路徑)
        ├── Lifecycle Orchestration
        ├── CleanupScope / scope watchdogs
        ├── CancellationToken
        ├── RetryPolicy
        ├── SubprocessExecutor
        ├── ArtifactManager
        ├── ArtifactValidator
        └── JsonReporter
                ↓
       result.json / per-attempt logs / validation results
路徑 用途
main.py CLI 入口,載入設定並啟動測試
runner/ 流程控制、命令執行、重試、取消、產物驗證與報告
configs/ YAML 設定範例
scripts/ 供測試流程呼叫的腳本
tests/ 專案自動化測試
docs/ 架構、測試、驗收與版本文件

詳細介面與執行流程見 v1.7.3 架構。

安裝

需要 Python 3.10+ 與 Poetry 2.x。程序群組清理使用 POSIX signal API;目前本機驗證為 macOS,沒有 Windows 支援驗證。在專案目錄執行:

git clone https://github.com/andrew771027/DeviceTestRunner.git
cd DeviceTestRunner
poetry install

Poetry 會建立虛擬環境,依 poetry.lock 安裝專案與開發依賴。後續指令都透過 poetry run 執行。

快速開始

將以下內容存為 configs/hello.yaml。此範例使用 POSIX shell 的 echo,不需要裝置。

test_case: {id: hello, name: Hello Runner, description: Print one line.}
device: {serial: demo, product: demo, build: demo}
lifecycle:
  global_setup: {steps: []}
  setup: {steps: []}
  scenario:
    steps:
      - name: hello
        type: command
        command: echo hello
  teardown: {steps: []}
  global_teardown: {steps: []}
artifact:
  output_dir: artifacts

在專案根目錄執行:

poetry run python main.py --config configs/hello.yaml

到 artifacts/ 下當次 run directory 查看 result.json 與 stdout/stderr logs。以 summary.status 判斷結果:PASSED、FAILED、CANCELLED 或 TIMED_OUT。TIMED_OUT 目前仍回傳 exit code 0,自動化需讀取報告。

完整操作、所有設定欄位的必填/選填、預設值、用途與範例,請閱讀 使用手冊。命令在 run directory 執行;引用專案腳本使用 $DEVICE_TEST_RUNNER_ROOT。ADB 等外部工具與裝置需自行準備,device 欄位提供報告資訊與模板引用,不會自動選擇裝置。

靜態變數範例 advance_sample.yaml 不需要裝置,會生成並驗證 CSV:

export ANDROID_SERIAL=emulator-5566
poetry run python main.py --config configs/advance_sample.yaml

variables 可在 step command、timeout_second 與 artifact validation path 中以 ${{ vars.NAME }} 引用;${{ run.dir }} 提供當次絕對路徑。完整引用保留型別,YAML step timeout literal 接受正整數;完整模板解析後接受有限正整數或小數。語法與限制見 靜態變數指南。

device.serial、step command 與 artifact path 可引用 ${{ env.NAME }}。先在啟動 runner 的 shell 設定變數,例如 export DEVICE_SERIAL=demo-001。環境值以字串解析,每次 run 使用固定快照;缺少 serial 引用的變數時不建立 run directory。完整操作見 環境變數指南。

${{ device.serial }}、${{ device.product }} 與 ${{ device.build }} 可在命令與驗證路徑引用當次裝置資訊。三個 device 欄位都必須是非空且不含未解析模板的字串;product/build 使用 literal 值。操作與限制見 Runtime Context 指南。

設定載入時會拒絕未知欄位、不合法型別、重複 step/rule 名稱與不存在的 after_step。省略 lifecycle 階段時使用空 steps。完整規則見 設定驗證指南。

configs/demo.yaml 是特定 macOS Android 工作站範例,使用外部 android-environment/android-cookbook 絕對路徑;需替換路徑並準備 JDK、SDK、ADB 與專用 emulator host。poetry run make demo 會建置 APK、操作 emulator,最後停止並刪除指定 AVD;不屬於無裝置入門範例。

執行專案測試

執行所有測試:

poetry run pytest

顯示較完整輸出:

poetry run pytest -v

只執行 retry 相關測試:

poetry run pytest -m retry

只執行 cancellation 標記測試(不等同完整 suite):

poetry run pytest -m cancelled

只執行 artifact 相關測試:

poetry run pytest -m artifact

測試工具與撰寫方式見 測試指南;覆蓋範圍與驗證紀錄見 測試矩陣 與 完成條件。

持續整合

CI workflow 會在 push 至 main 或建立以 main 為目標的 pull request 時執行。流程安裝 Python、Poetry 與專案依賴後,執行 pytest。

在本機執行相同的測試:

poetry install
poetry run pytest

限制與後續規劃

目前以單機命令流程為主。Recorder 管理、批次與並行執行、controller/worker 遠端執行仍在規劃中;詳細範圍與進度見 Roadmap。

程序清理與平台限制見 Process Lifecycle。執行逾時後的 cleanup 與最終產物驗證可能延長返回時間;自動化整合請讀取報告狀態,TIMED_OUT 目前仍會回傳 exit code 0。

維護者提交、發佈與操作手動文件更新 workflow 時,請參閱 提交與發佈檢查清單。

文件

文件 用途
快速開始 建立第一個設定並查看結果
CHANGELOG 歷史變更與版本差異
使用手冊 操作步驟、設定欄位、範例與結果判讀
靜態變數指南 引用語法、解析順序、整合與錯誤行為
環境變數指南 Host 變數、快照、失敗時機與欄位限制
設定驗證 結構、跨欄位規則、錯誤與 API 邊界
Runtime Context 裝置引用、綁定順序與相容性限制
Roadmap 後續功能與版本規劃
Process Lifecycle 程序清理行為與限制
Cancellation-Aware Cleanup v1.6.3 cleanup scope、逾時、partial artifacts 與報告優先順序
提交檢查清單 提交、發佈與文件維護流程
架構 v1.7.3 元件、取消路由、報告欄位與相容性
測試指南 Pytest 工具、fixture、Mock 與各版用法
測試矩陣 v1.7.3 功能對應的測試與覆蓋限制
驗收條件 v1.7.3 可觀察的預期行為
完成條件 v1.7.3 驗證紀錄與待完成的發佈項目

docs/ 內的舊版文件保留當時的設計與介面,使用時請確認版本。

About

Define device tests in YAML. Run commands, validate output files and review results.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages