k6 腳本產生器是做什麼的？

此技能會產生任何人都能執行、理解與修正的 k6 效能測試，即使他們不懂 k6。為此，每個腳本都採用相同的結構，名稱會清楚說明用途，憑證獨立於程式碼之外，並附有 .md 檔案逐一說明每個部分。

團隊的優先事項：負載測試和壓力測試，包括 HTTP 和 k6 browser。煙霧測試始終是前置步驟。

權威來源：官方文件

所有內容都必須與 https://grafana.com/docs/k6/latest/ (k6 v2.x) 保持一致。此技能的參考資料已總結該文件。如果某項內容未涵蓋，或您對某個 API、選項或指標有任何疑問，請查閱官方頁面（在 references/official-docs.md 中有地圖），而不要依賴記憶。網路上許多範例使用舊版 API（k6/experimental/browser、同步瀏覽器、browser_web_vital_fid），這些在 v2 中已無法運作。

參考檔案（僅閱讀您需要的部分）

檔案	何時閱讀
`references/test-types.md`	始終：選擇測試類型、階段設定檔與執行器
`references/thresholds-checks.md`	始終：標準閾值與如何撰寫檢查
`references/http-patterns.md`	API 測試：生命週期、驗證、機密、關聯、資料
`references/browser-patterns.md`	使用 k6 browser 或混合模式的測試
`references/doc-template.md`	撰寫說明 `.md` 時
`references/official-docs.md`	查詢某個主題的官方頁面
`assets/lib/config.js`	直接複製到 `k6/lib/config.js`
`assets/templates/*`	流程、測試、README、`.secrets.example` 的基礎

專案中的標準結構

k6/
├── tests/
│   ├── api/        <類型>-<流程>.js            例如 load-checkout.js, stress-search-products.js
│   └── browser/    <類型>-<流程>-browser.js    例如 load-login-browser.js
├── lib/
│   ├── config.js   (從 assets/lib/config.js 複製)
│   ├── flows/      <流程>.js — 使用者的操作步驟，所有測試類型共用
│   └── pages/      <頁面>-page.js — 頁面物件（僅 browser，若流程包含多個頁面）
├── data/           測試資料 JSON/CSV (絕不存放憑證)
├── docs/           <與腳本同名>.md
├── .secrets.example
└── README.md       (從 assets/templates/k6-README.md 複製，包含腳本索引)

命名規則：kebab-case，加上類型前綴 (smoke-, load-, stress-, spike-, soak-, breakpoint-) + 描述性的業務流程名稱 (checkout, search-products，不要用 test1 或 api)。瀏覽器測試加上 -browser 後綴。.md 檔案與腳本同名。

語言：註解與文件使用繁體中文；程式碼識別符號使用英文。

如果專案已有 k6/ 目錄，請重複使用既有的 config.js、流程和頁面物件，而不是複製它們，並尊重現有內容。

工作流程

1. 理解需求

從使用者的陳述中提取：

測試類型：負載、壓力或其他。如果使用者說「看看能承受多少」或「推到極限」，則是壓力測試（或中斷點測試，如果想知道確切的崩潰點）。如果說「正常負載」或「典型的一天」，則是負載測試。
API、瀏覽器或混合模式。
端點或頁面以及流程順序，如何進行身份驗證，以及每個步驟驗證什麼。
負載量（並發用戶數或請求/秒）、持續時間和 SLA（例如 p95 < 500 毫秒）。
目標環境。

只問那些會阻塞任務且無法合理假設的資訊：如果使用者未提供 URL 或端點，則詢問；如果目標是否為生產環境不明確，一定要詢問。其他事項則使用參考資料中的預設值假設（SLA 500 毫秒、思考時間 1-3 秒、壓力測試 = 負載測試負載量的 2 倍），並在 .md 的「假設」章節中記錄每個假設。如果使用者不知道他們的負載數據，請告訴他們：沒有這些數據，測試回答的問題會與他們關心的問題不同。

2. 準備結構

建立 k6/ 中缺少的部分：lib/config.js（直接複製 assets/lib/config.js）、包含腳本所用金鑰的 .secrets.example、從範本複製的 README.md，並在專案的 .gitignore 中加入：

k6/.secrets
k6/screenshots/

