雲端 Mac 上的 iOS 二維碼產出與辨識驗收

發版前，App 已將入場憑證存成二維碼 PNG，畫面預覽也正常；但實際掃描時，仍可能因縮放插值、邊緣遭裁切，或前景與背景對比不足而失敗。與其只斷言「檔案存在」，不如在雲端 Mac 上取出 App 最終輸出的圖片，交給 Vision 再辨識一次，並核對辨識內容。這是一項適合納入 iOS 回歸流程的檔案層級檢查。

先界定驗收範圍

本文檢查的是App 實際寫出的 PNG，不是測試腳本自行產生的二維碼。固定測試資料為 case-123；App 的測試進入點應將對應圖片寫入其沙盒中的 Documents/qr-sample.png。如果產品只在畫面上繪製二維碼，可以先透過既有的匯出功能取得檔案；不要另外寫一套測試產生器來冒充正式輸出。

通過條件有三項：能從 App 容器取出檔案；Vision 恰好辨識出一個二維碼；解碼後的字串與預期值完全一致。檔案雜湊不適合作為主要斷言：編碼參數或 PNG 中繼資料的變動可能改變檔案位元組，卻不影響二維碼內容。

這裡的「可辨識」僅針對匯出的數位圖片。相機對焦、螢幕亮度和列印尺寸都會帶來額外變數；檔案層級的驗收無法取代實際掃碼。

從模擬器取出最終檔案

先在已啟動的 iOS 模擬器中執行測試進入點，確認 App 確實寫入約定路徑。以下指令要求環境變數 BUNDLE_ID 已設為受測 App 真正的 bundle identifier；get_app_container 會傳回該 App 的資料容器路徑。

test -n "$BUNDLE_ID" || exit 2
APP_DATA=$(xcrun simctl get_app_container booted "$BUNDLE_ID" data) || exit 1
mkdir -p artifacts
cp "$APP_DATA/Documents/qr-sample.png" artifacts/qr-sample.png
file artifacts/qr-sample.png

如果 cp 失敗，先檢查 App 是否在目前已啟動的模擬器上執行，以及匯出邏輯是否真的將檔案寫入 Documents。不要從開發用電腦挑一張同名圖片補上，否則回歸檢查就會繞過 App。若 App 每次輸出多個檔案，測試進入點應使用固定檔名，並在每輪執行前清除舊檔，避免誤讀上一次的結果。

使用 Vision 解碼並核對內容

將以下內容儲存為工作目錄中的 qr-check.swift。腳本接收 PNG 路徑與預期文字；輸入、辨識或比對失敗時，都會以非零狀態結束，方便管線直接判定。

import Foundation
import Vision

guard CommandLine.arguments.count == 3 else {
    fputs("usage: swift qr-check.swift IMAGE EXPECTED\n", stderr)
    exit(2)
}

let url = URL(fileURLWithPath: CommandLine.arguments[1])
let expected = CommandLine.arguments[2]
let request = VNDetectBarcodesRequest()
request.symbologies = [.qr]

do {
    try VNImageRequestHandler(url: url, options: [:]).perform([request])
    let codes = (request.results ?? []).filter { $0.symbology == .qr }
    guard codes.count == 1,
          codes[0].payloadStringValue == expected else {
        fputs("QR count or payload mismatch\n", stderr)
        exit(1)
    }
    print("QR payload verified")
} catch {
    fputs("QR image could not be analyzed\n", stderr)
    exit(1)
}

執行 swift qr-check.swift artifacts/qr-sample.png case-123。不要只檢查辨識數量：即使成功辨識，二維碼內容仍可能是舊訂單編號、錯誤前綴或遭截斷的文字。正式測試資料也不應包含真實憑證；若業務資料含有敏感欄位，使用專門設計的無效測試值覆蓋格式與解析邏輯即可。

分層排查失敗原因

先看匯出的檔案，再看辨識結果，最後才回頭檢查二維碼產生程式碼。這樣才能區分「根本沒有匯出」與「已匯出但無法辨識」。

如果 App 使用 Core Image 產生二維碼，應先保留產生器 outputImage 的完整邊界，再以整數倍放大，最後寫出 PNG。也要檢查分享或截圖流程是否又透過插值將圖片縮小一次；預覽看起來平滑，不代表方塊邊緣仍然清晰。使用深色主題時，還須檢查最終檔案的顏色：畫面背景與匯出圖片的背景未必相同，透明區域換了底色後可能失去對比。

避免檢查產生錯誤結果

固定一張測試圖片、一組明確的測試資料和一個輸出路徑，但每次都要從本輪 App 執行結果取圖。若要涵蓋不同長度、非 ASCII 字元或含分隔符號的資料，請分別建立測試案例並逐一比對，不要把多個預期字串設成「符合其中一個即可」。二維碼解碼成功，也不代表業務連結可用；需要驗收跳轉行為時，應在另一層測試中檢查解析與路由。

將結果接入回歸流程

在既有模擬器測試之後執行取圖指令與 Swift 腳本，讓任一步驟的非零結束碼中止本輪工作。失敗時保留本輪 PNG 和腳本的錯誤輸出，方便判斷是匯出路徑變更，還是圖片處理造成品質退化；通過後只需記錄驗收狀態，不必長期保存含有業務資料的圖片。

最後確認四件事：圖片來自 App 的最終輸出；沒有讀到上一輪殘留檔案；Vision 恰好讀出一個二維碼；內容與固定測試值完全一致。完成這些檢查，檔案層級的二維碼回歸測試就有了清楚、可重複的邊界。若涉及螢幕展示或列印交付，再補上使用真實裝置的掃碼驗收。

常見問題