FreeBSD Test Suit 介紹

目標: 了解 FreeBSD kernel and usearspace tool 的測試環境

FreeBSD 針對測試有測自己一個 project，Test Suite project。使用的框架為 Kyua，而測試自己本身，可以使用多個語言編寫，像是 C, C++ and Shell 等，FreeBSD 建議使用 GitHub: jmmv/atf: Automated Testing Framework (ATF), a library collection to write test programs in C, C++ and POSIX shell. 寫測試，此測試框架甚至已經被容納在 FreeBSD Base 之中。

P.S. 注意 Kyua 為 Run test 的框架 (Runtime engine)，而 ATF 則是寫測試本身使用的框架，你也可以用別的框架來寫測試本身，但建議使用 ATF。
FreeBSD 自己也有做個 Online CI service for intergration testing，使用 Jenkins。
Tests can be written as shell scripts or as C (or C++) code — which one is best depends on what is being tested. Usually the shell version (‘man 3 atf-sh‘) is best suited to test entire applications and the C/C++ version (‘man 3 atf-c, man 3 atf-c++‘) is best suited when testing libraries or (kernel) APIs. — article

Kyua

FreeBSD 的測試套件跟 NetBSD 的測試套件極為相似，甚至 FreeBSD 的目標就是最小化與 NetBSD 測試套件的差異，NetBSD 對於 Kyua 的文件非常詳細。

Kyua 能在測試完後提供一個 matrix，描述哪些測試案例成功、失敗，產生 log 檔，也可以在測試案例失效時傳電子郵件給開發者等。

最簡單的使用方式

$ pkg install kyua # this can be skipped on FreeBSD CURRENT after 23 March 2020 
$ kyua test -k /usr/tests/Kyuafile

測試被放在 /usr/tests 下，Kyua 對每層目錄的測試都用 Kyuafile 來描述相關測試，上面的 /usr/tests/Kyuafile 就是最頂層的那個 Kyuafile，所以那個 command 會把所有在 /ust/tsets/ 下的所有測試都跑過一遍。

常見的操作

$ kyua list -v # 列出現在目錄底下測試的訊息 (透過 Kyuafile)

$ kyua report --verbose --results-file=$path # 每個 kyua test 會產生一個 .db file，可以透過在最後面的 example 放入那個 .db file 的 path，查看此 .db file 詳細內容
# Ex: kyua report --verbose --results-file=/home/kola/.kyua/store/results.usr_tests_bin_pwd.20230618-060809-843688.db
# https://man.freebsd.org/cgi/man.cgi?query=kyua-report&sektion=1&apropos=0&manpath=FreeBSD+13.2-RELEASE+and+Ports

TestSuite/Structure

事實上，在 /src/tools/regression/ 下有另外一個測試，他主要是放 regression test，是比較大的測試案例，而我們現在的測試主要在 /usr/tests/ 下，這些舊的 regression test 其實因該被整合到 /usr/tests/ 下。

先對測試做一些定義，test = test case: 只測試一種行為的測試，像是一個 function，計算機的加法等。這邊會有兩種類型的測試 1. CHKECKS，遇到錯誤繼續 run 下一個測試的測試 2. REQUIRES，遇到錯誤直接停下來的測試，當你知道遇到錯誤後，後面的動作都沒有意義時就要寫這種測試。

test program: 多個 test case 的集合，他們都是對某個概念或者某個 src code 的 test case，a binary file。
test program 有兩種類型，Plain test program and ATF-based test program (使用 ATF 的測試)，前者只能實做一個 test case，而 ATF 顯然更有擴充性，並且提供多個 API 使用，因此請編寫後者類型的測試。

ATF 介紹

1. head，放置一些 meta-data 屬性，像是測試案例的描述，也可以為這個測試案例增加了特殊的屬性，像是只有 root 的權限能執行此測試，或是只有在某個文件存在的情況下才能執行此 test，因此可以說是 head 的條件滿足下，才可以執行 body 的測試。
2. body，測試案例本身，執行任意的 code，並且調用特殊的 ATF function 來報錯，可以參考 FreeBSD man page。
3. cleanup，總是在 body 之後執行，負責把測試中間產生的東西進行清理，Optional。

每個測試案例是獨立的，不會互相傳狀態，並且避免測試案例影響其他檔案，測試案例會把自己所在的目錄變成 tmp 目錄，執行完測試案例後自動清理這個 tmp 目錄。

Structure

回到介紹測試本身的結構，測試放在 usr/tests/ 下面，並且要按照 src 目錄的排列，像是有關 cp 指令的測試就要放在這邊。
Ex /usr/src/bin/cp/ -> /usr/tests/bin/cp/

每層測試目錄中都會有 Kyuafile，他描述此目錄下的測試程式，並且子目錄也可能會有測試程式，子目錄也就會有 Kyuafile，我們就可以在現在目錄的 Kyuailfe 引用子目錄下的 Kyuafile。

而事實上在最上層的 Kyuafile (/usr/tests/Kyuafile 或者 /usr/tests/bin/Kyuafile … 等相同層面的 Kyuafile，原本是放在 /usr/src/tests/Kyuafile)，它會自動引入不只子目錄的 Kyuafiles，而是 */Kyuafiles，比較特別一點。

並且重要的，我們 /usr/tests/ 是從 /usr/src/ build 出來的，我們並不會在 /usr/tests/ 加入新的程式，因為他在最初的系統並不存在。

/usr/src/tests/Makefile 就是負責安裝所有 Kyuafile 的檔案，所以在寫新的測試時不需要編寫 Kyuafile。

而測試相關的程式是放在對應 source code 的目錄，像是我們要找有關 libcrypt 的測試程式，就是放在 /usr/src/lib/libcrypt/tests/ 下面。此 tests 目錄是由 /usr/src/lib/libcrypt/Makefil 負責創建。

而 /usr/src/lib/libcrypt/tests/Makefile 則負責創建 /usr/tests/lib/libcrypt 目錄。

針對如何創建測試程式，可以參考此 Repo，是用英文寫的。

此文章大部份內容來自 FreeBSD TestSuite Structure, Automated Testing Framework and ATF-TEST-CASE(4)，歡迎前去看原文。