Swift.org 的 Swift 6.4 發布說明確認，Swift Testing 與 XCTest 可朝兩個方向互操作：在 Swift Testing 測試中使用 XCTest 斷言，也能在 XCTest 中使用 #expect。官方發布說明因此，遇到 Swift 6.4 XCTest 互操作報錯時，先找出是哪套測試呼叫了另一套框架的斷言，再核對工具鏈、套件的 swift-tools-version 與互操作模式；不必一開始就重寫舊測試。這些能力不代表所有 API 或測試行為都能互換。

本文適合正在同一個課程專案中並用舊 XCTest 與新 Swift Testing 的學生，以及升級 Swift 工具鏈或套件版本後發現測試報告異常的初學者。
若你要用 Xcode 完成 Apple 平台課程驗收，也可依照下列檢查順序，分辨是測試程式本身、執行環境，還是跨框架呼叫造成問題。

資料核對：本文的互操作與設定說明依 Swift.org 的 Swift 6.4 發布說明、Apple Developer 遷移文件、Swift Package Manager 文件及互操作提案整理。最後更新於 2026 年 10 月 10 日；發布前核對自Swift 6.4 發布說明與Apple 的遷移說明。

Swift 6.4 XCTest 互操作報錯：先分清楚是哪種異常

「測試看起來怪怪的」不一定代表互操作出了問題。先依照測試結果分類，才能避免把環境問題誤當成斷言失效。

  • 測試顯示通過，但預期的失敗沒有被記錄：檢查 Swift Testing 測試內是否呼叫了封裝 XCTest 斷言的輔助函式。測試若只看表面結果，可能漏掉跨框架問題的記錄方式。
  • 測試仍能執行，卻出現警告或現代化提示：記下警告出現的位置及其所屬測試，不要只憑提示文字批次替換舊斷言。
  • 測試直接失敗：查看失敗項目與呼叫堆疊，確認失敗是在斷言、建置，還是測試執行階段發生。
  • 找不到測試結果：先確認測試目標確實執行，並查看結果中有沒有被跳過、沒有收集到，或建置失敗的紀錄。

Apple 的遷移文件說明 XCTest 與 Swift Testing 的使用方式及遷移時需留意的差異；因此，「另一套框架的斷言被呼叫」與「測試沒有執行」應分開判斷，不要只看最後顯示的成功或失敗狀態。參閱 Apple 的 XCTest 遷移說明。

Swift Testing 裡的 XCTAssert 失敗，卻沒有顯示錯誤怎麼辦？
先定位呼叫 XCTAssert 的輔助函式，再確認它是由哪個 Swift Testing 測試呼叫，並檢視該次執行的完整診斷。若只檢查測試總結、沒有檢查問題紀錄，就不能據此斷定斷言沒有生效。接著依照目前互操作模式確認該類跨框架問題會如何回報。

第一步：標出斷言的來源與呼叫位置

在調整設定前，先沿著一個出問題的測試追蹤呼叫路徑。課程專案常會保留舊的 XCTest 輔助函式；外層測試改用 Swift Testing 後，仍可能間接執行那些舊斷言。

可以先在專案中搜尋 XCTAssert、#expect 及呼叫相關輔助函式的測試，並逐項記錄：

  • 測試本身使用 XCTest 還是 Swift Testing。
  • 斷言實際寫在哪個函式，以及它由哪一個測試呼叫。
  • 測試結果是通過、失敗、出現警告，還是根本沒有執行。
  • 同一次執行中是否還有建置錯誤或測試被跳過的訊息。

兩套框架可以放在同一個測試檔案嗎？
互操作支援並不等於每種測試宣告都可以不加區別地混寫，也不保證不同測試執行方式會產生相同報告。先依 Apple 遷移文件確認目前使用的測試形式與呼叫位置；若不確定，就以最小測試分別驗證，而不是把整個課程專案的測試一次搬到同一檔案。

提醒：測試框架的宣告、斷言和執行結果是不同層次。只看到 XCTAssert 或 #expect，還不足以判定整個測試是否被執行，也不足以推論其他 API 的行為。

第二步：核對工具鏈與 Package 版本

「工具鏈」可以想成正在使用的編譯器與相關開發工具版本；swift-tools-version 則像 Package 的教材版本標記，會影響套件採用哪一套工具規則。兩者可能不一致，所以只看到 Xcode 版本，未必能解釋套件實際採用的設定。

依照以下順序檢查，並把結果記下來：

  • 在 Xcode 的測試結果中確認實際執行的是哪個測試目標，不要只看專案名稱。
  • 記錄目前使用的 Swift 工具鏈，以及是哪個 Package 發生問題。
  • 開啟該套件的 Package.swift，核對檔案開頭宣告的 swift-tools-version。
  • 查看測試結果中的完整警告或錯誤文字，保留它指向的檔案與呼叫位置。
  • 若透過環境變數設定互操作模式，記下變數名稱、值，以及該設定套用到哪個測試執行工作。

Swift Package Manager 文件說明了 swift-tools-version 的用途；Apple 的 Xcode 文件則說明如何執行測試及解讀結果。預設互操作行為可能受工具鏈與套件工具版本影響，因此要把這些資訊和報告放在一起看，不要只用「剛升級 Xcode」推斷原因。查看 swift-tools-version 文件與Apple 的 Xcode 測試說明。

