測試

設定

送出變更之前，先在你的電腦上檢查。

開始之前

先完成設定開發環境。Go 測試會提供已建置的 Web App，所以要先建置它。

安裝一次測試用的瀏覽器：

npx --prefix app/frontend playwright install chromium

執行日常檢查

建置並檢查 Go 程式碼：
Terminal window
```
go build ./...
go vet ./...
```
執行 Go 測試：
Terminal window
```
go test ./...
```

檢查並測試 Web App：

npm --prefix app/frontend run check
npm --prefix app/frontend run lint
npm --prefix app/frontend run test

執行層級與檔案配置的規則：

go test -tags structure ./app/backend/tools/structurecheck

你應該不會看到任何失敗。CI 執行的是同樣的指令，Go 的部分在 amd64 和 arm64 上執行，另外還會用 race detector 跑一次（go test -race ./...）。

執行端對端測試

端對端測試會用真實的瀏覽器操作真實的程式。執行你改動的那一塊對應的 project：

npm --prefix app/frontend run e2e -- --project=movies

每次執行都會用全新的設定資料夾啟動它自己的 HolyArrs。setup project 會先建立擁有者，大部分其他 project 都要等它。發布新版之前，不加 --project 執行完整的測試套件。

選項

要執行哪些 project

你改了	執行
電影	`movies`
影集	`shows`
請求	`requests`、`lists`、`reports`
下載	`sources`、`downloaders`、`downloads`
登入與使用者	`accounts`、`kid`
健康狀態與排程	`schedules`、`controls`
頁面版面	`desktop`、`phone`、`a11y`

Project 的名稱定義在 app/frontend/playwright.config.ts。依賴另一個 project 的，會先執行那一個。

新測試放在哪裡

種類	位置
Go	放在它所測試的檔案旁邊
Web 單元測試	放在它的檔案旁邊，命名為 `name.test.ts`
端對端	`app/tests/<module>/`

絕不要呼叫真實的外部服務。在 app/tests/fakes 底下加一個替身。只有在你的電腦上才會通過的測試，就是壞掉的測試。

如果沒有成功

症狀。 結構檢查失敗。 原因。 訊息會指出檔案和你違反的規則。 解決方式。 移動程式碼，或由較高的模組把單純的資料傳進來。見模組。

症狀。 端對端測試無法啟動。 原因。 沒有安裝測試用的瀏覽器。 解決方式。 執行上面那行 playwright install。

症狀。 Go 測試因為找不到頁面而失敗。 原因。 Web App 沒有建置。 解決方式。 執行 npm --prefix app/frontend run build。

給進階使用者

建置 tag

帶有 tag 的測試在一般的 go test ./... 裡會被跳過。傳入 -tags <tag> 才會執行它。

Tag	內容
`structure`	`tools/structurecheck` 裡的層級、檔案配置、SQL 位置和註解規則
`measure`	下載計時檢查
`lab`	在測試實驗室裡針對真實 App 的測試。它們會讀取 `HOLYARRS_LAB_*`，沒設定時就跳過
`labms`、`livesubs`	針對媒體伺服器和線上字幕網站的 lab 執行

長時間與 fault 執行

CI 會在一般測試之外執行這些。發布新版之前請先執行。

go test -count=1 -run '^TestFault|^TestCrashInEveryLoopIsContained$' ./app/backend/cmd/holyarrs
HOLYARRS_RESTART_TIMING=1 go test -count=1 -run '^TestCrashRestartTime$' ./app/backend/cmd/holyarrs
HOLYARRS_MEMORY=1 go test -count=1 -timeout 30m -run '^TestMemoryPartsRuns$' ./app/backend/cmd/holyarrs
go test -count=1 -run '^TestDownloaderConformance$' ./app/backend/internal/downloads

變數	作用
`HOLYARRS_FAULT_OUT`	fault 執行寫入它的表格的檔案
`HOLYARRS_RESTART_TIMING`、`HOLYARRS_RESTART_TIMING_OUT`	開啟從當機到登入的計時，並指定它的輸出檔案
`HOLYARRS_MEMORY`、`HOLYARRS_MEMORY_OUT`	開啟記憶體執行，並指定它們的輸出檔案
`HOLYARRS_CRASH_RUNS`、`HOLYARRS_CRASH_SEED`	`app/backend/internal/mediafiles/dbtests`（`crash_test.go`）裡當機迴圈的回合數和種子；在 `-short` 下會跳過

替身伺服器與變數

端對端測試會為下載器、來源和 metadata 伺服器啟動替身伺服器，所以沒有任何測試會碰到真實的服務。測試會設定 HOLYARRS_TMDB_URL、HOLYARRS_MUSICBRAINZ_URL、HOLYARRS_PLEX_URL 和 HOLYARRS_QBITTORRENT_URL 這類變數，讓程式指向它們。正式安裝從來不需要這些。

API 契約有它自己的測試。當 openapi.json 和路由不一致時，TestOpenAPIGenerated 會失敗；tools/structurecheck/testdata 裡的路由表快照，則會在有任何路由被新增、移除或移動時失敗。