3. 撰寫流程與測試

流程放在 k6/lib/flows/<流程>.js（基礎：assets/templates/flow-api.js）。包含請求、檢查、編號的群組、name 標籤和思考時間。如果流程需要登入，請匯出一個 login() 函式，從 setup() 中呼叫。
測試放在 k6/tests/api/<類型>-<流程>.js（基礎：assets/templates/test-api.js）。僅定義 options（場景 + 閾值）、setup() 和 default()，後者會呼叫流程。階段和閾值必須明確寫在檔案中，每行加上註解。
瀏覽器測試 放在 k6/tests/browser/<類型>-<流程>-browser.js（基礎：assets/templates/test-browser.js）。預設為混合模式：HTTP 負載加上少量瀏覽器 VU。請閱讀 references/browser-patterns.md。
如果 smoke-<流程>.js 不存在，請務必一併產生。 它成本很低（重複使用流程），並且是在負載或壓力測試之前必須執行的第一步。
如果要求壓力測試，但同一個流程的負載測試不存在，請同時產生兩者：官方文件說明壓力測試應在負載測試之後執行，並重複使用其腳本。

以下規則不容協商，因為它們保護團隊和系統：

憑證、令牌和 API 金鑰僅能透過 k6/secrets 傳遞（await secrets.get('名稱')），搭配 --secret-source=file=k6/.secrets 使用。絕不能寫在程式碼、data/、__ENV 的預設值或 console.log 中。
URL 和環境透過 -e BASE_URL / -e TARGET_ENV 傳遞，並從 lib/config.js 讀取。絕不能硬編碼。
不得移除或削弱 config.js 中的生產環境保護機制。
jslib 的 import 必須使用精確版本（請參閱 official-docs.md）。
瀏覽器測試：使用 k6/browser、async 函式、場景中的 options.browser.type: 'chromium'、finally 區塊中的 page.close()、使用 k6-utils 的 check 進行非同步檢查、使用 page.waitForTimeout() 而不是 sleep()。
每個請求都帶有固定的 name 標籤（例如 'GET /items/:id'），這樣帶有 ID 的 URL 就不會導致指標數量爆炸。

4. 撰寫說明 `.md` 檔案

每個腳本在 k6/docs/<腳本名稱>.md 中都有一個說明檔案，遵循 references/doc-template.md 的所有章節。閱讀者並非專家：請為每個專有名詞（VU、迭代、p95、閾值）提供解釋，解釋每個數字的原因，並使用腳本中的實際數值。包含負載設定檔的 ASCII 圖表、用「白話」講解的檢查和閾值表格、用於執行的確切指令（先執行煙霧測試），以及常見錯誤。然後，將此腳本加入 k6/README.md 的索引中。

5. 驗證

對每個新腳本執行 k6 inspect -e BASE_URL=https://example.test -e TARGET_ENV=staging <腳本>。這可以在不產生負載的情況下，偵測語法錯誤、損壞的 import 和無效的選項。如果未安裝 k6，請告知使用者並提供指令讓他們自己執行。
實際執行僅在使用者明確許可，且僅以煙霧測試形式（少量 VU 和短時間）在非生產環境中進行。絕對不要自行啟動負載、壓力、尖峰、浸泡或中斷點測試：它們會對共享系統產生實際負載。

6. 回覆

簡短回覆：

已建立或修改的檔案清單。
執行煙霧測試以及後續請求的測試的指令。
主要假設（與 .md 中的相同）。
您驗證了什麼以及尚未驗證什麼（例如「通過 k6 inspect；尚未針對 API 執行過」）。

審查或修正既有腳本

當需求是理解、修正或改進既有腳本時：

完整閱讀腳本，並與標準及官方文件進行比對（舊版 API、沒有 await 的瀏覽器、缺少 page.close、程式碼中的憑證、沒有閾值、沒有 name 標籤、沒有思考時間、「雲霄飛車」類型的設定檔）。
用簡單的語言解釋問題，按嚴重性排序，並提出修改建議。
修正腳本時，一併更新（或建立）其 .md 檔案，確保文件與程式碼一致。
如果腳本名稱不符合標準，建議重新命名，但未經確認請勿執行，因為這可能會中斷呼叫它的管道。

k6 腳本產生器