Prisma 測試終極指南：CI Pipeline

目錄

• 目錄
• 簡介
  • 什麼是持續整合 Pipeline？
  • 您將使用的技術
• 先決條件
  • 假設知識
  • 開發環境
  • 複製儲存庫
• 設定您自己的 GitHub 儲存庫
• 設定工作流程
• 新增單元測試任務
• 新增整合測試任務
• 新增端對端測試任務
• 摘要與最終想法

簡介

當您來到本系列的結尾時，請退後一步，思考一下您在過去四篇文章中完成了什麼。您

1. 模擬 Prisma Client
2. 了解並編寫了單元測試
3. 了解並編寫了整合測試
4. 了解並編寫了端對端測試

您學到的測試策略和概念將使您能夠編寫程式碼，並在現有程式碼庫中驗證新的變更是否如您所希望和預期的那樣運作。

這種安心感非常重要，尤其是在大型團隊中。然而，您所學到的知識中存在一個粗糙的邊緣：需要 _手動_ 執行測試，因為您會進行變更。

在本文中，您將學習自動化測試的執行，以便對程式碼庫的變更將在對主要分支提出 Pull Request 時自動進行測試。

什麼是持續整合 Pipeline？

持續整合 Pipeline 描述了一組必須在發布軟體新版本之前完成的步驟。您可能已經看過或聽過 CI/CD 這個縮寫，它指的是 _持續整合_ 以及 _持續部署_。通常，這些個別概念是通過 Pipeline（例如您今天將看到的 Pipeline）來處理的。

就本文而言，您將主要關注 _CI_ 部分，您將在其中建置、測試並最終合併您的程式碼。

有許多技術允許您設定 Pipeline，而選擇使用哪種技術通常取決於您使用的技術堆疊。例如，您可以在以下項目中設定 Pipeline：

• Jenkins
• CircleCI
• GitLab
• AWS CodePipeline
• 還有更多...

在本文中，您將學習如何使用 GitHub Actions 定義您的 Pipeline，這將允許您將 Pipeline 設定為在您建立對主要分支的 Pull Request 時針對程式碼變更執行。

您將使用的技術

• Node.js
• GitHub Actions
• Docker
• Postgres
• PNPM

先決條件

假設知識

在執行以下步驟時，以下知識會很有幫助

• Git 的基本使用知識
• Docker 的基本理解

開發環境

要跟著提供的範例進行操作，您需要具備

• Node.js 已安裝
• 您選擇的程式碼編輯器 (我們建議使用 VSCode)
• Git 已安裝
• pnpm 已安裝
• Docker 已安裝

本系列大量使用此 GitHub 儲存庫。請務必複製該儲存庫。

複製儲存庫

在您的終端機中，前往您儲存專案的目錄。在該目錄中執行以下命令

上面的命令會將專案複製到名為 testing_mono_repo 的資料夾中。該儲存庫的預設分支是 main。

您需要切換到 e2e-tests 分支，其中包含先前文章中的完整端對端測試設定

一旦您複製了儲存庫並檢查出正確的分支，就涉及到設定專案的幾個步驟。

首先，安裝 node_modules

接下來，在專案的根目錄建立一個 .env 檔案

將以下變數新增到該新檔案

在 .env 檔案中，新增了以下變數

• API_SECRET：提供驗證服務用來加密密碼的 _密鑰_。在真實世界的應用程式中，此值應替換為具有數字和字母字元的長隨機字串。
• DATABASE_URL：包含資料庫的 URL。
• VITE_API_URL：Express API 的 URL 位置。

設定您自己的 GitHub 儲存庫

為了開始設定要在 GitHub Actions 中執行的 Pipeline，您首先需要您自己的 GitHub 儲存庫，其中包含一個 main 分支，以便提交 Pull Request。

前往 GitHub 網站並登入您的帳戶。

注意：如果您還沒有 GitHub 帳戶，可以在這裡免費建立一個。

