判定與結束摘要

前面「基礎 1」已經先用過一次 check()。這一頁把它跟 fail() 一起講完整，並說明腳本結束時那一行摘要在講什麼，以及批次模式怎麼從 Exit Code 判斷這次跑的是通過還是失敗。

`check(條件 [, 說明])`：記一次判定，不管過或不過都繼續


check(1 + 1 == 2, "1 + 1 == 2")            -- 條件成立
check(1 + 1 == 3, "deliberately wrong")    -- 條件不成立

check() 每叫一次就記一筆：條件成立寫 CHECK OK: <說明>，不成立寫 CHECK FAIL: <說明>。不論過或不過，腳本都會繼續往下執行——這是它跟 fail() 最大的差別。說明 省略時固定寫 "check"。

腳本裡呼叫過幾次 check()、其中幾次失敗，程式都會記著，等腳本執行完再一起算進下面的結束摘要。這個計數是每次執行重新歸零的，不會累積到下一次執行。

`fail([說明])`：記一次失敗，並立刻結束腳本


fail("device did not respond")   -- 印一行 FAIL: ...，腳本到這裡就結束，不會再往下走

跟 check() 不同，fail() 叫下去之後，後面的程式碼不會再執行——用在遇到「已經確定不用再繼續測下去」的情況（例如裝置完全沒回應），比起讓腳本硬跑到最後、留一堆看起來莫名其妙的後續失敗，直接在這裡停下來更清楚。

結束時的摘要

不管腳本裡有沒有 check()／fail()，腳本結束時 Log 都會多寫最後一行摘要，說明這次跑的結果：

結果	摘要行
全部 `check()` 都過，也沒有任何錯誤	`Script PASSED (<次數> checks): <路徑>`
有 `check()` 沒過（或呼叫了 `fail()`）	`Script FAILED (<失敗次數> of <總次數> checks failed): <路徑>`
腳本本身出錯（找不到檔案、語法錯誤、呼叫到一半丟出非 `fail()` 的錯誤）	`Script INCOMPLETE (rc=<代碼>): <路徑>`
執行中被使用者中止	`Script ABORTED: <路徑>`

範例：一個成立、一個刻意寫錯

check_pass_fail.lua下載 check_pass_fail.lua

-- expect-rc: -64
-- 展示 check()／fail() 與失敗時的結束摘要（本範例刻意示範失敗）。
check(1 + 1 == 2, "1 + 1 == 2")
check(1 + 1 == 3, "deliberately wrong: 1 + 1 == 3")
log("info", "check_pass_fail done")

預期輸出

CHECK OK: 1 + 1 == 2
CHECK FAIL: deliberately wrong: 1 + 1 == 3
check_pass_fail done

這支範例故意讓第二個 check() 失敗。跟「第一次跑腳本」一樣用完整路徑跑：


nexus_tui.exe --dongle mock --batch --run C:\lua\check_pass_fail.lua

畫面上完整看到的內容大概是這樣（比「預期輸出」多出開始、結束兩行摘要，見「第一次跑腳本」的「預期輸出是什麼」一節）：


Script start: C:\lua\check_pass_fail.lua
CHECK OK: 1 + 1 == 2
CHECK FAIL: deliberately wrong: 1 + 1 == 3
check_pass_fail done
Script FAILED (1 of 2 checks failed): C:\lua\check_pass_fail.lua
nexus_tui: script 'C:\lua\check_pass_fail.lua' failed: rc=-64 (see log)

最後一行 nexus_tui: script '...' failed: rc=-64 (see log) 是批次模式額外印在 stderr 的一行（互動模式沒有這行，只有 Log 裡的摘要）；rc=-64 就是下一節表格裡「有 check() 沒過」對應的內部代碼。

Exit Code 對照表

批次模式（--batch）結束時的 Exit Code，就是拿來判斷「這次跑產線／CI 算不算過」用的。跟腳本本身的判定直接相關的兩個數字：

情況	Exit Code
全部判定都過	`0`
有 `check()` 沒過，或呼叫了 `fail()`	`64`

只有這兩個數字代表腳本真的完整跑完、給出了一個判定結果。 其餘任何數字都代表這次沒有一個完整的判定——常見的還有：找不到腳本檔案是 7；腳本本身出錯（語法錯誤，或執行到一半遇到非 fail() 的錯誤，這也包含硬體沒回應這類執行期錯誤——比對裝置沒回應跟語法寫錯，回報的是同一個代碼）是 1；執行中被中止（Ctrl+C）是 62；--cmd 想偷跑 run 被拒絕（見下一頁）是 2；程式偵測到同一台機器已經有一份在跑（常見於產線電腦上一份還沒關就又啟動一次）是 22。 這張表不是全部——重點不是背下每一個數字，而是記住下面這條規則。

⚠ 不要把「非 0、非 64」的 Exit Code 自動當成「重跑就好」：1 除了語法錯誤，也會是裝置真的沒回應（例如 i2c.read() 打了一個沒人在聽的位址）——這種情況重跑一百次結果都一樣，不是暫時性的。看到 0／64 以外的 Exit Code，正確的下一步是去看那次執行的 Log，找出真正的原因，而不是預設它可以重跑解決。下一頁會示範怎麼在 .bat／Python 腳本裡讀這個 Exit Code 做分支。

接下來

下一頁介紹怎麼把 --batch --run 整合進 .bat 或 Python 寫的自動化流程，用剛剛這張表判斷每一次跑的成敗。