完整說明測試執行環境。
背景
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。否則 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_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。符號連結的目標為 執行該檔案舉例來說，所有子程式會共用一個常見的執行檔 目錄。