升級 Swift 6.4 後如何檢查 XCTest 互操作模式？
先確認實際使用的工具鏈與套件版本，再查看專案或執行環境是否明確設定互操作模式。Swift 互操作提案說明相關模式與環境設定；不要從其他專案複製環境變數名稱或值，應以提案中的記載及目前專案實際設定為準。核對互操作提案。

第三步：按模式的診斷範圍調整，不要只為消除紅字

none、limited、complete 與 strict 是互操作模式；它們會影響跨框架情況如何被涵蓋或回報。可以把模式想成測試批改規則：有的規則較少檢查跨框架問題，有的會涵蓋更完整或採取更嚴格的診斷。名稱本身不能代替具體規則，調整前必須對照官方文件，確認目前版本對目標呼叫的處理方式。

| wait no tables. Need no table. Use bullets decision branches. Continue correct no table. Need decision conditions list explicit. We can't use table. 決策條件列表: - 若 test Swift Testing + XCTest assertion... - etc.

XCTest 中使用 #expect 為何可能出現測試問題？
因為兩套框架的斷言與測試執行機制各有邊界，開啟互操作支援不代表任意混用都不會產生診斷差異。先確認呼叫位置、模式及測試報告，再依官方提案核對該模式涵蓋的行為，不要把「採用了 #expect」直接當成故障根因。

請依照以下條件分流：

  • 若問題只出現在跨框架斷言，而且模式或診斷範圍尚未確認，先記錄現況並查閱對應工具版本的官方說明；暫時不要批次改寫斷言。
  • 若專案明確要求更嚴格地發現跨框架問題，確認團隊或課程規範後，再評估 strict 等模式是否符合需求；不要只為了讓測試回綠而降低檢查。
  • 若切換模式後警告或錯誤數量改變，將它視為診斷範圍改變的線索，不等於程式已修正。以同一組最小測試比較修改前後的報告。
  • 若問題是測試目標未執行、被跳過或建置失敗，先回到 Xcode 測試執行與專案設定檢查；互操作模式不是處理這些現象的通用開關。

模式的完整定義及相關設定方式，應以互操作提案 ST-0021及當前工具鏈文件為準。不要僅憑模式名稱推定錯誤一定會變成警告或失敗，也不要在沒有確認影響範圍前修改共用設定。

第四步：分辨互操作問題與 Xcode 執行問題

若測試沒有產生預期結果，先確認「測試有沒有被跑起來」，再判斷斷言是否以預期方式回報。Xcode 的測試結果可協助定位哪些測試執行、哪些失敗，以及問題所在的診斷資訊；錯誤位置若落在建置階段，就不應先改斷言。Apple 的測試結果說明可用來核對測試執行與報告的判讀方式。

可以用這個順序排除：

  • 建置失敗：先查看編譯錯誤與錯誤檔案，不要將建置未完成說成斷言失效。
  • 測試被跳過或沒有出現在結果內：確認選取的測試目標、測試計畫及實際執行內容。
  • 測試確實執行，但跨框架斷言的報告不如預期：回到呼叫位置與互操作模式核對。
  • 只有 UI 測試與單元測試結果不同：確認兩者是否屬於不同測試目標或執行路徑；不需要因此延伸成全面比較兩種測試框架。

這個分流能避免常見的錯誤修法：把專案設定或建置失敗誤診為 XCTest 與 Swift Testing 不相容，接著大幅重寫本來沒有問題的測試。

第五步：用最小案例驗證修正

完成設定核對後，先不要直接用整份課程專案判斷修復成效。建立或挑選一組範圍清楚的測試：一個預期成功，另一個能穩定觸發預期失敗；如果問題和跨框架斷言有關，測試中要保留相同的呼叫方向。

驗證時逐項勾選：

  • [ ] 記錄工具鏈版本與測試目標。
  • [ ] 記錄 Package 的 swift-tools-version。
  • [ ] 記錄互操作模式，以及設定它的位置。
  • [ ] 保留觸發問題的斷言與呼叫路徑。
  • [ ] 比較修改前後的測試結果與完整診斷。
  • [ ] 確認成功案例仍成功，預期失敗案例也能以可辨認的方式回報。
  • [ ] 用相同專案與設定重新執行，確認結果可以重現。

若修改模式只讓畫面上的紅色消失，卻沒有改變測試是否執行或錯誤是否可辨認，就不能視為修復完成。反之，若最小案例結果正常而課程專案仍異常，應回頭檢查其他測試目標、共用輔助函式及專案設定，而不是繼續調低互操作檢查。

沒有可用的 Xcode 環境時，先確認作業要求

Swift 6.4 的互操作排查需要能執行相關測試的 Apple 開發環境。若目前只能使用學校限制安裝軟體的電腦，或手邊沒有可執行 Xcode 專案的 Mac，反覆改寫測試並不能補足驗收環境。自行購買 Mac 能長期使用，但對只想完成課程測試或短期驗證的學生，前期支出可能不划算；一般虛擬環境也不能直接取代真實 macOS 上的 Xcode 測試。

若問題主要是暫時缺少可用的 Mac 測試環境，可先查看 RUVCLOUD 的Mac 使用方案及方案與費用說明，比較學校設備、自己的 Mac 與遠端 Mac 是否符合課程要求。租用遠端 Mac 並不適合所有情況：若需要長期穩定重載，或作業必須直接連接實體裝置與介面，應先確認設備和使用方式是否符合要求；若只是短期執行 Xcode、重現測試報告並完成驗收，則可把租用 RUVCLOUD 的 Mac 納入比較，省去先購買實機的決策。