ClickHouse 無狀態(tài)測試Stateless Tests實戰(zhàn)指南clickhouse-test 的運(yùn)行機(jī)制、常用參數(shù)與用例編寫【免費(fèi)下載鏈接】ClickHouseClickHouse? is a real-time analytics database management system項目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouseClickHouse 的無狀態(tài)測試Stateless Tests是一套面向 SQL 行為回歸驗證的核心測試體系它不依賴預(yù)先灌入的外部數(shù)據(jù)每個測試獨立建臨時庫、執(zhí)行查詢并把標(biāo)準(zhǔn)輸出與.reference期望文件逐字節(jié)比對。本文以倉庫內(nèi).claude/instructions.md記錄的開發(fā)流程為主線結(jié)合 測試運(yùn)行器tests/clickhouse-test的真實源碼系統(tǒng)講解從構(gòu)建、啟動服務(wù)到運(yùn)行、排查 stateless 測試的完整閉環(huán)讀完即可在本倉庫本地環(huán)境復(fù)現(xiàn) CI 同款的功能測試能力。一、Stateless Tests 是什么先理解這套測試的定位在 ClickHouse 倉庫中無狀態(tài)測試用例集中存放在tests/queries/0_stateless/倉庫內(nèi)共有一萬余個測試文件編號如00001_select_1.sql。所謂「無狀態(tài)」指每個用例在運(yùn)行前不依賴任何預(yù)設(shè)的持久化業(yè)務(wù)數(shù)據(jù)——運(yùn)行器會為每次執(zhí)行創(chuàng)建臨時數(shù)據(jù)庫與臨時表測試結(jié)束時環(huán)境即被清空因此用例彼此隔離、可并行、可重復(fù)。執(zhí)行這些用例的統(tǒng)一入口是根目錄下的 Python 運(yùn)行器tests/clickhouse-test倉庫內(nèi)約 7300 行由#!/usr/bin/env python3聲明啟動。它與 CI 中的功能測試任務(wù)如ci/jobs/functional_tests.py共用一套邏輯也就是說你本地跑通的命令就是 CI 里 stateless 任務(wù)實際執(zhí)行的核心流程。二、運(yùn)行前置條件構(gòu)建、啟動服務(wù)與就緒探測.claude/instructions.md給出了最簡三段式準(zhǔn)備流程每一步都有明確目的# 1. 構(gòu)建 ClickHouse 服務(wù)端與客戶端二進(jìn)制 cd build ninja clickhouse # 2. 用倉庫自帶的服務(wù)端配置啟動服務(wù) ./build/programs/clickhouse server --config-file ./programs/server/config.xml # 3. 用一次最小查詢探測服務(wù)是否就緒 ./build/programs/clickhouse client -q SELECT 1第 1 步假設(shè)build/目錄已完成 CMake 配置全新檢出時需要先執(zhí)行cmake -S . -B build ...之類的一次性配置之后每次增量構(gòu)建只需ninja clickhouse。第 2 步加載的配置文件programs/server/config.xml即發(fā)行版默認(rèn)服務(wù)端配置。按該文檔說明默認(rèn)監(jiān)聽 TCP 端口為9000原生客戶端協(xié)議、HTTP 端口為8123HTTP 接口——這兩個默認(rèn)值隨后會與測試運(yùn)行時的端口環(huán)境變量嚴(yán)格對應(yīng)是很多「測試連不上服務(wù)」問題的根因。測試場景下更貼近 CI 的另一種做法是使用tests/config/目錄下的專用測試配置但本地快速驗證時直接使用programs/server/config.xml即可。第 3 步的client -q SELECT 1本質(zhì)是一次就緒探針liveness probe只有服務(wù)端完成表加載、能接受查詢后客戶端才會返回結(jié)果并正常退出此時才能開始跑測試。三、運(yùn)行測試端口環(huán)境變量為何必須設(shè)置運(yùn)行器通過以下命令執(zhí)行測試測試名可傳目錄名或單個用例名CLICKHOUSE_PORT_TCP9000 CLICKHOUSE_PORT_HTTP8123 ./tests/clickhouse-test test_name兩個環(huán)境變量的作用可在 tests/clickhouse-test 中得到印證。運(yùn)行器啟動時會讀取它們并寫入客戶端連接配置相關(guān)代碼位于該文件約 L3829-L3863 與 L7204-L7221若未通過環(huán)境變量顯式指定運(yùn)行器會回退到命令行參數(shù)--tcp-port/--http-port的邏輯。除基本兩件套外源碼中還支持CLICKHOUSE_PORT_TCP_SECURE、CLICKHOUSE_PORT_HTTPS、CLICKHOUSE_PORT_HTTP_PROTO用于把 HTTP 切到https等加密通道變量——當(dāng)使用 TLS 服務(wù)配置時可據(jù)此補(bǔ)齊。值得注意的細(xì)節(jié)是如果手動修改了服務(wù)端監(jiān)聽端口卻沒有同步設(shè)置環(huán)境變量運(yùn)行器會按默認(rèn)值9000/8123探測導(dǎo)致「服務(wù)明明在跑卻全部超時」。因此實踐上建議把端口統(tǒng)一收斂到上述默認(rèn)值或在命令行顯式覆蓋例如./tests/clickhouse-test -- --help # 查看運(yùn)行器全部選項 CLICKHOUSE_PORT_TCP9001 ./tests/clickhouse-test 00001_select_1 # 端口與默認(rèn)不同時四、常用 Flags 速查與源碼依據(jù).claude/instructions.md重點介紹三個在本地調(diào)試與 CI 排障中最高頻的選項它們都實現(xiàn)在 tests/clickhouse-test 的參數(shù)解析段約 L6680-L6760Flag作用典型使用場景--no-random-settings禁用「隨機(jī)化 settings」機(jī)制排除某個SET隨機(jī)值恰好觸發(fā)失敗的干擾做確定性復(fù)現(xiàn)--no-random-merge-tree-settings禁用 MergeTree 表引擎相關(guān)設(shè)置的隨機(jī)化排查 MergeTree 行為差異或配合隨機(jī)化診斷定位問題--recordstdout 與期望不一致時自動把 stdout 寫回.reference文件驗證行為變更后批量刷新期望輸出關(guān)鍵提醒--record的副作用源碼在 L7104-L7109 處特意注明——開啟--record時運(yùn)行器會禁用引擎替換engine replacement以確保錄制的.reference是測試原始輸出。這意味著你錄下來的結(jié)果可能與開啟了Replicated引擎替換等「云模式改寫」的 CI 環(huán)境不一致。因此--record更適合本地比對、確認(rèn)新輸出符合預(yù)期后再由開發(fā)者審閱提交而非盲目全量刷新。除文檔點名的三個選項外從同一段參數(shù)解析代碼還能看到運(yùn)行器還支持--skip跳過指定測試、--no-stateful關(guān)閉有狀態(tài)測試、--no-long跳過long標(biāo)簽用例、--sequential、--client-option追加客戶端參數(shù)、--s3-storage/--azure-blob-storage在對象存儲后端上跑、--distributed-cache以及一組用于復(fù)現(xiàn)隨機(jī)化失敗的--random-settings-diagnostics-dir/--diagnose-random-settings。本地調(diào)試建議組合使用CLICKHOUSE_PORT_TCP9000 CLICKHOUSE_PORT_HTTP8123 \ ./tests/clickhouse-test 00001_select_1 \ --no-random-settings --no-random-merge-tree-settings五、測試文件擴(kuò)展名生態(tài)與.reference比對機(jī)制Stateless 測試不止是.sql。.claude/instructions.md歸納了完整的文件類型體系倉庫中這些類型都能在tests/queries/0_stateless/中實際找到對應(yīng)文件擴(kuò)展名含義.sql最常用的純 SQL 測試.sql.j2基于 Jinja2 模板的 SQL 測試可參數(shù)化渲染后執(zhí)行.shShell 腳本型測試用于需要外部進(jìn)程配合的場景.pyPython 測試.expectExpect 腳本測試交互式會話驅(qū)動.reference期望輸出文件測試 stdout 與之逐字節(jié)比對.gen.reference.j2模板測試運(yùn)行前生成的期望文件運(yùn)行器的核心判定邏輯是執(zhí)行用例后捕獲 stdout/stderr與同目錄同名.reference做 diff不一致即失敗。一個最樸素的用例是tests/queries/0_stateless/00001_select_1.sql內(nèi)容僅SELECT 1其對應(yīng)期望文件即00001_select_1.reference。同時普通 SQL 測試還會用到行內(nèi)錯誤斷言注釋。例如 tests/queries/0_stateless/00002_system_numbers.sql 中select x from system.numbers limit 1; -- { serverError UNKNOWN_IDENTIFIER }表示該語句期望拋錯且錯誤碼必須是UNKNOWN_IDENTIFIER——這類注釋同樣會被運(yùn)行器解析并參與結(jié)果判定是編寫「驗證報錯行為」用例的基礎(chǔ)語法。六、數(shù)據(jù)庫名歸一化.reference里為什么必須寫default這是 stateless 測試最容易踩坑、也最容易被誤解的機(jī)制。.claude/instructions.md明確指出運(yùn)行器會為每個測試創(chuàng)建名字隨機(jī)的一次性臨時數(shù)據(jù)庫形如test_abc123以便并行執(zhí)行時互不干擾而執(zhí)行結(jié)束后運(yùn)行器在比對前會把 stdout/stderr 中出現(xiàn)該隨機(jī)庫名的位置統(tǒng)一替換成default再與.reference比較。這一行為在 tests/clickhouse-test 中有直接代碼佐證測試輸出文件經(jīng)由 L3816-L3818 的replace_in_file(self.stdout_file, database, default)stderr 同理完成歸一化而隨機(jī)庫名會通過環(huán)境變量CLICKHOUSE_DATABASE見 L2305、L2334與--param_CLICKHOUSE_DATABASE見 L3745-L3750注入執(zhí)行環(huán)境。由此得出一個硬性規(guī)則編寫或修改.reference時庫名一律寫成default絕不能寫${CLICKHOUSE_DATABASE}或某個真實隨機(jī)名——否則歸一化前后永遠(yuǎn)對不上用例必然誤報失敗。同理期望輸出里也不要依賴任何與隨機(jī)庫相關(guān)的副作用。七、Tags用首行注釋控制用例執(zhí)行策略用例可以通過文件內(nèi)首行注釋打標(biāo)簽聲明自身的行為約束語法為-- Tags: no-fasttest, no-parallel運(yùn)行器在 read_test_tags_and_random_settings_limits 附近解析這些標(biāo)簽前綴Tags:并在調(diào)度與隨機(jī)化階段消費(fèi)它們。常見標(biāo)簽及含義如下Tag含義disabled用例當(dāng)前被禁用不參與執(zhí)行no-fasttest不進(jìn)入 fasttest 快速冒煙集no-parallel該用例禁止與其他用例并行no-random-settings對應(yīng)用例自身要求不參與 settings 隨機(jī)化no-random-merge-tree-settings對應(yīng)用例要求不參與 MergeTree 設(shè)置隨機(jī)化long耗時長的用例配合--no-long可跳過注意標(biāo)簽語義與第三節(jié)全局 flag 的對應(yīng)關(guān)系--no-random-settings是全局關(guān)閉隨機(jī)化而用例上的no-random-settings標(biāo)簽是單測豁免——兩者粒度不同排障時可先看是哪個層級在生效。八、Random settings limits給隨機(jī)化畫上范圍ClickHouse 在 CI 中默認(rèn)會為每個測試隨機(jī)挑選一部分SET參數(shù)如max_threads來擴(kuò)大覆蓋、暴露競態(tài)代價是結(jié)果不穩(wěn)定。為了既保留隨機(jī)化、又約束到合理范圍.claude/instructions.md給出了行級限制注釋的寫法-- Random settings limits: max_threads(1, 4); max_block_size(100, 1000)運(yùn)行器按分號拆分每條限制、用 Pythonliteral_eval風(fēng)格解析(min, max)元組再在生成隨機(jī)值時把對應(yīng) setting 鉗制在該閉區(qū)間內(nèi)核心邏輯見 parse_random_settings_limits_from_line 與 apply_random_settings_limits。典型應(yīng)用是某用例在max_threads取大值時偶發(fā)失敗你既不想全局關(guān)掉隨機(jī)化又需要鎖定線程數(shù)做復(fù)現(xiàn)這時就在文件里聲明max_threads(1, 4)之類的小范圍。九、收尾如何正確停止服務(wù)本地調(diào)試結(jié)束后.claude/instructions.md建議用進(jìn)程管理命令優(yōu)雅結(jié)束服務(wù)不要在測試運(yùn)行中途直接殺進(jìn)程否則可能殘留臨時表或鎖pgrep -f clickhouse server # 先拿到服務(wù)進(jìn)程 PID 列表 kill pid1 pid2 # 再逐個停止運(yùn)行器本身對進(jìn)程也做了配套設(shè)計例如clickhouse-test開頭L58-L66就提到 CI 側(cè)可用--cleanup清理被SIGKILL打斷后遺留的孤兒進(jìn)程組PID 記錄寫入ci/tmp/clickhouse_test_group_pid.pid。因此在本地多開服務(wù)時務(wù)必用pgrep -f clickhouse server精確匹配、避免誤殺其他實例。十、實踐小結(jié)與延伸閱讀把整條鏈路串起來一次標(biāo)準(zhǔn)化的 stateless 本地調(diào)試流程是# 1. 準(zhǔn)備首次需先 CMake 配置 build 目錄 cd build ninja clickhouse ./build/programs/clickhouse server --config-file ./programs/server/config.xml ./build/programs/clickhouse client -q SELECT 1 # 就緒探測 # 2. 單測 確定性調(diào)試 CLICKHOUSE_PORT_TCP9000 CLICKHOUSE_PORT_HTTP8123 ./tests/clickhouse-test 00001_select_1 \ --no-random-settings --no-random-merge-tree-settings # 3. 結(jié)果異常時審視三處而不是盲改 # - 用例自身-- { serverError ... } 行內(nèi)斷言 # - .reference庫名是否遵守 default 歸一化規(guī)則 # - Tags / Random settings limits 注釋如需繼續(xù)深入可在當(dāng)前倉庫中查看以下材料運(yùn)行器全量邏輯見 tests/clickhouse-test海量真實用例見 tests/queries/0_stateless/進(jìn)程與超時管理的最佳實踐見 tests/clickhouse-test-process-management.mdCI 側(cè)的調(diào)度封裝見 ci/jobs/functional_tests.py。理解本節(jié)第三、六、七部分三個「隱性規(guī)則」端口注入、庫名歸一化、標(biāo)簽粒度就能讓本地調(diào)試行為與 CI 判定保持一致避免「本地過了、CI 紅了」的經(jīng)典困惑?！久赓M(fèi)下載鏈接】ClickHouseClickHouse? is a real-time analytics database management system項目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考