登入後，按一下下方指示的 New 按鈕以建立新的儲存庫

在下一個頁面上，系統會要求您提供有關儲存庫的一些資訊。填寫下方指示的欄位，然後按一下頁面底部的 Create repository 按鈕

然後，您將被導航到新儲存庫的首頁。頂部會有一個文字欄位，可讓您複製儲存庫的 URL。按一下複製圖示以複製 URL

現在您有了新 GitHub 儲存庫的 URL，請前往終端機中程式碼庫的根目錄，並變更專案的 _origin_ 以使用以下命令指向新儲存庫（請務必在第二行中插入您剛複製的 URL）

您將在 e2e-tests 分支的進度上進行工作，因此該分支應被視為 main。將 e2e-tests 合併到 main 中

最後，將專案推送到您的新儲存庫

設定工作流程

您現在已設定好儲存庫，可以將變更推送至該儲存庫。下一個目標是在針對您已建立的 main 分支建立或更新 Pull Request 時觸發一組任務。

使用 GitHub 時，您可以建立 工作流程 檔案來定義這些步驟。這些檔案必須在專案根目錄中的 .github/workflows 資料夾中建立。

在您的專案中建立一個名為 .github 的新資料夾

在 .github/workflows 資料夾中，建立一個新檔案，您將在其中定義名為 test.yml 的測試工作流程

在此檔案中，您將提供 GitHub Actions 應採取的步驟，以準備您的專案並執行您的測試套件。

若要開始此工作流程，請使用 name 屬性為您的工作流程命名

工作流程現在將在 GitHub 中顯示為 'Tests'。

接下來要做的，是將此工作流程設定為僅在針對儲存庫的 main 分支建立 Pull Request 時執行。新增具有以下選項的 on 關鍵字以完成此操作

注意：請注意縮排。縮排在 YAML 檔案中非常重要，不正確的縮排會導致檔案失敗。

現在您已命名您的工作流程，並將其設定為僅在針對 main 建立或更新 Pull Request 時執行。接下來，您將開始定義一個執行單元測試的任務。

注意：在工作流程檔案中有很多選項可以設定，這些選項會變更工作流程的執行方式、工作流程的作用等等... 如需完整清單，請查看 GitHub 的文件。

新增單元測試任務

若要定義與工作流程中特定任務（稱為 _步驟_）相關的一組指示，您將使用 job 關鍵字。每個任務都在您設定的隔離環境中執行其步驟集。

將 jobs 區段新增到 .github/workflows/tests.yml 檔案，並指定一個名為 unit-tests 的任務

如先前所述，每個個別任務都在其自己的環境中執行。為了執行任務，您需要指定應在何種類型的機器中執行該任務。

使用 runs-on 關鍵字指定任務應在 ubuntu-latest 機器上執行

您將定義以設定單元測試任務的最後一個區段是 steps 區段，您將在其中定義任務應採取的步驟集，以執行您的單元測試。

將以下內容新增到 unit-tests 任務

這定義了一個具有一個步驟的 steps 區段。該步驟使用名為 actions/checkout 的預先建置 _動作_ 的 v3 版本，該版本會檢查出您的 GitHub 儲存庫，以便您可以在任務內與其互動。

注意：動作 是您可以在工作流程中使用的個別步驟集。它們可以協助將可重複使用的步驟集分解為單一檔案。

接下來，您需要定義一組步驟，以在虛擬環境中安裝 Node.js、安裝 PNPM，並安裝儲存庫的套件。

您建立的每個測試任務都需要這些步驟，因此您將在可重複使用的自訂動作中定義這些步驟。

在 .github 目錄中建立一個名為 actions 的新資料夾，並在 .github/actions 資料夾中建立一個 build 資料夾

然後在 .github/actions/build 中建立一個名為 action.yml 的檔案

在該檔案中，貼上以下內容

