2026 年如何自動測試 Vercel Preview 部署

簡短回答

您不需要新增工作流程檔案，也不需要撰寫從建置紀錄中擷取 Preview URL 的腳本。TestSprite 以 GitHub App 的形式安裝，監聽您的流水線早已產生的部署事件，依您設定一次的模式推算出 Preview URL，對其執行測試，並將結果以留言形式張貼回 Pull Request。

設定大約需要十分鐘，需要具備安裝 GitHub App 的管理員權限，且不需要變更您的儲存庫。

前提條件：確認 Pull Request 會產生部署

TestSprite 是由部署事件觸發，因此該事件必須先存在，其他一切才會運作。開啟任何現有的 Pull Request，確認上面列出了附帶可點擊 URL 的部署，然後開啟該 URL，檢查 Preview 環境確實能載入。

在 Vercel 上，這會顯示為 Pull Request 上的機器人留言，列出專案名稱、Ready 狀態，以及 Preview 連結。AWS Amplify、Netlify，以及會建立 GitHub 部署的自架流水線，都會以各自的格式產生相同的訊號——重點在於部署確實存在，且其 URL 可以連上。

步驟 1——將 GitHub 連接到您的工作區

這是每個工作區僅需執行一次的設定。在 TestSprite 中，前往Workspace Settings → Integrations，找到 GitHub 這一列，點選Connect。系統會將您導向 GitHub，選擇擁有該儲存庫的組織或個人帳號，接著選擇All repositories 或 Only select repositories，並點選Install & Authorize。

在核准之前，值得先了解所請求的權限：

寫入權限用於將測試結果回貼到您的 Pull Request 與 Commit 上。TestSprite 不會推送 Commit，也不會修改您的工作流程檔案。如果安裝過程中未列出您的組織，代表您沒有為該組織安裝 GitHub App 的權限——需要組織擁有者核准。

步驟 2——將儲存庫連接到專案

開啟您想要連接的 TestSprite 專案，前往GitHub Action 分頁，點選Connect GitHub Action。接著選擇測試該如何被觸發：

一個觸發條件就足以開始。您也可以兩者都建立——它們會各自獨立運作。

步驟 3——選擇代表「部署完成」的事件

選擇Pull Request 分頁，貼上一個已有可運作 Preview 部署的現有 Pull Request 的 URL，然後點選Detect Events。TestSprite 會列出它在該 Pull Request 上找到的 CI/CD 事件——GitHub Actions 檢查、來自 Vercel 或 Amplify 的機器人留言、工作流程執行——由您選擇由哪一個來啟動測試執行。

請選擇在部署上線、URL 可連上之後才觸發的事件。這是設定出錯最常見的原因：若事件在建置開始時就觸發，測試就會針對尚未就緒的 URL 執行，導致每個測試都失敗。

步驟 4——填入目標 URL 模式

每家託管服務商命名 Preview URL 的方式都不同，因此您需要告訴 TestSprite 如何為任一 Pull Request 建構出 URL。有五種佔位符可供使用：

請將此模式與實際的 Preview URL 逐字元比對：

Vercel 預設的 Preview 主機名稱是根據分支建立的，這也是為什麼在此通常應使用 {branch-slug} 而非 {pr} 作為佔位符。如果您的託管服務商產生的是完全不可預測的隨機子網域，請為 Preview 環境設定一個穩定的別名 URL，並改用該別名。

Push 觸發完全不需要模式——它會針對您所選 TestSprite 環境所設定的 URL 執行，因此 dev 請選擇 Dev，main 請選擇 Production。

步驟 5——儲存前先送出測試事件

點選Send Test Event。這會像真正的觸發一樣，針對範例 Pull Request 執行您的測試，讓您能在正式套用前預覽整個流程。等候大約 30 秒後，回到 GitHub 上的 Pull Request——會看到出現一則 TestSprite 留言。

在繼續下一步之前，請先開啟該留言中的 URL。確認該連結可以連上，且指向您預期的環境。如果不正確，請修正模式並再送出一次測試事件，不要等到下一個 Pull Request 才發現問題。測試執行完成後，TestSprite 會在同一則留言中更新結果。

當測試事件看起來正確後，點選Create Trigger。它會出現在Triggers 清單中，標示為 Active，並在未來每個 Pull Request 上自動執行。有兩個選用切換開關值得謹慎設定：

如果您的 Preview 位於 Deployment Protection 之後

這是一種看起來像設定成功、實則失敗的情況。啟用 Vercel 的 Deployment Protection 後，每個 Preview URL 都會位於驗證關卡之後，外部測試者收到的會是登入頁面，而不是您的應用程式。測試不會出現錯誤——它們只是描述了一個誰也沒預期到的頁面。

步驟 5 中的檢查可以抓出這個問題：在無痕視窗中開啟 TestSprite 留言中的 URL。如果看到 Vercel 登入畫面，就代表保護功能已啟用。接下來有兩種做法：停用該 Preview 環境的保護功能，或使用 Vercel 的 Protection Bypass for Automation，它會產生一組密鑰，Vercel 會將其接受為 x-vercel-protection-bypass 查詢參數或標頭。由於目標 URL 模式本身就是一個 URL，查詢參數的形式可以直接附加在後面：

https://app-git-{branch-slug}-team.vercel.app?x-vercel-protection-bypass=YOUR_SECRET

請在 Project Settings → Deployment Protection → Protection Bypass for Automation 下產生此密鑰。這一步請務必謹慎——它會將繞過密鑰儲存在設定欄位中，因此若您的 Preview 環境不含任何敏感內容，停用保護功能會是更乾淨的做法。

解讀結果

測試執行完成後，TestSprite 會以結果更新其 Pull Request 留言——或 Commit 檢查。留言的結構固定，如果程式碼是由 AI 代理撰寫的，最後一列會是最重要的資訊：

每個結果都會連回 TestSprite 中的完整報告。

驗證您的設定

在您依賴此整合功能之前，請確認以下五點：

1. 工作區中的 GitHub 整合顯示為Connected

2. 該儲存庫出現在專案的GitHub Action 分頁中

3. 已列出一個觸發條件並已啟用

4. 測試事件已產生 TestSprite 留言（Pull Request）或檢查（Push）

5. 該留言或檢查中的 URL 可開啟正確的已部署環境

疑難排解

命令列替代方案

當您的流水線已經會產生部署時，GitHub App 是最適合的做法。如果您想改由自己的工作流程來驅動測試執行——或者您根本不是使用 GitHub——開源的 TestSprite CLI 可以在任何 CI 系統中完成相同的工作。它可免費安裝，並採用 Apache-2.0 授權：

npm install -g @testsprite/testsprite-cli
testsprite setup

將專案指向您已經解析好的 URL，並執行整套測試以取得結果：

testsprite project update prj_abc123 --url "$PREVIEW_URL"
testsprite test run --all --project prj_abc123 --wait --output json
#   exit 0 = everything passed, exit 1 = something is broken

testsprite ci init github 會為此路徑產生一份工作流程範本，而該 CLI 只需要環境中有 TESTSPRITE_API_KEY，因此同樣可以輕鬆用於 CircleCI、GitLab、Jenkins 或 Azure Pipelines。使用 --report junit --report-file <path> 可產生這些系統原生支援匯入的附加報告。

如果您在意的流程位於應用程式自身的登入機制之後，可以在專案中儲存一組測試帳號，讓測試執行時能夠登入驗證。以下兩個參數必須一起使用：

testsprite project update prj_abc123 \
  --username qa@example.com \
  --password-file ./.secrets/qa-password

常見問題