境變量配置實(shí)戰(zhàn)指南)
pytest 跑出幾百條用例之后最難受的往往不是失敗本身而是失敗之后要在一屏一屏的終端輸出里翻找哪一條斷言掛了。這時(shí)候 allure 就會(huì)進(jìn)入視野——它把 pytest 的執(zhí)行結(jié)果渲染成帶步驟、附件、失敗截圖和趨勢(shì)曲線的可視化報(bào)告。但不少人卡在第一步allure 裝不上或者裝上了敲 allure 提示 command not found。這篇就圍繞 pytest 場(chǎng)景下的 allure 安裝與環(huán)境變量配置把 Windows 和 Mac 兩條路完整走一遍包括它背后的 JDK 依賴、PATH 寫法、pytest 側(cè)插件對(duì)接以及那些明明看著是 PATH 問題、表現(xiàn)出來卻像別的問題的典型場(chǎng)景。1. 拆開看 allure 這條鏈路誰(shuí)依賴誰(shuí)先搞清楚再動(dòng)手在動(dòng)手敲命令之前有一件事必須先說明白allure 不是 Python 生態(tài)里的東西它和 pip 沒有半點(diǎn)關(guān)系。很多人第一次搜a(bǔ)llure 安裝看到第一行是pip install allure-pytest裝完就以為搞定了然后在終端里敲allure --version得到一句不是內(nèi)部或外部命令。這個(gè)誤會(huì)幾乎每個(gè)新手都踩過一次把它講清楚后面所有步驟才有邏輯。1.1 allure 命令行是一條獨(dú)立的 Java 工具鏈Allure 命令行版本發(fā)布出來的是一個(gè)壓縮包解壓后大致長(zhǎng)這樣allure-2.27.0/ ├── bin/ │ ├── allure # macOS / Linux 用的 shell 腳本 │ └── allure.bat # Windows 用的批處理 ├── config/ └── lib/ ├── allure-commandline-2.27.0.jar ── ... 一堆依賴 jar這個(gè)結(jié)構(gòu)已經(jīng)說明了它的本質(zhì)一堆 jar 包外面套了一個(gè)啟動(dòng)腳本。allure和allure.bat干的事情其實(shí)很簡(jiǎn)單——找到本機(jī)的 Java 運(yùn)行時(shí)把 lib 目錄下那堆 jar 拼成 classpath然后把命令行參數(shù)原樣透?jìng)鹘o Java 主類。所以它和 Maven、Gradle 是同一類東西屬于JVM 上的命令行工具。這就直接推出了兩個(gè)硬性結(jié)論。第一機(jī)器上必須有能用的 Java 運(yùn)行時(shí)而且版本不能太低Allure 2.x 系列基本要求 Java 8 及以上現(xiàn)在用 11 或 17 更穩(wěn)。第二Java 光裝上還不行必須讓allure.bat或allure腳本能在它自己的執(zhí)行上下文里找到 Java這就涉及到JAVA_HOME或者 PATH 的問題。很多allure 裝了但跑不起來的案例根因其實(shí)在 Java 那一側(cè)而不是 allure 本身。1.2 pytest 側(cè)的 allure-pytest 只負(fù)責(zé)產(chǎn)出原料allure-pytest這個(gè) Python 包的作用非常單一它是一個(gè) pytest 插件通過在用例執(zhí)行的各個(gè)鉤子上打點(diǎn)把測(cè)試結(jié)果寫成一組結(jié)構(gòu)化的 JSON/XML 文件通常落在allure-results目錄里。它完全不負(fù)責(zé)渲染不負(fù)責(zé)啟動(dòng)服務(wù)也不會(huì)給你生成一個(gè)能點(diǎn)開的 HTML 頁(yè)面。也就是說整條鏈路是兩段式的環(huán)節(jié)承擔(dān)者產(chǎn)物采集測(cè)試數(shù)據(jù)allure-pytest插件allure-results/下的一堆 JSON渲染成報(bào)告allure 命令行工具allure-report/靜態(tài)站點(diǎn)或本地服務(wù)搞不清這個(gè)分段就會(huì)出現(xiàn)很典型的困惑我 pip 裝了 allure也跑了 pytest為什么沒有報(bào)告因?yàn)槟阒煌瓿闪说谝欢蔚诙蔚拿钚泄ぞ邏焊鶝]裝。反過來也有我裝了命令行工具allure --version也有輸出為什么 pytest 跑完allure-results是空的那是插件沒裝或者沒通過--alluredir指定輸出目錄。1.3 三類高頻失敗癥狀和對(duì)策完全不同把常見問題歸一下類會(huì)發(fā)現(xiàn)它們雖然都表現(xiàn)為allure 用不了但處理路徑完全不同第一類是命令找不到allure在終端里不被識(shí)別。這是純環(huán)境變量問題PATH 里沒有 allure 的 bin 目錄或者配了但當(dāng)前終端窗口沒重新加載。第二類是命令能找到但執(zhí)行報(bào)錯(cuò)比如提示找不到主類、Java 版本不兼容、JVM 啟動(dòng)失敗。這是 Java 環(huán)境問題JAVA_HOME指向不對(duì)或者指向了一個(gè) JRE 而非完整 JDK。第三類是命令正常、報(bào)告空白或元素缺失比如報(bào)告能打開但一個(gè)用例都沒有或者趨勢(shì)圖永遠(yuǎn)是空的。這通常是觸發(fā)參數(shù)、目錄清理、history 目錄處理的問題跟環(huán)境變量已經(jīng)沒關(guān)系了。下面的內(nèi)容會(huì)按這個(gè)分類依次展開。先說 Windows因?yàn)樗沫h(huán)境變量機(jī)制更顯式也更容易排查。2. Windows 上的完整落地路徑從 JDK 到 PATH 一次性配齊Windows 上配環(huán)境變量的順序很重要先 Java 后 allure因?yàn)?allure 啟動(dòng)腳本會(huì)去讀 Java 相關(guān)的變量。反過來做的話你會(huì)先看到 allure 報(bào)錯(cuò)然后再回頭補(bǔ) Java多繞一圈。2.1 JDK 的選擇與 JAVA_HOME 的正確指向JDK 用什么發(fā)行版其實(shí)無(wú)所謂Temurin原 AdoptOpenJDK、Zulu、微軟的 OpenJDK、Oracle JDK 都行只要版本在 8 以上。安裝時(shí)有個(gè)選項(xiàng)要注意如果要裝多個(gè)版本共存就不要勾選設(shè)置 JAVA_HOME 變量這類選項(xiàng)讓安裝器自己動(dòng)環(huán)境變量反而容易把已有配置覆蓋掉手工配更可控。安裝完成后先開一個(gè)新的 cmd 窗口敲java -version有正常的版本輸出說明 Java 已經(jīng)在 PATH 里了。但這一步不能證明JAVA_HOME是對(duì)的這是兩個(gè)獨(dú)立的東西。接著確認(rèn)JAVA_HOMEecho %JAVA_HOME%正確的結(jié)果應(yīng)該是 JDK 的根目錄類似這樣D:\devtools\jdk-17有兩個(gè)常見的錯(cuò)誤指向要特別提一下。一是把它指向了bin目錄寫成D:\devtools\jdk-17\bin這是錯(cuò)的JAVA_HOME表達(dá)的是JDK 的家在哪不是可執(zhí)行文件在哪。二是把它指向了jre目錄某些 Oracle 安裝包會(huì)單獨(dú)裝一個(gè) JRE 出來指向那里的話如果后續(xù)有什么工具需要編譯相關(guān)的能力就會(huì)出問題。設(shè)置路徑是此電腦右鍵 →屬性→高級(jí)系統(tǒng)設(shè)置→環(huán)境變量。新增一個(gè)用戶變量JAVA_HOME值填 JDK 根目錄。然后找到Path點(diǎn)編輯新增一行%JAVA_HOME%\bin用%JAVA_HOME%這種相對(duì)引用而不是寫死絕對(duì)路徑好處是以后換 JDK 版本只需要改JAVA_HOME一處PATH 不用動(dòng)。這是個(gè)很小的習(xí)慣但在需要多版本切換的團(tuán)隊(duì)里能省不少事。2.2 Path 中最容易被搶占的那一行javapath 的坑這里有個(gè)非常隱蔽的問題值得單獨(dú)講。Windows 上裝了 Oracle JDK 或者某些帶 Java 的軟件之后會(huì)在C:\Program Files\Common Files\Oracle\Java\javapath或者C:\Windows\System32里放一個(gè)java.exe的轉(zhuǎn)發(fā)程序。如果這個(gè)路徑在 PATH 里排在%JAVA_HOME%\bin前面那么java -version顯示的版本就是那個(gè)轉(zhuǎn)發(fā)程序指向的版本而不是你新配的。排查方式是在 cmd 里執(zhí)行where java它會(huì)按 PATH 順序列出所有匹配的java.exe。如果第一行不是你想用的 JDK 下的那個(gè)說明被搶占了。解決方法有兩個(gè)一是把%JAVA_HOME%\bin上移到 PATH 列表頂部二是干脆把那個(gè)干擾項(xiàng)從 PATH 里刪掉。我個(gè)人推薦前者動(dòng)的東西少回滾也容易。注意Windows 的 PATH 是從左到右、先命中先用的查找順序。這不是哪個(gè)最新用哪個(gè)也不是哪個(gè)版本高用哪個(gè)純粹看位置。理解這一點(diǎn)很多我明明改了環(huán)境變量為什么沒生效的疑問就能自己想明白。2.3 解壓 allure 命令行包并配置 ALLURE_HOMEJava 那邊確認(rèn)無(wú)誤之后再去下載 allure 命令行包。取 zip 版本解壓到一個(gè)不含空格、不含中文、不含特殊符號(hào)的目錄。比如D:\devtools\allure-2.27.0為什么不建議放在Program Files或者桌面這種路徑下因?yàn)閍llure.bat內(nèi)部做 classpath 拼接的時(shí)候是把lib目錄下的 jar 一個(gè)個(gè)用分號(hào)連起來的路徑里出現(xiàn)空格如果腳本里的引用沒有全部加引號(hào)實(shí)際上歷史版本的腳本確實(shí)有過這個(gè)問題就會(huì)出現(xiàn) classpath 被空格截?cái)?、?bào)找不到主類的情況。放在D:\devtools這種干凈路徑下一勞永逸省得排查時(shí)還要懷疑這一層。解壓完之后同樣去環(huán)境變量里新增ALLURE_HOME D:\devtools\allure-2.27.0然后在 PATH 里追加%ALLURE_HOME%\bin注意這里指的是bin目錄因?yàn)檎嬲目蓤?zhí)行文件allure.bat就在bin下面。配成根目錄的話終端會(huì)找不到命令。2.4 驗(yàn)證順序三條命令逐個(gè)確認(rèn)環(huán)境變量改完之后必須關(guān)掉所有已經(jīng)打開的 cmd 和 PowerShell 窗口重新開一個(gè)。原因是 Windows 的進(jìn)程在啟動(dòng)的那一刻會(huì)把環(huán)境變量做一次快照之后系統(tǒng)層面再怎么改已經(jīng)運(yùn)行的進(jìn)程都不會(huì)感知到。這一點(diǎn)后面還會(huì)專門講。新窗口里依次執(zhí)行java -version echo %JAVA_HOME% allure --version三條都有正常輸出Windows 側(cè)就算通了。第三條如果輸出類似2.27.0說明整套鏈路是活的。如果java -version正常但allure --version報(bào)錯(cuò)把錯(cuò)誤信息完整看一下。常見的是Error: Could not create the Java Virtual Machine這通常說明JAVA_HOME或者 JVM 參數(shù)有問題如果是找不到或無(wú)法加載主類基本可以鎖定在那個(gè)含空格的路徑上。3. Mac 上的兩種裝法Homebrew 省事手動(dòng)解壓可控Mac 這邊麻煩的地方不在安裝命令本身而在于 shell 加載環(huán)境變量的時(shí)機(jī)、Apple 自帶的 Java 樁程序以及 GUI 應(yīng)用不繼承終端環(huán)境這三件事湊在一起導(dǎo)致表現(xiàn)很迷惑。先把兩條安裝路線說清楚再挨個(gè)拆這些坑。3.1 Homebrew 路線的依賴鏈與常見中斷最省事的方式是用 Homebrewbrew install allure這條命令會(huì)自動(dòng)把 allure 裝到/opt/homebrew/binApple Silicon或/usr/local/binIntel并且符號(hào)鏈接已經(jīng)做好通常不需要再手工配 PATH。但它會(huì)引入 Java 依賴Homebrew 的 allure formula 依賴 openjdk 或 default-jdk 之類的 formula安裝過程中可能會(huì)去下載 JDK這時(shí)候如果網(wǎng)絡(luò)環(huán)境不穩(wěn)定就會(huì)卡在中途。一個(gè)常見的現(xiàn)象是下載到一半斷了然后重跑brew install allure報(bào)另一個(gè)進(jìn)程正在使用或者提示某個(gè) formula 處于 incomplete 狀態(tài)。處理辦法是先清理brew cleanup brew doctor按brew doctor給出的提示逐條處理再重跑安裝。如果反復(fù)卡在 JDK 依賴這一環(huán)其實(shí)可以直接走手動(dòng)路線效果一樣可控性還更高。裝完之后確認(rèn)版本allure --version如果提示 command not found先確認(rèn)/opt/homebrew/bin是否在 PATH 里echo $PATHIntel 機(jī)器上是/usr/local/binM 系列芯片是/opt/homebrew/bin兩者不一樣網(wǎng)上抄配置的時(shí)候要看清自己的機(jī)型。3.2 手動(dòng)解壓加 zshrc 的 PATH 寫法手動(dòng)路線和 Windows 類似下載 zip解壓到一個(gè)固定位置。這里建議放在用戶目錄下避免權(quán)限問題~/devtools/allure-2.27.0然后編輯~/.zshrcmacOS Catalina 之后默認(rèn) shell 已經(jīng)是 zsh加一行export PATH$HOME/devtools/allure-2.27.0/bin:$PATH注意這里是把新路徑前置不是追加在后面。前置的好處是如果系統(tǒng)里已有其他版本的 allure你可以確保用自己指定的這個(gè)。寫完保存執(zhí)行source ~/.zshrc allure --version這里有個(gè)很容易翻車的細(xì)節(jié)PATH 字符串不要手打不要從網(wǎng)頁(yè)上復(fù)制帶全角字符或者不可見空格的內(nèi)容。macOS 的 PATH 導(dǎo)致的問題里有相當(dāng)一部分是復(fù)制粘貼帶進(jìn)來的特殊字符肉眼看不出來但終端會(huì)把它當(dāng)成路徑的一部分結(jié)果是命令找不到反復(fù)echo $PATH也看不出異常。實(shí)在懷疑的話把那一行刪掉重打一遍比逐字符找可疑字符快得多。3.3 Apple 自帶 java 樁程序的迷惑行為在完全沒裝過 JDK 的 Mac 上敲java -version你會(huì)看到一句提示大意是沒有找到 Java 運(yùn)行時(shí)是否需要安裝并且會(huì)彈出一個(gè)下載引導(dǎo)。這是 Apple 留的一個(gè)占位程序它本身不是 Java。這件事造成的困惑是這樣的java -version有輸出雖然是提示安裝的輸出看起來Java 是有的但 allure 跑起來會(huì)報(bào)錯(cuò)。所以判斷 Mac 上 Java 是否可用不要只看命令有沒有回顯要看回顯的內(nèi)容是不是真正的版本號(hào)。裝 JDK 的推薦做法有兩個(gè)。一是用 Homebrewbrew install openjdk17裝完之后 Homebrew 通常會(huì)提示你需要做一次符號(hào)鏈接把 JDK 暴露給系統(tǒng)統(tǒng)一的 Java 目錄sudo ln -sfn /opt/homebrew/opt/openjdk17/libexec/openjdk.jdk \ /Library/Java/JavaVirtualMachines/openjdk-17.jdk這一步很多教程會(huì)漏掉不做的話/usr/libexec/java_home -V是看不到這個(gè) JDK 的某些依賴JAVA_HOME的工具就會(huì)失聯(lián)。二是直接下載 Temurin 的 pkg 安裝包雙擊裝完即可會(huì)自動(dòng)注冊(cè)到/Library/Java/JavaVirtualMachines下。裝好之后確認(rèn)/usr/libexec/java_home -V會(huì)列出所有已注冊(cè)的 JDK。如果想在~/.zshrc里固定 Java 版本可以這樣寫export JAVA_HOME$(/usr/libexec/java_home -v 17) export PATH$JAVA_HOME/bin:$PATH用java_home命令動(dòng)態(tài)取值的好處是換機(jī)器或者換版本時(shí)不用改硬編碼路徑腳本里寫死的/Library/Java/JavaVirtualMachines/xxx/Contents/Home一旦版本升級(jí)就失效了。3.4 GUI 應(yīng)用不繼承 shell 環(huán)境這件事這一條是 Mac 上特有的重災(zāi)區(qū)。macOS 的圖形界面應(yīng)用包括從 Dock 啟動(dòng)的終端以外的一切程序是由 launchd 啟動(dòng)的它們讀的環(huán)境變量和你在~/.zshrc里配的那套是兩套體系。也就是說你在終端里echo $PATH能看到 allure 的 bin 目錄但從 Finder 里雙擊打開的某個(gè)工具它的 PATH 里可能完全沒有這個(gè)東西。具體到 pytest allure 的場(chǎng)景最典型的表現(xiàn)是終端里跑pytest --alluredir./allure-results完全正常然后在 PyCharm 里點(diǎn)綠色三角跑同一個(gè)用例報(bào)錯(cuò)或者生成的報(bào)告少東西。因?yàn)?PyCharm 作為 GUI 應(yīng)用它的運(yùn)行進(jìn)程環(huán)境可能拿不到你 shell 里配的那些變量。這個(gè)問題在下一節(jié)會(huì)具體講怎么處理。4. 環(huán)境變量到底在哪一刻生效Windows 與 macOS 的加載順序差異上面提到要重開窗口這句話背后有具體機(jī)制值得展開講講。因?yàn)槔斫饬藱C(jī)制你就不會(huì)再做改完立刻測(cè)試、發(fā)現(xiàn)沒生效、以為配錯(cuò)了、反復(fù)改這種無(wú)效循環(huán)。4.1 進(jìn)程快照機(jī)制為什么新開窗口才行操作系統(tǒng)在創(chuàng)建進(jìn)程的時(shí)候會(huì)把父進(jìn)程的環(huán)境變量表復(fù)制一份給子進(jìn)程。這是一次性的復(fù)制不是引用。子進(jìn)程在自己的生命周期內(nèi)持有的是那份快照之后父進(jìn)程或者系統(tǒng)配置再發(fā)生變化這個(gè)已經(jīng)跑起來的進(jìn)程是感知不到的。所以 Windows 上改完環(huán)境變量已經(jīng)開著的 cmd 窗口里的%PATH%還是老的必須關(guān)掉重開新窗口才會(huì)從系統(tǒng)拿到更新后的環(huán)境變量表。同樣的道理已經(jīng)啟動(dòng)的 PyCharm、已經(jīng)在跑的 pytest 進(jìn)程都不會(huì)感知到你的修改。這里還有一層容易忽略的父子鏈上的每一層都要重新走一遍。比如你從 cmd 里啟動(dòng)了 PyCharmPyCharm 里再開終端跑 pytest這條鏈上每一級(jí)的進(jìn)程環(huán)境都是繼承來的。系統(tǒng)改了變量最頂層那個(gè) cmd 要關(guān)PyCharm 要從新的 cmd 里重新啟動(dòng)PyCharm 里的終端也要重開。很多我明明重啟了終端還是不行的情況就是因?yàn)橹虚g還有一層沒重啟。4.2 Windows 用戶變量與系統(tǒng)變量的取舍Windows 把環(huán)境變量分成用戶變量和系統(tǒng)變量?jī)杉?jí)。查找時(shí)的順序是先用戶后系統(tǒng)如果兩邊都有同名變量用戶變量?jī)?yōu)先。選哪一級(jí)配取決于使用場(chǎng)景。個(gè)人開發(fā)機(jī)、只有你自己用配用戶變量就夠了好處是不需要管理員權(quán)限改動(dòng)不影響其他賬戶。如果是共享的構(gòu)建機(jī)或者需要以服務(wù)方式運(yùn)行比如 CI Agent 常以某個(gè)服務(wù)賬戶跑那就得配系統(tǒng)變量因?yàn)榉?wù)賬戶不一定加載到你的用戶變量。JAVA_HOME和ALLURE_HOME這兩個(gè)建議都配用戶變量除非你明確知道有服務(wù)賬戶場(chǎng)景。PATH 的修改同理用戶級(jí)的 Path 改動(dòng)只影響你自己出問題了也好回滾。4.3 macOS 的 login shell 與 non-login shell 裝載的文件不一樣macOS 上 shell 啟動(dòng)時(shí)會(huì)讀哪些配置文件取決于它是 login shell 還是 non-login shell是交互式還是非交互式。這套規(guī)則復(fù)雜到很多人干脆放棄理解全憑試。簡(jiǎn)化后的實(shí)用結(jié)論是這樣的Terminal.app 里新開的窗口默認(rèn)是 login shell它會(huì)讀/etc/profile然后讀~/.zprofile然后讀~/.zshrc。而很多 IDE 內(nèi)嵌的終端或者腳本調(diào)起的 shell 是 non-login 的只會(huì)讀~/.zshrc。所以有個(gè)穩(wěn)妥的做法把 PATH 和 JAVA_HOME 這類需要被廣泛繼承的導(dǎo)出語(yǔ)句放在~/.zshrc里而不是~/.zprofile。因?yàn)閪/.zshrc被讀取的場(chǎng)景更多。如果你兩邊都寫了注意不要重復(fù)追加 PATH否則每開一個(gè) shell 就多疊一段PATH 會(huì)越長(zhǎng)越離譜排查時(shí)看著特別亂。檢查 PATH 有沒有被重復(fù)疊加可以執(zhí)行echo $PATH | tr : \n | sort | uniq -d有重復(fù)輸出就說明某處被追加了多次。4.4 source 之后仍然不生效的排查順序source ~/.zshrc之后命令還是找不到按這個(gè)順序查第一步確認(rèn)文件真的被讀到了?？梢栽趡/.zshrc末尾加一句echo zshrc loaded然后新開一個(gè)終端看有沒有打印出來。沒打印說明文件根本沒被加載可能是文件名不對(duì)比如誤建成了~/.zshrc.txtWindows 遷移過來的用戶特別容易犯這個(gè)錯(cuò)或者當(dāng)前 shell 不是 zsh。第二步確認(rèn)那一行語(yǔ)法沒問題。少個(gè)引號(hào)、多一個(gè)反斜杠都可能導(dǎo)致整行被忽略或者導(dǎo)出錯(cuò)誤的值。用echo $PATH看到的目標(biāo)路徑是否在其中。第三步確認(rèn)目標(biāo)文件真的有可執(zhí)行權(quán)限。手動(dòng)解壓出來的allure腳本如果是從 zip 里解壓的權(quán)限一般是對(duì)的但如果是從某些網(wǎng)盤或者其它途徑拿到的文件可能出現(xiàn)權(quán)限丟失。執(zhí)行l(wèi)s -l ~/devtools/allure-2.27.0/bin/allure chmod x ~/devtools/allure-2.27.0/bin/allure第四步確認(rèn) Java 那一層是通的。allure --version報(bào)的錯(cuò)如果指向 Java說明 PATH 其實(shí)已經(jīng)生效了問題在 Java 側(cè)別再折騰 PATH 了。5. 把 pytest 和 allure 接起來生成、查看、留痕環(huán)境配好只是把工具裝上了真正跑起來還需要在 pytest 這一側(cè)接線。這一節(jié)講安裝、參數(shù)固化以及幾個(gè)能讓報(bào)告真正好用的細(xì)節(jié)。5.1 allure-pytest 的安裝與 pytest.ini 固化參數(shù)裝插件pip install allure-pytest建議順手固定版本避免團(tuán)隊(duì)里不同人裝到不同版本導(dǎo)致報(bào)告結(jié)構(gòu)不一致pip install allure-pytest2.13.5然后在項(xiàng)目根目錄的pytest.ini里把輸出目錄固化下來[pytest] addopts --alluredir./allure-results --clean-alluredir testpaths tests這樣每次跑 pytest 不需要手打參數(shù)結(jié)果自動(dòng)落到allure-results。--clean-alluredir的作用是每次運(yùn)行前清空該目錄避免上一次的殘留數(shù)據(jù)混進(jìn)來。這個(gè)參數(shù)很重要不加的話你刪掉某條用例之后報(bào)告里可能還在顯示它——因?yàn)榕f的 JSON 文件還躺在目錄里allure 是無(wú)差別讀取的。注意--clean-alluredir清的是allure-results不是allure-report。生成的報(bào)告目錄是另一個(gè)命令產(chǎn)出的兩者的清理邏輯要分開看。5.2 generate、serve、open 三個(gè)命令該在什么場(chǎng)景用allure 命令行提供了三個(gè)容易混淆的子命令用錯(cuò)場(chǎng)景會(huì)覺得別扭命令作用適用場(chǎng)景allure serve results起一個(gè)本地服務(wù)臨時(shí)渲染并打開開發(fā)調(diào)試看完就關(guān)allure generate results -o report把結(jié)果渲染成靜態(tài)站點(diǎn)歸檔、CI 產(chǎn)物、需要分享allure open report起服務(wù)打開已生成的報(bào)告目錄已生成報(bào)告后本地查看生成靜態(tài)報(bào)告allure generate ./allure-results -o ./allure-report --clean--clean會(huì)在生成前清空目標(biāo)目錄。這個(gè)參數(shù)和上面的--clean-alluredir不是一回事別混。最常用的是allure serve一條命令直接看到結(jié)果allure serve ./allure-results它會(huì)臨時(shí)起一個(gè) HTTP 服務(wù)并在瀏覽器打開。缺點(diǎn)是關(guān)掉終端就沒了而且如果報(bào)告里附件很多每次都要重新渲染一遍稍慢。日常調(diào)試用它要留檔就用generate。5.3 讓趨勢(shì)圖不丟history 目錄的手動(dòng)搬運(yùn)趨勢(shì)圖Trends是 allure 報(bào)告里很有價(jià)值的一塊能看到通過率的走勢(shì)。但很多人會(huì)發(fā)現(xiàn)它永遠(yuǎn)是空的。原因在于趨勢(shì)數(shù)據(jù)不是從allure-results里推出來的而是從上一次生成的報(bào)告里的 history 目錄繼承來的。也就是說allure generate的時(shí)候它會(huì)去allure-report/history找歷史數(shù)據(jù)處理完再輸出到新的history目錄。如果你每次都加--clean或者每次都換一個(gè)新的輸出目錄那歷史就被清掉了趨勢(shì)自然斷。正確的做法是在生成新報(bào)告之前把上一次的 history 拷到這次的 results 目錄里cp -r ./allure-report/history ./allure-results/ 2/dev/null || true allure generate ./allure-results -o ./allure-report --clean這段邏輯在 CI 里通常寫成腳本。第一次跑的時(shí)候 history 不存在所以要容忍失敗加個(gè)|| true或者做個(gè)存在性判斷。這個(gè)技巧很多教程不會(huì)寫但在實(shí)際做持續(xù)集成的時(shí)候是必需的不然趨勢(shì)圖永遠(yuǎn)是一條空線。5.4 報(bào)告里的 environment 與分類信息怎么補(bǔ)報(bào)告右上角可以放環(huán)境信息方法是往allure-results目錄里放一個(gè)environment.propertiesBase.URLhttps://api.example.com Python3.11.5 Envstaging Run.Bynightly-job這個(gè)文件在allure generate的時(shí)候會(huì)被讀取。注意它必須放在 results 目錄里放在 report 目錄里是沒用的。而且如果用了--clean-alluredir每次 pytest 運(yùn)行前目錄被清空這個(gè)文件也就沒了。處理辦法是在 pytest 的 session 級(jí) fixture 里動(dòng)態(tài)寫或者干脆不用--clean-alluredir改成跑完 pytest 之后自己刪舊文件再補(bǔ)上。還有一個(gè)categories.json用來把失敗按規(guī)則歸類比如斷言失敗歸一類、超時(shí)歸一類。格式大致是[ { name: 斷言失敗, matchedStatuses: [failed], messageRegex: .*AssertionError.* } ]同樣放在 results 目錄里。對(duì)于用例量大、失敗類型雜的項(xiàng)目這個(gè)文件能把報(bào)告的可讀性提升一個(gè)檔次。6. PyCharm 場(chǎng)景下的特殊處理PyCharm 是很多人跑 pytest 的主力環(huán)境它和終端環(huán)境之間的變量繼承差異是 Mac 上尤其突出的一個(gè)坑。6.1 終端通、Run 不通的根因現(xiàn)象很明確PyCharm 底部的 Terminal 里敲allure serve ./allure-results完全正常但點(diǎn)某個(gè)用例旁邊的綠色三角或者右鍵 Run報(bào)錯(cuò)說找不到 allure 或者 PATH 不對(duì)。根因有兩條。一是 GUI 啟動(dòng)的 PyCharm 本身就是從 launchd 繼承環(huán)境可能拿不到~/.zshrc里的導(dǎo)出。二是即使 PyCharm 拿到了它的 Run Configuration 是獨(dú)立配置的不一定繼承 Terminal 的 shell 環(huán)境。這兩條疊在一起就出現(xiàn)了同一個(gè)軟件里表現(xiàn)不一致。6.2 三種讓 Run Configuration 拿到 PATH 的辦法按侵入性從低到高排列第一種是在 Run Configuration 里手工加環(huán)境變量。打開 Run/Debug Configurations找到對(duì)應(yīng)的 pytest 配置在 Environment variables 那一欄點(diǎn)開把PATH或者ALLURE_HOME顯式填進(jìn)去。適合只有一兩個(gè)配置、改動(dòng)不頻繁的情況。第二種是裝 EnvFile 插件。它支持指定一個(gè).env文件PyCharm 啟動(dòng)進(jìn)程時(shí)會(huì)自動(dòng)把這些變量注入。好處是配置文件可以進(jìn)版本庫(kù)團(tuán)隊(duì)共享?yè)Q機(jī)器不用重配。代價(jià)是多了一個(gè)插件依賴。第三種是從終端啟動(dòng) PyCharm。在命令行里執(zhí)行open -a PyCharm或者直接跑 PyCharm 的可執(zhí)行文件。這樣啟動(dòng)的 PyCharm 會(huì)繼承當(dāng)前 shell 的全部環(huán)境Run Configuration 里就不用額外配了。缺點(diǎn)是每次都要走終端用 Dock 圖標(biāo)點(diǎn)開的時(shí)候不生效容易忘。我個(gè)人的習(xí)慣是第三種加上在~/.zshrc里把配置寫規(guī)整日常用 Dock 啟動(dòng)遇到問題時(shí)用終端啟動(dòng)一次對(duì)比一下是不是環(huán)境問題這個(gè)對(duì)比動(dòng)作本身就能快速定位。6.3 路徑里帶空格和中文引發(fā)的解析問題這一點(diǎn)在 Windows 的 PyCharm 上特別常見。項(xiàng)目放在類似這樣的路徑下C:\Users\張三\我的項(xiàng)目\自動(dòng)化測(cè)試然后allure generate報(bào)錯(cuò)或者生成的報(bào)告打開是空白的。原因和前面講的 allure 腳本拼 classpath 是同一類問題——路徑里的空格和中文在某些環(huán)節(jié)沒有被正確引用或者編碼。處理辦法很直接把 allure 命令行工具裝在純英文無(wú)空格的目錄前面已經(jīng)建議了D:\devtools\allure-2.27.0項(xiàng)目本身的路徑也盡量保持英文。如果項(xiàng)目路徑動(dòng)不了至少保證輸出目錄是干凈的比如--alluredirD:\allure-out避開項(xiàng)目路徑里的空格。另外注意相對(duì)路徑./allure-results在不同工具里的工作目錄可能不一樣。PyCharm 的 Run Configuration 默認(rèn)工作目錄是項(xiàng)目根但從 Terminal 里跑的時(shí)候可能是別的地方。如果出現(xiàn)報(bào)告生成了但找不到的情況把路徑改成絕對(duì)路徑先跑通再說。7. 排錯(cuò)清單把裝完了但沒用按癥狀切開前面各節(jié)散著講了很多問題這里做一個(gè)集中對(duì)照方便出問題的時(shí)候快速定位。7.1 癥狀對(duì)照表癥狀大概率原因優(yōu)先檢查allure命令找不到PATH 未生效或未重開終端重開終端、echo $PATH報(bào)找不到主類路徑含空格classpath 被截?cái)郺llure 安裝目錄路徑JVM 啟動(dòng)失敗JAVA_HOME指向錯(cuò)誤java -version、echo $JAVA_HOMEjava -version版本不對(duì)PATH 被 javapath 搶占where java報(bào)告生成但空白allure-results為空是否裝了allure-pytest、是否傳了--alluredir報(bào)告里有已刪除的用例results 目錄殘留加--clean-alluredir趨勢(shì)圖永遠(yuǎn)為空history 未繼承拷貝上一次 report 的 history終端通、IDE 不通GUI 應(yīng)用未繼承 shell 環(huán)境Run Configuration 的環(huán)境變量這張表能覆蓋絕大部分場(chǎng)景。遇到問題時(shí)先對(duì)號(hào)入座比漫無(wú)目的地搜教程要快。7.2 一個(gè)多版本沖突的排查過程復(fù)原講一個(gè)我實(shí)際遇到的情況。機(jī)器上先后裝過兩個(gè) JDK一個(gè) 8一個(gè) 17另外裝了某個(gè)帶 Java 的桌面軟件。表現(xiàn)是cmd 里java -version顯示 1.8allure --version卻報(bào)主類錯(cuò)誤。排查過程是這樣的。第一步where java輸出三行第一行是那個(gè)桌面軟件目錄下的java.exe第二行才是 JDK 8 的。也就是說java -version顯示的 8 其實(shí)來自別處不是我以為的那個(gè)。第二步echo %JAVA_HOME%指向的是 JDK 17 的目錄。這就出現(xiàn)了矛盾PATH 里排第一的 java 是 8但JAVA_HOME指向 17。allure 啟動(dòng)腳本優(yōu)先用JAVA_HOME所以它用 17 去跑但那個(gè)腳本里可能還引用了別的東西導(dǎo)致混亂。第三步把 PATH 里那個(gè)桌面軟件的 java 路徑刪掉同時(shí)把%JAVA_HOME%\bin上移重開終端。問題解決。這個(gè)案例的價(jià)值在于java -version和JAVA_HOME是兩個(gè)獨(dú)立的信號(hào)源工具可能優(yōu)先讀其中一個(gè)也可能兩個(gè)都讀。排查時(shí)必須分別確認(rèn)不能看了一個(gè)就下結(jié)論。7.3 升級(jí)與版本匹配的建議最后說版本。allure-pytest和 allure 命令行是兩條獨(dú)立的版本線它們之間靠allure-results里的數(shù)據(jù)格式溝通。設(shè)計(jì)上是向前兼容的但有一個(gè)最低要求命令行工具太舊的話插件新加的標(biāo)簽和步驟渲染不出來。實(shí)用建議是命令行版本保持在 2.20 以上allure-pytest保持在 2.9 以上。團(tuán)隊(duì)里最好把這兩個(gè)版本都寫進(jìn)文檔或者寫進(jìn)requirements.txt和構(gòu)建腳本避免出現(xiàn)我本地報(bào)告正常、CI 上少了幾塊的詭異差異。升級(jí)的時(shí)候不要只升一邊兩個(gè)一起升升完拿一份歷史結(jié)果跑一遍回歸確認(rèn)渲染沒問題再推到團(tuán)隊(duì)里用。環(huán)境變量這部分我個(gè)人在幾臺(tái)機(jī)器上來回折騰之后的體會(huì)是把它當(dāng)成一條鏈路來看待Java 是一環(huán)allure 命令行是一環(huán)pytest 插件是第三環(huán)任何一環(huán)斷了都會(huì)表現(xiàn)為allure 用不了。每次出問題不要急著改配置先用where javaWindows或/usr/libexec/java_home -VMac、allure --version、pytest --collect-only這三條命令把三環(huán)各自的現(xiàn)狀確認(rèn)一遍問題基本會(huì)自己浮出來。另外有個(gè)小技巧值得留著在~/.zshrc或者 Windows 的用戶變量里把ALLURE_HOME和JAVA_HOME都配上不要只配 PATH因?yàn)橛行┠_本和插件會(huì)去讀這兩個(gè)變量做路徑推導(dǎo)只配 PATH 的時(shí)候它們會(huì)靜默失敗不報(bào)錯(cuò)也不生效排查起來極其費(fèi)勁。 pytest+Allure安裝與環(huán)境變量配置實(shí)戰(zhàn)指南
pytest 跑出幾百條用例之后最難受的往往不是失敗本身而是失敗之后要在一屏一屏的終端輸出里翻找哪一條斷言掛了。這時(shí)候 allure 就會(huì)進(jìn)入視野——它把 pytest 的執(zhí)行結(jié)果渲染成帶步驟、附件、失敗截圖和趨勢(shì)曲線的可視化報(bào)告。但不少人卡在第一步allure 裝不上或者裝上了敲 allure 提示 command not found。這篇就圍繞 pytest 場(chǎng)景下的 allure 安裝與環(huán)境變量配置把 Windows 和 Mac 兩條路完整走一遍包括它背后的 JDK 依賴、PATH 寫法、pytest 側(cè)插件對(duì)接以及那些明明看著是 PATH 問題、表現(xiàn)出來卻像別的問題的典型場(chǎng)景。1. 拆開看 allure 這條鏈路誰(shuí)依賴誰(shuí)先搞清楚再動(dòng)手在動(dòng)手敲命令之前有一件事必須先說明白allure 不是 Python 生態(tài)里的東西它和 pip 沒有半點(diǎn)關(guān)系。很多人第一次搜a(bǔ)llure 安裝看到第一行是pip install allure-pytest裝完就以為搞定了然后在終端里敲allure --version得到一句不是內(nèi)部或外部命令。這個(gè)誤會(huì)幾乎每個(gè)新手都踩過一次把它講清楚后面所有步驟才有邏輯。1.1 allure 命令行是一條獨(dú)立的 Java 工具鏈Allure 命令行版本發(fā)布出來的是一個(gè)壓縮包解壓后大致長(zhǎng)這樣allure-2.27.0/ ├── bin/ │ ├── allure # macOS / Linux 用的 shell 腳本 │ └── allure.bat # Windows 用的批處理 ├── config/ └── lib/ ├── allure-commandline-2.27.0.jar ── ... 一堆依賴 jar這個(gè)結(jié)構(gòu)已經(jīng)說明了它的本質(zhì)一堆 jar 包外面套了一個(gè)啟動(dòng)腳本。allure和allure.bat干的事情其實(shí)很簡(jiǎn)單——找到本機(jī)的 Java 運(yùn)行時(shí)把 lib 目錄下那堆 jar 拼成 classpath然后把命令行參數(shù)原樣透?jìng)鹘o Java 主類。所以它和 Maven、Gradle 是同一類東西屬于JVM 上的命令行工具。這就直接推出了兩個(gè)硬性結(jié)論。第一機(jī)器上必須有能用的 Java 運(yùn)行時(shí)而且版本不能太低Allure 2.x 系列基本要求 Java 8 及以上現(xiàn)在用 11 或 17 更穩(wěn)。第二Java 光裝上還不行必須讓allure.bat或allure腳本能在它自己的執(zhí)行上下文里找到 Java這就涉及到JAVA_HOME或者 PATH 的問題。很多allure 裝了但跑不起來的案例根因其實(shí)在 Java 那一側(cè)而不是 allure 本身。1.2 pytest 側(cè)的 allure-pytest 只負(fù)責(zé)產(chǎn)出原料allure-pytest這個(gè) Python 包的作用非常單一它是一個(gè) pytest 插件通過在用例執(zhí)行的各個(gè)鉤子上打點(diǎn)把測(cè)試結(jié)果寫成一組結(jié)構(gòu)化的 JSON/XML 文件通常落在allure-results目錄里。它完全不負(fù)責(zé)渲染不負(fù)責(zé)啟動(dòng)服務(wù)也不會(huì)給你生成一個(gè)能點(diǎn)開的 HTML 頁(yè)面。也就是說整條鏈路是兩段式的環(huán)節(jié)承擔(dān)者產(chǎn)物采集測(cè)試數(shù)據(jù)allure-pytest插件allure-results/下的一堆 JSON渲染成報(bào)告allure 命令行工具allure-report/靜態(tài)站點(diǎn)或本地服務(wù)搞不清這個(gè)分段就會(huì)出現(xiàn)很典型的困惑我 pip 裝了 allure也跑了 pytest為什么沒有報(bào)告因?yàn)槟阒煌瓿闪说谝欢蔚诙蔚拿钚泄ぞ邏焊鶝]裝。反過來也有我裝了命令行工具allure --version也有輸出為什么 pytest 跑完allure-results是空的那是插件沒裝或者沒通過--alluredir指定輸出目錄。1.3 三類高頻失敗癥狀和對(duì)策完全不同把常見問題歸一下類會(huì)發(fā)現(xiàn)它們雖然都表現(xiàn)為allure 用不了但處理路徑完全不同第一類是命令找不到allure在終端里不被識(shí)別。這是純環(huán)境變量問題PATH 里沒有 allure 的 bin 目錄或者配了但當(dāng)前終端窗口沒重新加載。第二類是命令能找到但執(zhí)行報(bào)錯(cuò)比如提示找不到主類、Java 版本不兼容、JVM 啟動(dòng)失敗。這是 Java 環(huán)境問題JAVA_HOME指向不對(duì)或者指向了一個(gè) JRE 而非完整 JDK。第三類是命令正常、報(bào)告空白或元素缺失比如報(bào)告能打開但一個(gè)用例都沒有或者趨勢(shì)圖永遠(yuǎn)是空的。這通常是觸發(fā)參數(shù)、目錄清理、history 目錄處理的問題跟環(huán)境變量已經(jīng)沒關(guān)系了。下面的內(nèi)容會(huì)按這個(gè)分類依次展開。先說 Windows因?yàn)樗沫h(huán)境變量機(jī)制更顯式也更容易排查。2. Windows 上的完整落地路徑從 JDK 到 PATH 一次性配齊Windows 上配環(huán)境變量的順序很重要先 Java 后 allure因?yàn)?allure 啟動(dòng)腳本會(huì)去讀 Java 相關(guān)的變量。反過來做的話你會(huì)先看到 allure 報(bào)錯(cuò)然后再回頭補(bǔ) Java多繞一圈。2.1 JDK 的選擇與 JAVA_HOME 的正確指向JDK 用什么發(fā)行版其實(shí)無(wú)所謂Temurin原 AdoptOpenJDK、Zulu、微軟的 OpenJDK、Oracle JDK 都行只要版本在 8 以上。安裝時(shí)有個(gè)選項(xiàng)要注意如果要裝多個(gè)版本共存就不要勾選設(shè)置 JAVA_HOME 變量這類選項(xiàng)讓安裝器自己動(dòng)環(huán)境變量反而容易把已有配置覆蓋掉手工配更可控。安裝完成后先開一個(gè)新的 cmd 窗口敲java -version有正常的版本輸出說明 Java 已經(jīng)在 PATH 里了。但這一步不能證明JAVA_HOME是對(duì)的這是兩個(gè)獨(dú)立的東西。接著確認(rèn)JAVA_HOMEecho %JAVA_HOME%正確的結(jié)果應(yīng)該是 JDK 的根目錄類似這樣D:\devtools\jdk-17有兩個(gè)常見的錯(cuò)誤指向要特別提一下。一是把它指向了bin目錄寫成D:\devtools\jdk-17\bin這是錯(cuò)的JAVA_HOME表達(dá)的是JDK 的家在哪不是可執(zhí)行文件在哪。二是把它指向了jre目錄某些 Oracle 安裝包會(huì)單獨(dú)裝一個(gè) JRE 出來指向那里的話如果后續(xù)有什么工具需要編譯相關(guān)的能力就會(huì)出問題。設(shè)置路徑是此電腦右鍵 →屬性→高級(jí)系統(tǒng)設(shè)置→環(huán)境變量。新增一個(gè)用戶變量JAVA_HOME值填 JDK 根目錄。然后找到Path點(diǎn)編輯新增一行%JAVA_HOME%\bin用%JAVA_HOME%這種相對(duì)引用而不是寫死絕對(duì)路徑好處是以后換 JDK 版本只需要改JAVA_HOME一處PATH 不用動(dòng)。這是個(gè)很小的習(xí)慣但在需要多版本切換的團(tuán)隊(duì)里能省不少事。2.2 Path 中最容易被搶占的那一行javapath 的坑這里有個(gè)非常隱蔽的問題值得單獨(dú)講。Windows 上裝了 Oracle JDK 或者某些帶 Java 的軟件之后會(huì)在C:\Program Files\Common Files\Oracle\Java\javapath或者C:\Windows\System32里放一個(gè)java.exe的轉(zhuǎn)發(fā)程序。如果這個(gè)路徑在 PATH 里排在%JAVA_HOME%\bin前面那么java -version顯示的版本就是那個(gè)轉(zhuǎn)發(fā)程序指向的版本而不是你新配的。排查方式是在 cmd 里執(zhí)行where java它會(huì)按 PATH 順序列出所有匹配的java.exe。如果第一行不是你想用的 JDK 下的那個(gè)說明被搶占了。解決方法有兩個(gè)一是把%JAVA_HOME%\bin上移到 PATH 列表頂部二是干脆把那個(gè)干擾項(xiàng)從 PATH 里刪掉。我個(gè)人推薦前者動(dòng)的東西少回滾也容易。注意Windows 的 PATH 是從左到右、先命中先用的查找順序。這不是哪個(gè)最新用哪個(gè)也不是哪個(gè)版本高用哪個(gè)純粹看位置。理解這一點(diǎn)很多我明明改了環(huán)境變量為什么沒生效的疑問就能自己想明白。2.3 解壓 allure 命令行包并配置 ALLURE_HOMEJava 那邊確認(rèn)無(wú)誤之后再去下載 allure 命令行包。取 zip 版本解壓到一個(gè)不含空格、不含中文、不含特殊符號(hào)的目錄。比如D:\devtools\allure-2.27.0為什么不建議放在Program Files或者桌面這種路徑下因?yàn)閍llure.bat內(nèi)部做 classpath 拼接的時(shí)候是把lib目錄下的 jar 一個(gè)個(gè)用分號(hào)連起來的路徑里出現(xiàn)空格如果腳本里的引用沒有全部加引號(hào)實(shí)際上歷史版本的腳本確實(shí)有過這個(gè)問題就會(huì)出現(xiàn) classpath 被空格截?cái)?、?bào)找不到主類的情況。放在D:\devtools這種干凈路徑下一勞永逸省得排查時(shí)還要懷疑這一層。解壓完之后同樣去環(huán)境變量里新增ALLURE_HOME D:\devtools\allure-2.27.0然后在 PATH 里追加%ALLURE_HOME%\bin注意這里指的是bin目錄因?yàn)檎嬲目蓤?zhí)行文件allure.bat就在bin下面。配成根目錄的話終端會(huì)找不到命令。2.4 驗(yàn)證順序三條命令逐個(gè)確認(rèn)環(huán)境變量改完之后必須關(guān)掉所有已經(jīng)打開的 cmd 和 PowerShell 窗口重新開一個(gè)。原因是 Windows 的進(jìn)程在啟動(dòng)的那一刻會(huì)把環(huán)境變量做一次快照之后系統(tǒng)層面再怎么改已經(jīng)運(yùn)行的進(jìn)程都不會(huì)感知到。這一點(diǎn)后面還會(huì)專門講。新窗口里依次執(zhí)行java -version echo %JAVA_HOME% allure --version三條都有正常輸出Windows 側(cè)就算通了。第三條如果輸出類似2.27.0說明整套鏈路是活的。如果java -version正常但allure --version報(bào)錯(cuò)把錯(cuò)誤信息完整看一下。常見的是Error: Could not create the Java Virtual Machine這通常說明JAVA_HOME或者 JVM 參數(shù)有問題如果是找不到或無(wú)法加載主類基本可以鎖定在那個(gè)含空格的路徑上。3. Mac 上的兩種裝法Homebrew 省事手動(dòng)解壓可控Mac 這邊麻煩的地方不在安裝命令本身而在于 shell 加載環(huán)境變量的時(shí)機(jī)、Apple 自帶的 Java 樁程序以及 GUI 應(yīng)用不繼承終端環(huán)境這三件事湊在一起導(dǎo)致表現(xiàn)很迷惑。先把兩條安裝路線說清楚再挨個(gè)拆這些坑。3.1 Homebrew 路線的依賴鏈與常見中斷最省事的方式是用 Homebrewbrew install allure這條命令會(huì)自動(dòng)把 allure 裝到/opt/homebrew/binApple Silicon或/usr/local/binIntel并且符號(hào)鏈接已經(jīng)做好通常不需要再手工配 PATH。但它會(huì)引入 Java 依賴Homebrew 的 allure formula 依賴 openjdk 或 default-jdk 之類的 formula安裝過程中可能會(huì)去下載 JDK這時(shí)候如果網(wǎng)絡(luò)環(huán)境不穩(wěn)定就會(huì)卡在中途。一個(gè)常見的現(xiàn)象是下載到一半斷了然后重跑brew install allure報(bào)另一個(gè)進(jìn)程正在使用或者提示某個(gè) formula 處于 incomplete 狀態(tài)。處理辦法是先清理brew cleanup brew doctor按brew doctor給出的提示逐條處理再重跑安裝。如果反復(fù)卡在 JDK 依賴這一環(huán)其實(shí)可以直接走手動(dòng)路線效果一樣可控性還更高。裝完之后確認(rèn)版本allure --version如果提示 command not found先確認(rèn)/opt/homebrew/bin是否在 PATH 里echo $PATHIntel 機(jī)器上是/usr/local/binM 系列芯片是/opt/homebrew/bin兩者不一樣網(wǎng)上抄配置的時(shí)候要看清自己的機(jī)型。3.2 手動(dòng)解壓加 zshrc 的 PATH 寫法手動(dòng)路線和 Windows 類似下載 zip解壓到一個(gè)固定位置。這里建議放在用戶目錄下避免權(quán)限問題~/devtools/allure-2.27.0然后編輯~/.zshrcmacOS Catalina 之后默認(rèn) shell 已經(jīng)是 zsh加一行export PATH$HOME/devtools/allure-2.27.0/bin:$PATH注意這里是把新路徑前置不是追加在后面。前置的好處是如果系統(tǒng)里已有其他版本的 allure你可以確保用自己指定的這個(gè)。寫完保存執(zhí)行source ~/.zshrc allure --version這里有個(gè)很容易翻車的細(xì)節(jié)PATH 字符串不要手打不要從網(wǎng)頁(yè)上復(fù)制帶全角字符或者不可見空格的內(nèi)容。macOS 的 PATH 導(dǎo)致的問題里有相當(dāng)一部分是復(fù)制粘貼帶進(jìn)來的特殊字符肉眼看不出來但終端會(huì)把它當(dāng)成路徑的一部分結(jié)果是命令找不到反復(fù)echo $PATH也看不出異常。實(shí)在懷疑的話把那一行刪掉重打一遍比逐字符找可疑字符快得多。3.3 Apple 自帶 java 樁程序的迷惑行為在完全沒裝過 JDK 的 Mac 上敲java -version你會(huì)看到一句提示大意是沒有找到 Java 運(yùn)行時(shí)是否需要安裝并且會(huì)彈出一個(gè)下載引導(dǎo)。這是 Apple 留的一個(gè)占位程序它本身不是 Java。這件事造成的困惑是這樣的java -version有輸出雖然是提示安裝的輸出看起來Java 是有的但 allure 跑起來會(huì)報(bào)錯(cuò)。所以判斷 Mac 上 Java 是否可用不要只看命令有沒有回顯要看回顯的內(nèi)容是不是真正的版本號(hào)。裝 JDK 的推薦做法有兩個(gè)。一是用 Homebrewbrew install openjdk17裝完之后 Homebrew 通常會(huì)提示你需要做一次符號(hào)鏈接把 JDK 暴露給系統(tǒng)統(tǒng)一的 Java 目錄sudo ln -sfn /opt/homebrew/opt/openjdk17/libexec/openjdk.jdk \ /Library/Java/JavaVirtualMachines/openjdk-17.jdk這一步很多教程會(huì)漏掉不做的話/usr/libexec/java_home -V是看不到這個(gè) JDK 的某些依賴JAVA_HOME的工具就會(huì)失聯(lián)。二是直接下載 Temurin 的 pkg 安裝包雙擊裝完即可會(huì)自動(dòng)注冊(cè)到/Library/Java/JavaVirtualMachines下。裝好之后確認(rèn)/usr/libexec/java_home -V會(huì)列出所有已注冊(cè)的 JDK。如果想在~/.zshrc里固定 Java 版本可以這樣寫export JAVA_HOME$(/usr/libexec/java_home -v 17) export PATH$JAVA_HOME/bin:$PATH用java_home命令動(dòng)態(tài)取值的好處是換機(jī)器或者換版本時(shí)不用改硬編碼路徑腳本里寫死的/Library/Java/JavaVirtualMachines/xxx/Contents/Home一旦版本升級(jí)就失效了。3.4 GUI 應(yīng)用不繼承 shell 環(huán)境這件事這一條是 Mac 上特有的重災(zāi)區(qū)。macOS 的圖形界面應(yīng)用包括從 Dock 啟動(dòng)的終端以外的一切程序是由 launchd 啟動(dòng)的它們讀的環(huán)境變量和你在~/.zshrc里配的那套是兩套體系。也就是說你在終端里echo $PATH能看到 allure 的 bin 目錄但從 Finder 里雙擊打開的某個(gè)工具它的 PATH 里可能完全沒有這個(gè)東西。具體到 pytest allure 的場(chǎng)景最典型的表現(xiàn)是終端里跑pytest --alluredir./allure-results完全正常然后在 PyCharm 里點(diǎn)綠色三角跑同一個(gè)用例報(bào)錯(cuò)或者生成的報(bào)告少東西。因?yàn)?PyCharm 作為 GUI 應(yīng)用它的運(yùn)行進(jìn)程環(huán)境可能拿不到你 shell 里配的那些變量。這個(gè)問題在下一節(jié)會(huì)具體講怎么處理。4. 環(huán)境變量到底在哪一刻生效Windows 與 macOS 的加載順序差異上面提到要重開窗口這句話背后有具體機(jī)制值得展開講講。因?yàn)槔斫饬藱C(jī)制你就不會(huì)再做改完立刻測(cè)試、發(fā)現(xiàn)沒生效、以為配錯(cuò)了、反復(fù)改這種無(wú)效循環(huán)。4.1 進(jìn)程快照機(jī)制為什么新開窗口才行操作系統(tǒng)在創(chuàng)建進(jìn)程的時(shí)候會(huì)把父進(jìn)程的環(huán)境變量表復(fù)制一份給子進(jìn)程。這是一次性的復(fù)制不是引用。子進(jìn)程在自己的生命周期內(nèi)持有的是那份快照之后父進(jìn)程或者系統(tǒng)配置再發(fā)生變化這個(gè)已經(jīng)跑起來的進(jìn)程是感知不到的。所以 Windows 上改完環(huán)境變量已經(jīng)開著的 cmd 窗口里的%PATH%還是老的必須關(guān)掉重開新窗口才會(huì)從系統(tǒng)拿到更新后的環(huán)境變量表。同樣的道理已經(jīng)啟動(dòng)的 PyCharm、已經(jīng)在跑的 pytest 進(jìn)程都不會(huì)感知到你的修改。這里還有一層容易忽略的父子鏈上的每一層都要重新走一遍。比如你從 cmd 里啟動(dòng)了 PyCharmPyCharm 里再開終端跑 pytest這條鏈上每一級(jí)的進(jìn)程環(huán)境都是繼承來的。系統(tǒng)改了變量最頂層那個(gè) cmd 要關(guān)PyCharm 要從新的 cmd 里重新啟動(dòng)PyCharm 里的終端也要重開。很多我明明重啟了終端還是不行的情況就是因?yàn)橹虚g還有一層沒重啟。4.2 Windows 用戶變量與系統(tǒng)變量的取舍Windows 把環(huán)境變量分成用戶變量和系統(tǒng)變量?jī)杉?jí)。查找時(shí)的順序是先用戶后系統(tǒng)如果兩邊都有同名變量用戶變量?jī)?yōu)先。選哪一級(jí)配取決于使用場(chǎng)景。個(gè)人開發(fā)機(jī)、只有你自己用配用戶變量就夠了好處是不需要管理員權(quán)限改動(dòng)不影響其他賬戶。如果是共享的構(gòu)建機(jī)或者需要以服務(wù)方式運(yùn)行比如 CI Agent 常以某個(gè)服務(wù)賬戶跑那就得配系統(tǒng)變量因?yàn)榉?wù)賬戶不一定加載到你的用戶變量。JAVA_HOME和ALLURE_HOME這兩個(gè)建議都配用戶變量除非你明確知道有服務(wù)賬戶場(chǎng)景。PATH 的修改同理用戶級(jí)的 Path 改動(dòng)只影響你自己出問題了也好回滾。4.3 macOS 的 login shell 與 non-login shell 裝載的文件不一樣macOS 上 shell 啟動(dòng)時(shí)會(huì)讀哪些配置文件取決于它是 login shell 還是 non-login shell是交互式還是非交互式。這套規(guī)則復(fù)雜到很多人干脆放棄理解全憑試。簡(jiǎn)化后的實(shí)用結(jié)論是這樣的Terminal.app 里新開的窗口默認(rèn)是 login shell它會(huì)讀/etc/profile然后讀~/.zprofile然后讀~/.zshrc。而很多 IDE 內(nèi)嵌的終端或者腳本調(diào)起的 shell 是 non-login 的只會(huì)讀~/.zshrc。所以有個(gè)穩(wěn)妥的做法把 PATH 和 JAVA_HOME 這類需要被廣泛繼承的導(dǎo)出語(yǔ)句放在~/.zshrc里而不是~/.zprofile。因?yàn)閪/.zshrc被讀取的場(chǎng)景更多。如果你兩邊都寫了注意不要重復(fù)追加 PATH否則每開一個(gè) shell 就多疊一段PATH 會(huì)越長(zhǎng)越離譜排查時(shí)看著特別亂。檢查 PATH 有沒有被重復(fù)疊加可以執(zhí)行echo $PATH | tr : \n | sort | uniq -d有重復(fù)輸出就說明某處被追加了多次。4.4 source 之后仍然不生效的排查順序source ~/.zshrc之后命令還是找不到按這個(gè)順序查第一步確認(rèn)文件真的被讀到了?？梢栽趡/.zshrc末尾加一句echo zshrc loaded然后新開一個(gè)終端看有沒有打印出來。沒打印說明文件根本沒被加載可能是文件名不對(duì)比如誤建成了~/.zshrc.txtWindows 遷移過來的用戶特別容易犯這個(gè)錯(cuò)或者當(dāng)前 shell 不是 zsh。第二步確認(rèn)那一行語(yǔ)法沒問題。少個(gè)引號(hào)、多一個(gè)反斜杠都可能導(dǎo)致整行被忽略或者導(dǎo)出錯(cuò)誤的值。用echo $PATH看到的目標(biāo)路徑是否在其中。第三步確認(rèn)目標(biāo)文件真的有可執(zhí)行權(quán)限。手動(dòng)解壓出來的allure腳本如果是從 zip 里解壓的權(quán)限一般是對(duì)的但如果是從某些網(wǎng)盤或者其它途徑拿到的文件可能出現(xiàn)權(quán)限丟失。執(zhí)行l(wèi)s -l ~/devtools/allure-2.27.0/bin/allure chmod x ~/devtools/allure-2.27.0/bin/allure第四步確認(rèn) Java 那一層是通的。allure --version報(bào)的錯(cuò)如果指向 Java說明 PATH 其實(shí)已經(jīng)生效了問題在 Java 側(cè)別再折騰 PATH 了。5. 把 pytest 和 allure 接起來生成、查看、留痕環(huán)境配好只是把工具裝上了真正跑起來還需要在 pytest 這一側(cè)接線。這一節(jié)講安裝、參數(shù)固化以及幾個(gè)能讓報(bào)告真正好用的細(xì)節(jié)。5.1 allure-pytest 的安裝與 pytest.ini 固化參數(shù)裝插件pip install allure-pytest建議順手固定版本避免團(tuán)隊(duì)里不同人裝到不同版本導(dǎo)致報(bào)告結(jié)構(gòu)不一致pip install allure-pytest2.13.5然后在項(xiàng)目根目錄的pytest.ini里把輸出目錄固化下來[pytest] addopts --alluredir./allure-results --clean-alluredir testpaths tests這樣每次跑 pytest 不需要手打參數(shù)結(jié)果自動(dòng)落到allure-results。--clean-alluredir的作用是每次運(yùn)行前清空該目錄避免上一次的殘留數(shù)據(jù)混進(jìn)來。這個(gè)參數(shù)很重要不加的話你刪掉某條用例之后報(bào)告里可能還在顯示它——因?yàn)榕f的 JSON 文件還躺在目錄里allure 是無(wú)差別讀取的。注意--clean-alluredir清的是allure-results不是allure-report。生成的報(bào)告目錄是另一個(gè)命令產(chǎn)出的兩者的清理邏輯要分開看。5.2 generate、serve、open 三個(gè)命令該在什么場(chǎng)景用allure 命令行提供了三個(gè)容易混淆的子命令用錯(cuò)場(chǎng)景會(huì)覺得別扭命令作用適用場(chǎng)景allure serve results起一個(gè)本地服務(wù)臨時(shí)渲染并打開開發(fā)調(diào)試看完就關(guān)allure generate results -o report把結(jié)果渲染成靜態(tài)站點(diǎn)歸檔、CI 產(chǎn)物、需要分享allure open report起服務(wù)打開已生成的報(bào)告目錄已生成報(bào)告后本地查看生成靜態(tài)報(bào)告allure generate ./allure-results -o ./allure-report --clean--clean會(huì)在生成前清空目標(biāo)目錄。這個(gè)參數(shù)和上面的--clean-alluredir不是一回事別混。最常用的是allure serve一條命令直接看到結(jié)果allure serve ./allure-results它會(huì)臨時(shí)起一個(gè) HTTP 服務(wù)并在瀏覽器打開。缺點(diǎn)是關(guān)掉終端就沒了而且如果報(bào)告里附件很多每次都要重新渲染一遍稍慢。日常調(diào)試用它要留檔就用generate。5.3 讓趨勢(shì)圖不丟history 目錄的手動(dòng)搬運(yùn)趨勢(shì)圖Trends是 allure 報(bào)告里很有價(jià)值的一塊能看到通過率的走勢(shì)。但很多人會(huì)發(fā)現(xiàn)它永遠(yuǎn)是空的。原因在于趨勢(shì)數(shù)據(jù)不是從allure-results里推出來的而是從上一次生成的報(bào)告里的 history 目錄繼承來的。也就是說allure generate的時(shí)候它會(huì)去allure-report/history找歷史數(shù)據(jù)處理完再輸出到新的history目錄。如果你每次都加--clean或者每次都換一個(gè)新的輸出目錄那歷史就被清掉了趨勢(shì)自然斷。正確的做法是在生成新報(bào)告之前把上一次的 history 拷到這次的 results 目錄里cp -r ./allure-report/history ./allure-results/ 2/dev/null || true allure generate ./allure-results -o ./allure-report --clean這段邏輯在 CI 里通常寫成腳本。第一次跑的時(shí)候 history 不存在所以要容忍失敗加個(gè)|| true或者做個(gè)存在性判斷。這個(gè)技巧很多教程不會(huì)寫但在實(shí)際做持續(xù)集成的時(shí)候是必需的不然趨勢(shì)圖永遠(yuǎn)是一條空線。5.4 報(bào)告里的 environment 與分類信息怎么補(bǔ)報(bào)告右上角可以放環(huán)境信息方法是往allure-results目錄里放一個(gè)environment.propertiesBase.URLhttps://api.example.com Python3.11.5 Envstaging Run.Bynightly-job這個(gè)文件在allure generate的時(shí)候會(huì)被讀取。注意它必須放在 results 目錄里放在 report 目錄里是沒用的。而且如果用了--clean-alluredir每次 pytest 運(yùn)行前目錄被清空這個(gè)文件也就沒了。處理辦法是在 pytest 的 session 級(jí) fixture 里動(dòng)態(tài)寫或者干脆不用--clean-alluredir改成跑完 pytest 之后自己刪舊文件再補(bǔ)上。還有一個(gè)categories.json用來把失敗按規(guī)則歸類比如斷言失敗歸一類、超時(shí)歸一類。格式大致是[ { name: 斷言失敗, matchedStatuses: [failed], messageRegex: .*AssertionError.* } ]同樣放在 results 目錄里。對(duì)于用例量大、失敗類型雜的項(xiàng)目這個(gè)文件能把報(bào)告的可讀性提升一個(gè)檔次。6. PyCharm 場(chǎng)景下的特殊處理PyCharm 是很多人跑 pytest 的主力環(huán)境它和終端環(huán)境之間的變量繼承差異是 Mac 上尤其突出的一個(gè)坑。6.1 終端通、Run 不通的根因現(xiàn)象很明確PyCharm 底部的 Terminal 里敲allure serve ./allure-results完全正常但點(diǎn)某個(gè)用例旁邊的綠色三角或者右鍵 Run報(bào)錯(cuò)說找不到 allure 或者 PATH 不對(duì)。根因有兩條。一是 GUI 啟動(dòng)的 PyCharm 本身就是從 launchd 繼承環(huán)境可能拿不到~/.zshrc里的導(dǎo)出。二是即使 PyCharm 拿到了它的 Run Configuration 是獨(dú)立配置的不一定繼承 Terminal 的 shell 環(huán)境。這兩條疊在一起就出現(xiàn)了同一個(gè)軟件里表現(xiàn)不一致。6.2 三種讓 Run Configuration 拿到 PATH 的辦法按侵入性從低到高排列第一種是在 Run Configuration 里手工加環(huán)境變量。打開 Run/Debug Configurations找到對(duì)應(yīng)的 pytest 配置在 Environment variables 那一欄點(diǎn)開把PATH或者ALLURE_HOME顯式填進(jìn)去。適合只有一兩個(gè)配置、改動(dòng)不頻繁的情況。第二種是裝 EnvFile 插件。它支持指定一個(gè).env文件PyCharm 啟動(dòng)進(jìn)程時(shí)會(huì)自動(dòng)把這些變量注入。好處是配置文件可以進(jìn)版本庫(kù)團(tuán)隊(duì)共享?yè)Q機(jī)器不用重配。代價(jià)是多了一個(gè)插件依賴。第三種是從終端啟動(dòng) PyCharm。在命令行里執(zhí)行open -a PyCharm或者直接跑 PyCharm 的可執(zhí)行文件。這樣啟動(dòng)的 PyCharm 會(huì)繼承當(dāng)前 shell 的全部環(huán)境Run Configuration 里就不用額外配了。缺點(diǎn)是每次都要走終端用 Dock 圖標(biāo)點(diǎn)開的時(shí)候不生效容易忘。我個(gè)人的習(xí)慣是第三種加上在~/.zshrc里把配置寫規(guī)整日常用 Dock 啟動(dòng)遇到問題時(shí)用終端啟動(dòng)一次對(duì)比一下是不是環(huán)境問題這個(gè)對(duì)比動(dòng)作本身就能快速定位。6.3 路徑里帶空格和中文引發(fā)的解析問題這一點(diǎn)在 Windows 的 PyCharm 上特別常見。項(xiàng)目放在類似這樣的路徑下C:\Users\張三\我的項(xiàng)目\自動(dòng)化測(cè)試然后allure generate報(bào)錯(cuò)或者生成的報(bào)告打開是空白的。原因和前面講的 allure 腳本拼 classpath 是同一類問題——路徑里的空格和中文在某些環(huán)節(jié)沒有被正確引用或者編碼。處理辦法很直接把 allure 命令行工具裝在純英文無(wú)空格的目錄前面已經(jīng)建議了D:\devtools\allure-2.27.0項(xiàng)目本身的路徑也盡量保持英文。如果項(xiàng)目路徑動(dòng)不了至少保證輸出目錄是干凈的比如--alluredirD:\allure-out避開項(xiàng)目路徑里的空格。另外注意相對(duì)路徑./allure-results在不同工具里的工作目錄可能不一樣。PyCharm 的 Run Configuration 默認(rèn)工作目錄是項(xiàng)目根但從 Terminal 里跑的時(shí)候可能是別的地方。如果出現(xiàn)報(bào)告生成了但找不到的情況把路徑改成絕對(duì)路徑先跑通再說。7. 排錯(cuò)清單把裝完了但沒用按癥狀切開前面各節(jié)散著講了很多問題這里做一個(gè)集中對(duì)照方便出問題的時(shí)候快速定位。7.1 癥狀對(duì)照表癥狀大概率原因優(yōu)先檢查allure命令找不到PATH 未生效或未重開終端重開終端、echo $PATH報(bào)找不到主類路徑含空格classpath 被截?cái)郺llure 安裝目錄路徑JVM 啟動(dòng)失敗JAVA_HOME指向錯(cuò)誤java -version、echo $JAVA_HOMEjava -version版本不對(duì)PATH 被 javapath 搶占where java報(bào)告生成但空白allure-results為空是否裝了allure-pytest、是否傳了--alluredir報(bào)告里有已刪除的用例results 目錄殘留加--clean-alluredir趨勢(shì)圖永遠(yuǎn)為空history 未繼承拷貝上一次 report 的 history終端通、IDE 不通GUI 應(yīng)用未繼承 shell 環(huán)境Run Configuration 的環(huán)境變量這張表能覆蓋絕大部分場(chǎng)景。遇到問題時(shí)先對(duì)號(hào)入座比漫無(wú)目的地搜教程要快。7.2 一個(gè)多版本沖突的排查過程復(fù)原講一個(gè)我實(shí)際遇到的情況。機(jī)器上先后裝過兩個(gè) JDK一個(gè) 8一個(gè) 17另外裝了某個(gè)帶 Java 的桌面軟件。表現(xiàn)是cmd 里java -version顯示 1.8allure --version卻報(bào)主類錯(cuò)誤。排查過程是這樣的。第一步where java輸出三行第一行是那個(gè)桌面軟件目錄下的java.exe第二行才是 JDK 8 的。也就是說java -version顯示的 8 其實(shí)來自別處不是我以為的那個(gè)。第二步echo %JAVA_HOME%指向的是 JDK 17 的目錄。這就出現(xiàn)了矛盾PATH 里排第一的 java 是 8但JAVA_HOME指向 17。allure 啟動(dòng)腳本優(yōu)先用JAVA_HOME所以它用 17 去跑但那個(gè)腳本里可能還引用了別的東西導(dǎo)致混亂。第三步把 PATH 里那個(gè)桌面軟件的 java 路徑刪掉同時(shí)把%JAVA_HOME%\bin上移重開終端。問題解決。這個(gè)案例的價(jià)值在于java -version和JAVA_HOME是兩個(gè)獨(dú)立的信號(hào)源工具可能優(yōu)先讀其中一個(gè)也可能兩個(gè)都讀。排查時(shí)必須分別確認(rèn)不能看了一個(gè)就下結(jié)論。7.3 升級(jí)與版本匹配的建議最后說版本。allure-pytest和 allure 命令行是兩條獨(dú)立的版本線它們之間靠allure-results里的數(shù)據(jù)格式溝通。設(shè)計(jì)上是向前兼容的但有一個(gè)最低要求命令行工具太舊的話插件新加的標(biāo)簽和步驟渲染不出來。實(shí)用建議是命令行版本保持在 2.20 以上allure-pytest保持在 2.9 以上。團(tuán)隊(duì)里最好把這兩個(gè)版本都寫進(jìn)文檔或者寫進(jìn)requirements.txt和構(gòu)建腳本避免出現(xiàn)我本地報(bào)告正常、CI 上少了幾塊的詭異差異。升級(jí)的時(shí)候不要只升一邊兩個(gè)一起升升完拿一份歷史結(jié)果跑一遍回歸確認(rèn)渲染沒問題再推到團(tuán)隊(duì)里用。環(huán)境變量這部分我個(gè)人在幾臺(tái)機(jī)器上來回折騰之后的體會(huì)是把它當(dāng)成一條鏈路來看待Java 是一環(huán)allure 命令行是一環(huán)pytest 插件是第三環(huán)任何一環(huán)斷了都會(huì)表現(xiàn)為allure 用不了。每次出問題不要急著改配置先用where javaWindows或/usr/libexec/java_home -VMac、allure --version、pytest --collect-only這三條命令把三環(huán)各自的現(xiàn)狀確認(rèn)一遍問題基本會(huì)自己浮出來。另外有個(gè)小技巧值得留著在~/.zshrc或者 Windows 的用戶變量里把ALLURE_HOME和JAVA_HOME都配上不要只配 PATH因?yàn)橛行┠_本和插件會(huì)去讀這兩個(gè)變量做路徑推導(dǎo)只配 PATH 的時(shí)候它們會(huì)靜默失敗不報(bào)錯(cuò)也不生效排查起來極其費(fèi)勁。