此檔案定義了一個 複合動作，可讓您在任務中使用此動作中定義的 steps。

您新增的上述步驟執行以下操作：

1. 在虛擬環境中設定 PNPM
2. 在虛擬環境中設定 Node.js
3. 在儲存庫中執行 pnpm install 以安裝 node_modules

現在已定義此可重複使用的動作，您可以在主工作流程檔案中使用它。

回到 .github/workflows/tests.yml，使用 uses 關鍵字來使用該自訂動作

此時，任務將檢查出儲存庫、設定虛擬環境並安裝 node_modules。剩下的就是要實際執行測試。

新增最後一個步驟，執行 pnpm test:backend:unit 以執行單元測試

注意：請注意，您使用 name 關鍵字將這個新步驟命名為 'Run tests'，並使用 run 關鍵字執行了任意命令。

此任務現在已完成並準備好進行測試。為了進行測試，請先將此程式碼推送至您儲存庫中的 main 分支

工作流程現在已在 main 分支上定義。但是，只有在您針對該分支提交 Pull Request 時，才會觸發工作流程。

建立一個名為 new-branch 的新分支

在該新分支中，透過在 backend/src/index.ts 檔案中新增註解來進行微小變更

現在提交並將這些變更推送至遠端儲存庫。儲存庫目前不知道 new-branch 分支，因此您需要指定 _origin_ 應使用名為 new-branch 的分支來處理這些變更

新分支現在可在遠端儲存庫上使用。建立 Pull Request 以將此分支合併到 main 分支中。

前往瀏覽器中的儲存庫。在頁面頂部的 Pull requests 索引標籤中，您應該會看到 Compare & pull request 按鈕，因為 new-branch 最近有推送

按一下該按鈕以開啟 Pull Request。您應該會被導航到一個新頁面。在新頁面上，按一下 Create pull request 按鈕以開啟 Pull Request

開啟 Pull Request 後，您應該會在 Merge pull request 按鈕上方看到一個黃色方塊，顯示您的 Tests 任務正在執行

如果您按一下 Details 按鈕，您應該會看到每個步驟都在執行及其主控台輸出。

任務完成後，您將收到通知，告知您的工作流程中的檢查是否通過

現在您的單元測試任務已完成，您將繼續建立執行整合測試的任務。

注意：請勿立即合併此 Pull Request！您將在本文的其餘部分重複使用此 Pull Request。

新增整合測試任務

執行整合測試的過程將與執行單元測試的方式非常相似。此任務的不同之處在於，您的整合測試依賴於測試資料庫和環境變數。在本節中，您將設定這些項目，並定義一個任務來執行您的測試。

在開始進行變更之前，您需要再次檢查出儲存庫的 main 分支

首先將 unit-tests 任務複製到名為 integration-tests 的新任務中。此外，在此任務的最後一個步驟中，將 pnpm test:backend:unit 替換為 pnpm test:backend:int

有了這個，您已經擁有運行測試所需的大部分組件，但是按原樣運行工作流程將觸發 scripts/run-integration.sh 檔案的運行。該腳本使用 Docker Compose 來啟動測試資料庫。

GitHub Actions 使用的虛擬環境預設不附帶 Docker Compose。為了使其正常運作，您將設定另一個自訂動作，將 Docker Compose 安裝到環境中。

在 .github/actions 中建立一個名為 docker-compose 的新資料夾，並在其內部建立一個名為 action.yml 的檔案

此動作應執行兩項操作：

1. 將 Docker Compose 外掛程式下載到虛擬環境中
2. 使外掛程式可執行，以便可以使用 docker-compose 命令

將以下內容貼到 .github/actions/docker-compose/action.yml 中以處理這些任務

上面程式碼片段中的第一個步驟將 Docker Compose 外掛程式來源下載到虛擬環境中的 /usr/local/bin/docker-compose。然後，它使用 chmod 將此來源設定為可執行檔案。

