完整說明測試執行環境。
背景
Bazel BUILD 語言包含可用來定義自動化動作的規則 測試計劃。
測試是使用 bazel test
執行。
使用者也可以直接執行測試二進位檔。我們允許這類行為,但不得背書。 因此叫用時不會遵循下述規定。
測試應是「遺傳性」:也就是說,測試只要求存取這些資源 而且已宣告依附元件如果測試的語意不恰當 則無法在過去提供可重現的結果這可以是 找出違規的重大問題 (判斷哪個變更導致測試失敗) 發布工程的可稽核性,以及測試資源隔離 (自動化 由於某些測試 資料)。
目標
本頁面的目標是正式建立執行階段環境, Bazel 測試的預期行為這個瀏覽器也會對測試施加要求 執行器和建構系統
測試環境規格有助於測試作者避免依賴 因此讓測試基礎架構更有餘裕 進行導入變更規格加緊 即使系統測試不夠單純 確定性及重新利用
以下為規範及公信力的參考網頁。如果這是 測試執行工具的實際規格和實作行為不一致, 會優先採用其他規格
提出的規格
下列關鍵字:「必須」、「不得」、「必要」、「應」、「不應」、「應該」、「應該」、 「不應該」、「建議」、「可能」和「選用」會被解讀為 如 IETF RFC 2119 中所述。
測試目的
Bazel 測試的目的是要確認來源檔案的某些屬性 登錄到存放區(在這個頁面上,「來源檔案」包含測試資料、 以及由版本管控的所有其他項目)。一位使用者 測試來斷言要維持的不變數。其他使用者 稍後執行測試,檢查不變量是否損毀。如果 測試取決於來源檔案 (非密封) 以外的任何變數,其值 測試停止通過時。
因此,測試結果只能根據下列項目:
- 測試已宣告依附元件的來源檔案
- 測試中已宣告依附元件的建構系統產品
- 測試執行器保證執行哪些資源行為會維持不變
我們目前並未強制執行這類行為。不過,測試執行工具會保留 。
建構系統的角色
測試規則類似於二進位規則,每個規則都必須產生執行檔 計畫。針對部分語言,這項虛設常式程式結合了 透過測試程式碼建立特定語言專屬的整合介面。測試規則必須產生其他 輸出內容除了主要測試執行檔外,測試執行工具 就需要「runfiles」runfiles資訊清單,也就是應可供使用的輸入檔案 執行測試,而且可能需要類型、大小和 測試的標記。
建構系統可能會使用執行檔案來提供程式碼和資料。(這 可用於最佳化作業,讓每個測試二進位檔 檔案進行追蹤,例如使用動態連結。建構系統 即可確保產生的執行檔透過執行檔載入這些檔案 測試執行器提供的映像檔,而非以硬式編碼參照 位於來源或輸出樹狀結構中的位置
測試執行工具的角色
從測試執行工具的角度來看,每項測試都是一個程式
透過 execve()
叫用。可能還有其他執行測試的方法。例如
IDE 可能會允許在過程中執行 Java 測試。不過,結果
以獨立程序執行測試,必須視為具有權威性。如果
測試程序會執行到完成,並正常終止,並顯示結束代碼
零,測試已通過任何其他結果均視為測試失敗。於
具體而言,將任何字串 PASS
或 FAIL
寫入 stdout 時,並沒有
對測試執行者的重要性。
如果測試執行時間過長,超過某些資源限制,或測試 跑動器或其他偵測到禁止的行為 則可以選擇終止測試 將執行視為失敗。執行器不得將測試回報為通過 並傳送信號給測試程序或其中的任何子項。
系統會限制整個測試目標,而非個別方法或測試
完成這項設定測試的時間限制取決於
timeout
屬性
至下表:
逾時 | 時間限制 (秒) |
---|---|
short | 60 |
中度 | 300 |
long | 900 |
Eternal | 3600 |
沒有明確指定逾時的測試,會根據
測試的 size
,如下所示:
大小 | 「默示逾時」標籤 |
---|---|
small | short |
媒介 | 中度 |
large | long |
巨大 | Eternal |
「大」沒有明確逾時設定的測試會分配到 900 秒。「媒介」將逾時設為「短」可獲得 60 分 秒內請求驗證碼。
與 timeout
不同,size
會額外決定以下的假設用量高峰:
在本機執行測試時使用的其他資源 (如 RAM),
常見定義。
size
和 timeout
標籤的所有組合皆為合法,因此「龐大」測試
可能會宣告逾時為「短」。我們或許會想做點功課
所以很快
無論逾時,測試都能以任意速度傳回。測試不會受到懲罰 ,但您可能會收到警示: 一般而言,逾時設定會越嚴密,不會造成任何不亮。
您可以使用 --test_timeout
bazel 標記覆寫測試逾時時間。
在已知緩慢的情況下手動執行。
--test_timeout
的值以秒為單位。例如:--test_timeout=120
將測試逾時設為兩分鐘。
建議的測試逾時下限值如下:
逾時 | 最短時間 (秒) |
---|---|
short | 0 |
中度 | 30 |
long | 300 |
Eternal | 900 |
例如「中速」測試在 5.5 秒內完成,請考慮設定 timeout =
"short"
或 size = "small"
。使用邊框 --test_verbose_timeout_warnings
指令列選項會顯示指定大小過大的測試。
系統會根據 請參閱這裡的規格說明。如果 未指定,測試的大小將預設為「中」。
如果測試結束的主要程序,但部分子項仍在執行, 測試執行工具應將執行作業視為成功,並計為成功 偵測失敗情形的依據為從主要程序中觀察到的結束代碼。測試執行工具 可能會終止任何不愉快的程序測試不應以這種方式洩漏程序。
測試資料分割
測試可透過測試資料分割平行處理。詳情請見
--test_sharding_strategy
敬上
和 shard_count
到
啟用測試資料分割。啟用資料分割時,測試執行器會啟動一次
每個資料分割。環境變數 TEST_TOTAL_SHARDS
是資料分割數量,而 TEST_SHARD_INDEX
則是
資料分割索引,從 0 開始。執行器會根據這項資訊來選取哪些測試
,例如採用循環制策略。並非所有測試執行工具都支援
資料分割。如果執行器支援資料分割,則必須建立或更新最後一個
指定的該檔案修改日期
TEST_SHARD_STATUS_FILE
。否則,如果
--incompatible_check_sharding_support
敬上
如果 Bazel 已設定分割,則 Bazel 將無法測試。
初始條件
執行測試時,測試執行器必須建立特定的初始值 條件。
測試執行器必須使用
argv[0]
。這個路徑必須是測試目前目錄的相對路徑
(在執行檔案樹狀結構中,如下所示)。測試執行工具不應傳遞任何
要測試的其他引數,除非使用者明確提出要求。
初始環境區塊應按以下方式組成:
變數 | 值 | 狀態 |
---|---|---|
HOME |
$TEST_TMPDIR 的值 |
建議 |
LANG |
未設定 | 必填 |
LANGUAGE |
未設定 | 必填 |
LC_ALL |
未設定 | 必填 |
LC_COLLATE |
未設定 | 必填 |
LC_CTYPE |
未設定 | 必填 |
LC_MESSAGES |
未設定 | 必填 |
LC_MONETARY |
未設定 | 必填 |
LC_NUMERIC |
未設定 | 必填 |
LC_TIME |
未設定 | 必填 |
LD_LIBRARY_PATH |
以冒號分隔的目錄清單,其中包含共用程式庫 | 選用 |
JAVA_RUNFILES |
$TEST_SRCDIR 的值 |
已淘汰 |
LOGNAME |
$USER 的值 |
必填 |
PATH |
/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin:. |
建議 |
PWD |
$TEST_SRCDIR/workspace-name |
建議 |
SHLVL |
2 |
建議 |
TEST_INFRASTRUCTURE_FAILURE_FILE |
可寫入目錄中私人檔案的絕對路徑 (這個檔案) 應僅用於回報測試過程中的錯誤 而非當成一般的回報機制 測試在這種情況下,測試基礎架構的定義為 或非測試專用的程式庫,但可能導致測試失敗 發生故障第一行是測試基礎架構的名稱 第二個是使用者容易理解的元件 錯誤說明。系統會忽略其他行)。 | 選用 |
TEST_LOGSPLITTER_OUTPUT_FILE |
可寫入目錄中私人檔案的絕對路徑 (用於寫入) LogSplitter protobuffer 記錄) | 選用 |
TEST_PREMATURE_EXIT_FILE |
可寫入目錄中私人檔案的絕對路徑 (用於
接聽到 exit() 的來電) |
選用 |
TEST_RANDOM_SEED |
如果使用 --runs_per_test 選項,
TEST_RANDOM_SEED 已設為 run number
每次測試執行時,從 1 開始。 |
選用 |
TEST_RUN_NUMBER |
如果使用 --runs_per_test 選項,
TEST_RUN_NUMBER 已設為 run number
每次測試執行時,從 1 開始。 |
選用 |
TEST_TARGET |
受測試目標的名稱 | 選用 |
TEST_SIZE |
測試 size |
選用 |
TEST_TIMEOUT |
測試 timeout (以秒為單位) |
選用 |
TEST_SHARD_INDEX |
資料分割索引 (如果使用 sharding ) |
選用 |
TEST_SHARD_STATUS_FILE |
用於表示支援 sharding 的檔案路徑 |
選用 |
TEST_SRCDIR |
執行檔案樹狀結構底層的絕對路徑 | 必填 |
TEST_TOTAL_SHARDS |
總數
shard count 、
如果使用 sharding |
選用 |
TEST_TMPDIR |
私人可寫入目錄的絕對路徑 | 必填 |
TEST_WORKSPACE |
本機存放區的工作區名稱 | 選用 |
TEST_UNDECLARED_OUTPUTS_DIR |
私人可寫入目錄的絕對路徑 (用來寫入未宣告的
測試輸出內容)。寫入
將壓縮 TEST_UNDECLARED_OUTPUTS_DIR 目錄,
已新增至以下位置的 outputs.zip 檔案中:
bazel-testlogs 。 |
選用 |
TEST_UNDECLARED_OUTPUTS_ANNOTATIONS_DIR |
私人可寫入目錄的絕對路徑 (用來寫入未宣告的
測試輸出註解 .part 和 .pb 檔案)。 |
選用 |
TEST_WARNINGS_OUTPUT_FILE |
可寫入目錄中私人檔案的絕對路徑 (用於寫入) 測試目標警告) | 選用 |
TESTBRIDGE_TEST_ONLY |
值
--test_filter 、
(如有指定) |
選用 |
TZ |
UTC |
必填 |
USER |
getpwuid(getuid())->pw_name 的值 |
必填 |
XML_OUTPUT_FILE |
測試動作應寫入測試結果 XML 輸出檔案的位置。 否則 Bazel 會產生預設 XML 輸出檔案,並納入測試記錄 做為測試動作的一部分XML 架構是以 JUnit 測試結果結構定義。 | 選用 |
BAZEL_TEST |
表示測試執行檔是由 bazel test 驅動 |
必填 |
環境可能包含其他項目。測試不應仰賴 是否存在、不存在或上述任何環境變數的值。
初始工作目錄應為 $TEST_SRCDIR/$TEST_WORKSPACE
。
目前程序 ID、程序群組 ID、工作階段 ID 和父項程序 ID 為 未指定。這項程序不一定是程序組長或課程負責人 領先傳輸程序不一定有控制終端機,這項程序可能需要 沒有任何執行中或未重新啟動的子項程序。這項程序不應 當測試程式碼取得控制時,會有多個執行緒。
檔案描述元 0 (stdin
) 應開放讀取,但附加內容
未指定,測試不得讀取。檔案描述元 1 (stdout
) 和 2
(stderr
) 允許書寫,但附加內容為
未指定。這些位置可以是終端機、管線、一般檔案等等
哪些字元可以寫入他們可能會共用開啟的檔案表格項目
(這代表他們無法單獨跳轉)。測試不應沿用任何
其他開啟的檔案描述元
初始遮罩應為 022
或 027
。
不會顯示鬧鐘或間隔計時器。
已封鎖信號的初始遮罩為空白。所有信號應設為 他們的預設動作。
初始資源限制 (嚴格和硬性) 應設定如下:
資源 | 限制 |
---|---|
RLIMIT_AS |
無限制 |
RLIMIT_CORE |
未指定 |
RLIMIT_CPU |
無限制 |
RLIMIT_DATA |
無限制 |
RLIMIT_FSIZE |
無限制 |
RLIMIT_LOCKS |
無限制 |
RLIMIT_MEMLOCK |
無限制 |
RLIMIT_MSGQUEUE |
未指定 |
RLIMIT_NICE |
未指定 |
RLIMIT_NOFILE |
至少 1024 年 |
RLIMIT_NPROC |
未指定 |
RLIMIT_RSS |
無限制 |
RLIMIT_RTPRIO |
未指定 |
RLIMIT_SIGPENDING |
未指定 |
RLIMIT_STACK |
無限制,或 2044KB <= rlim <= 8192KB |
初始處理時間 (由 times()
傳回) 和資源使用率
(由 getrusage()
傳回) 未指定。
未指定初始排程政策和優先順序。
主機系統的角色
除了可直接控制測試的使用者情境之外, 執行測試的作業系統必須滿足 測試執行作業的屬性。
檔案系統
測試觀察到的根目錄不一定是真正的根目錄。
應掛接「/proc
」。
所有建構工具都必須位於以下項目所使用 /usr
下的絕對路徑
本機安裝。
可能無法提供以 /home
開頭的路徑。測試不應存取任何
這類路徑
/tmp
應可寫入,但測試應避免使用這些路徑。
測試不得假設任何常數路徑可用做為獨有 相關單位會如何運用資料,並讓他們覺得自己 獲得充分告知,且能夠針對該使用方式表示同意
測試不得假設任何已掛接的檔案系統已啟用時間。
使用者和群組
使用者的 root、無人和 unittest 必須存在。群組的根、無人和 eng 必須存在。
測試必須以非超級使用者的身分執行。真正有效的使用者 ID 必須 等於;同樣適用於群組 ID除此之外,目前使用者 ID、群組 ID 未指定使用者名稱和群組名稱。補充群組 ID 為 未指定。
目前使用者 ID 和群組 ID 必須有相應的名稱,可用於
使用 getpwuid()
和 getgrgid()
擷取。有些時間
其他補充群組 ID
目前的使用者必須擁有主目錄。可能無法寫入。測試必須 卻無法寫入資料
網路
未指定主機名稱。不一定包含點。解決 主機名稱必須提供目前主機的 IP 位址。解析主機名稱剪下 每個點後面也必須正常運作主機名稱 localhost 必須解析。
其他資源
測試至少會獲得一個 CPU 核心。其他供應商或許會開放,但你無法 保證。未指定這個核心的其他效能層面。你可以 新增標記,將預留項目增加到更多的 CPU 核心 "cpu:n"(其中 n 為正數) 加到測試規則。如果機器的規模 CPU 核心總數超過所要求的總數,Bazel 仍會執行測試。如果測試使用 資料分割,每個資料分割都會保留 CPU 數量 這裡指定了核心
測試可能會建立子程序,但無法處理群組或工作階段。
系統對測試可耗用的輸入檔案有數量限制,此限制為 可能會有所變動,但目前在數萬個輸入資料範圍內。
時間與日期
未指定目前的時間和日期。未指定系統時區。
X Windows 不一定會推出。需要 X 伺服器的測試應啟動 Xvfb。
測試與檔案系統的互動
在測試環境變數中指定的所有檔案路徑都指向 本機檔案系統。
測試只能在
$TEST_TMPDIR
和 $TEST_UNDECLARED_OUTPUTS_DIR
(如有設定)。
這些目錄一開始是空的。
測試不得嘗試移除、chmod 或以其他方式更改這些目錄。
這些目錄可能是符號連結。
未指定「$TEST_TMPDIR/.
」的檔案系統類型。
測試也可能會將 .part 檔案寫入
$TEST_UNDECLARED_OUTPUTS_ANNOTATIONS_DIR
用於為未宣告的輸出檔案加上註解。
在極少數情況下,系統可能會強制在 /tmp
中建立檔案。例如:
Unix 網域通訊端的路徑長度限制
通常需要在 /tmp
下建立通訊端。Bazel 將無法
追蹤這類檔案;測試時必須注意保持美觀
避免彼此衝突,同時執行測試和非測試
處理及清理在 /tmp
中建立的檔案。
一些常用的測試架構,例如
JUnit4 TemporaryFolder
或 前往 TempDir
並自己的方法在 /tmp
下建立暫存目錄。這些測試
架構包含清理 /tmp
檔案的功能,因此您可以使用
即使他們在 TEST_TMPDIR
之外建立檔案也一樣。
測試必須透過 runfiles 機制, 專門用來產生輸入檔案的執行環境 廣告。
測試不得存取以推斷出的路徑推斷的建構系統的其他輸出內容 自己執行檔的位置
未指定執行檔案樹狀結構是否包含一般檔案,
或混合使用執行檔案樹狀結構可能包含指向目錄的符號連結。
測試應避免在執行檔案中使用含有 ..
元件的路徑
。
在執行檔案樹狀結構中不得有目錄、檔案或符號連結 (包括
反向符號連結) 必須可寫入。
目錄不應寫入)測試不得假設
執行檔可寫入,或由目前使用者擁有 (例如,chmod
和 chgrp
可能會
失敗)。
執行檔案樹狀結構 (包括週遊符號連結的路徑) 不得變更 測試執行期間父項目錄和檔案系統掛接不得變更 以任何方式影響執行檔案內解析路徑的結果 。
為了掌握早期離開事件,測試會在
TEST_PREMATURE_EXIT_FILE
啟動,並在退出時移除。如果 Bazel 發現
檔案進行測試時,會假設測試提早結束,
並標示為作業失敗
代碼慣例
測試規則中的部分代碼具有特殊意義。另請參閱
依據 tags
屬性 Bazel 建構百科全書。
標記 | 意義 |
---|---|
exclusive |
無法同時執行其他測試 |
external |
具有外部依附元件停用測試快取 |
large |
test_suite 慣例;大型測試套件 |
manual * |
不在萬用字元目標模式 (例如
:... 、:* 或:all |
medium |
test_suite 慣例;中等測試套件 |
small |
test_suite 慣例;一系列小型測試套件 |
smoke |
test_suite 慣例;表示應在 Pod 執行
將程式碼變更提交到版本管控系統 |
執行檔案
接下來,假設有一個 *_binary() 規則
//foo/bar:unittest
,且執行時間依附於已加上標籤的規則
//deps/server:server
。
位置
目標 //foo/bar:unittest
的執行檔案目錄是目錄
$(WORKSPACE)/$(BINDIR)/foo/bar/unittest.runfiles
。這個路徑稱為
runfiles_dir
。
依附元件
runfiles 目錄會宣告為
*_binary()
規則。執行檔案目錄本身取決於 BUILD 的集合
影響 *_binary()
規則或其任何編譯時間或執行階段的檔案
依附元件修改來源檔案不會影響
因此不會觸發任何重新建構。
目錄
runfiles 目錄包含以下內容:
- 用於執行時間依附元件的 Symlink:每個 OutputFile 和 CommandRule
是
*_binary()
規則的執行階段依附元件 。符號連結的名稱是$(WORKSPACE)/package_name/rule_name
。例如,伺服器的符號連結 名稱會是$(WORKSPACE)/deps/server/server
,完整路徑會是$(WORKSPACE)/foo/bar/unittest.runfiles/$(WORKSPACE)/deps/server/server
。 符號連結的目的地是 OutputFile 的 OutputFileName() CommandRule,以絕對路徑表示。因此,目標運算的目的地 符號連結可能是$(WORKSPACE)/linux-dbg/deps/server/42/server
。 - 子執行檔案的連結:每個屬於執行階段的
*_binary()
Z*_binary()
C 的依附元件,執行檔案內包含第二個連結 C 的目錄套用至 Z 的執行檔案。符號連結的名稱是$(WORKSPACE)/package_name/rule_name.runfiles
。符號連結的目標為 執行該檔案舉例來說,所有子程式會共用一個常見的執行檔 目錄。