自訂動作完成後，在 .github/workflows/tests.yml 中的 integration-tests 任務中，在執行測試的步驟之前新增它

此測試最後需要的是一組環境變數。您的應用程式預期的環境變數是

• DATABASE_URL：資料庫的 URL
• API_SECRET：用於簽署 JWT 的驗證密碼
• VITE_API_URL：Express API 的 URL

您可以使用 env 關鍵字將這些新增到虛擬環境中。環境變數可以新增到工作流程層級，這會將它們應用於每個任務，也可以新增到特定任務。在您的情況下，您將在工作流程層級新增它們，以便變數在每個任務中都可用。

注意：通常，最佳做法是僅將所需的環境變數單獨公開給每個任務。在本文中，為了簡單起見，變數將公開給每個任務。

將 env 鍵新增到您的工作流程，並定義您需要的三個變數

此時，您可以提交這些變更並將其推送至 main 分支，以發布對工作流程的變更

然後執行以下命令將這些變更合併到 new-branch 分支中，以觸發工作流程的新執行

注意：在 git merge main 步驟中，您將在終端機中進入編輯器。按下 :qa 和 enter 以退出該編輯器。

此任務將比單元測試任務花費更多時間，因為它必須安裝 Docker Compose、啟動資料庫，然後執行所有測試。

任務完成後，您應該會看到以下成功訊息

新增端對端測試任務

現在單元測試和整合測試正在工作流程中運行，要定義的最後一組測試是端對端測試。

首先，再次檢查出 main 分支以變更工作流程檔案

與上一節的開始方式類似，將 integration-tests 任務的內容複製到名為 e2e-tests 的新任務中，將 pnpm backend:tests:int 替換為 pnpm test:e2e

在提交新任務之前，有幾件事要做

• 在虛擬環境中安裝 Playwright 及其測試瀏覽器
• 更新 scripts/run-e2e.sh

在此任務中安裝 Docker Compose 的步驟之後，立即新增兩個新步驟，在專案的 e2e 資料夾中下載 Playwright 並安裝其測試瀏覽器

您還需要將兩個新的環境變數新增到 env 區段，Playwright 將在安裝 Playwright 時使用

現在，當工作流程運行時，Playwright 應已正確安裝和設定，以允許您的測試運行。

接下來要變更的是 scripts/run-e2e.sh 腳本運行端對端測試的方式。

目前，當端對端測試完成運行時，腳本將使用 npx playwright show-report 自動提供產生的報告。在 CI 環境中，您不希望發生這種情況，因為這會導致任務無限期地運行，直到手動取消為止。

從腳本中移除該行

解決該問題後，您現在可以將變更推送至 main，並將這些變更合併到 new-branch 分支中

如果您回到瀏覽器中的 Pull Request，您現在應該會在檢查中看到三個任務正在運行。

新任務將需要很長時間才能完成，因為它必須下載 Docker Compose 和 Playwright 的瀏覽器、啟動資料庫並執行所有測試。

任務完成後，您應該會看到已完成的成功測試清單

摘要與最終想法

在本文中，您了解了持續整合。更具體地說，您了解了

• 什麼是持續整合
• 為什麼它在您的專案中可能很有用
• 如何使用 GitHub Actions 設定 CI Pipeline

最後，您有一個 CI Pipeline，它可以針對與 main 分支的 Pull Request 相關聯的任何分支自動執行您的整個測試套件。

這非常強大，因為它允許您在每個 Pull Request 上設定檢查，以確保相關分支中的變更按預期運作。使用 GitHub 的安全性設定，您也可以在這些檢查不成功時阻止合併到 main 中。

在本系列課程中，您了解了可以針對您的應用程式運行的各種測試、如何針對使用 Prisma 與資料庫互動的函數和應用程式編寫這些測試，以及如何在您的專案中使用這些測試。

如果您對本系列涵蓋的任何內容有任何疑問，請隨時在 Twitter 上與我聯繫。