跳至主要內容

貢獻

您喜歡 WebdriverIO 並想幫助它變得更好嗎？太棒了！我們正在努力使這個過程盡可能簡單和透明。我們可能還沒有完全做到，但本指南將幫助您成為貢獻者，並為您提供首次貢獻所需的一切。如果有任何遺漏的資訊阻礙您發送 Pull Request，請告訴我們。我們會將這類問題視為實際的錯誤。

行為準則​

每個參與此專案的人，無論是以使用者或貢獻者的身分，都有義務遵守專案的行為準則。任何違反行為準則的行為都將經過審查和調查，並將根據情況採取必要且適當的回應。專案團隊有義務對事件舉報人保密。具體執行政策的更多詳細資訊可能會另行發布。

尋找貢獻方式​

該專案提供了多種貢獻方式。如果您難以找到適合自己的方式，請加入 Matrix 上的 WebdriverIO 支援頻道並聯絡維護者。別害羞，他們在那裡是為了幫助您！

您可以透過以下方式參與

  • 貢獻程式碼
  • 改進文件
  • 協助我們將專案翻譯成更多語言
  • 在Discord支援頻道中回答問題並提供協助
  • 建立教育內容（部落格文章、教學、影片等）
  • 宣傳該專案（例如，透過 Twitter）
  • 如果您在使用 WebdriverIO 時發現錯誤，請建立錯誤
  • 如果您在專案中缺少某些功能，請提出功能要求
  • 如果您想在金錢上支持我們，請考慮捐贈給專案

專案的維護者會盡力整理所有issue，以便任何人都能有足夠的背景資訊開始著手處理。如果情況並非如此，請在 issue 討論串中提及，以便 issue 建立者或維護者提供更多資訊。

如果您想貢獻程式碼，一般而言，找到要處理的任務的好方法是查看所有標有help wanted和/或good first pick標籤的 issue。如果這些 issue 沒有指派使用者，則所有這些 issue 都可供您處理。如果您發現感興趣的內容，請務必在 issue 討論串中告知我們您有意願處理它。

通常，issue 需要一些關於問題的背景資訊，這使得很難了解需要做什麼。根據您使用/處理專案的經驗，可能會缺少這些背景資訊。通常，從處理缺少的文件或僅增加程式碼中某些部分的測試覆蓋率開始會有幫助。一段時間後，您會更熟悉程式碼庫，這讓您可以處理更困難的任務。

如果您找不到適合您的內容，請查看專案路線圖，看看是否有您感興趣的內容。最後，您也隨時可以透過Discord支援頻道聯絡維護者。他們有責任為您找到任務。

回報新 issue​

當開啟新的 issue時，請務必填寫 issue 範本。這個步驟非常重要！如果沒有這樣做，您的 issue 可能無法及時處理。如果發生這種情況，請不要介意，並在您收集到範本所需的所有資訊後，隨時開啟新的 issue。

  • 一個 issue，一個錯誤：請在每個 issue 中回報單一錯誤。
  • 提供重現步驟：列出重現 issue 所需的所有步驟。閱讀您的錯誤報告的人應該能夠按照這些步驟，以最少的努力重現您的 issue。

提供可重現的範例​

可重現的範例是一個簡單、獨立的指令碼或程式，可示範您遇到的 issue 或錯誤。目的是讓其他人可以輕鬆有效地重現問題。

建立可重現範例的步驟

  1. 隔離問題
  • 將您的程式碼縮減到仍可重現 issue 的最小量。
  • 移除任何與問題無關的非必要程式碼或相依性。
  1. 確保其他人可以執行您的範例並重現 issue
  • 除非絕對必要，否則它不應需要任何非標準設定，例如，移除對特殊軟體或 CI 廠商等服務的任何需求。
  • 記錄執行可重現範例所需的步驟
  1. 分享專案
  • 建立一個新的公開 GitHub 儲存庫，並將您的可重現範例推送至該儲存庫。
  • 在 issue 中分享儲存庫的連結。
  • 記錄您觀察到的行為以及您期望的行為

注意：如果您無法提供可重現的範例，很遺憾，我們只能被迫關閉該 issue。

安全性錯誤​

請參閱SECURITY.md。

流程圖​

流程圖提供了 WebdriverIO 生態系統的高階概觀，以及不同套件彼此之間的互動方式。

WDIO 命令 - 說明 wdio config、install 和 repl 命令工作流程。

建立本機工作進程 - 說明 @wdio/cli、@wdio/local-runner 和 @wdio/runner 套件之間的互動，以及如何建立工作進程。

測試執行 - 概述本機執行程式工作進程中如何執行測試。

高階概觀 - 流程圖提供 WebdriverIO 生態系統如何與核心套件互動的高階概觀。

提出變更​

我們樂於接受您提出的任何改善框架可用性的想法。如果您有關於新功能的想法，請先提出功能要求，以便維護團隊對其提供回饋。這讓我們可以在您投入大量精力之前就您的提案達成協議。

如果您只是修正錯誤，您可以立即提交 Pull Request，但我們仍然建議您提出 issue，詳細說明您要修正的內容。這有助於我們在不接受該特定修正，但又想追蹤問題的情況下。

使用程式碼​

如果您對程式碼進行任何變更，您需要快速測試它，看看它們是否符合您的預期。在 WebdriverIO 中有幾種方法可以做到這一點。首先，您可以將單個子套件連結到您自己的專案中，看看您所做的變更是否產生您預期的效果。

在 WebdriverIO 中測試變更的另一種方法是使用其範例目錄或執行其煙霧測試套件。範例目錄是一組以各種方式使用 WebdriverIO 的範例指令碼。在這裡，您需要執行瀏覽器驅動程式才能執行指令碼。透過煙霧測試套件，您可以在預定義的執行場景中執行各種 WebdriverIO 版本。所有這些場景都在我們的WebDriver 模擬服務中定義，該服務透過使用預定義的回應存根化端點來模擬瀏覽器驅動程式。這是快速執行 WebdriverIO 套件而無需設定任何內容的好方法。

發出 Pull Request​

一旦您實作了修正或完成功能實作，您就可以發出 Pull Request。您的變更需要推送至您的 WebdriverIO 分支。在 GitHub UI 中，您應該會看到一個按鈕彈出，讓您可以向主儲存庫提出 PR。

我們已經為您提供了一個範本供您填寫。這裡沒有太多規則需要遵循。請盡可能詳細地解釋您的變更。請確保您已為您的變更編寫足夠的單元測試，否則程式碼覆蓋率檢查將導致建置失敗。

如同許多開源專案一樣，我們要求您簽署一份 CLA，即貢獻者授權協議，以確保所有對專案的貢獻都根據專案各自的開源許可（即 MIT 許可）授權。它規範了您向我們（作為 OpenJS 基金會）提供程式碼變更的法律含義。

WebdriverIO 的維護者將盡快審查您的提取請求。他們將批准並合併您的變更、請求修改或關閉並附上說明。

設定專案​

您可以立即使用 預先設定好的 Gitpod 環境開始編寫程式碼（請參閱 此處 以了解更多資訊）。如果您想在本機上開發專案，請按照此逐步指南進行

  • Fork 專案。

  • 將專案克隆到您電腦的某個位置

    $ git clone git@github.com:<your-username>/webdriverio.git

  • 在 Windows 上，您需要將 git config core.symlinks 設定為 true，因為我們目前為提交到我們儲存庫的類型定義設定了一些符號連結。

    • 要全域設定 git config：git config --global --add core.symlinks true
    • 要在克隆儲存庫時在本機設定 git config：git -c core.symlinks=true clone git@github.com:<your-username>/webdriverio.git。

    請參閱 https://github.com/git-for-windows/git/wiki/Symbolic-Links 以了解更多資訊

  • 如果您需要更新您的 Fork，您可以按照此處的步驟進行

  • 切換到最新的 Node LTS 版本（您應該可以使用較舊/較新的 Node 版本，但我們建議使用 v20 LTS，以便所有開發人員都在同一版本上），或切換到 .nvmrc 中指定的版本。我們建議使用 nvm 在 Node.js 版本之間切換。

  • 設定專案：首先請確保您已安裝正確的 Node.js 版本。您可以在專案根目錄的 .nvmrc 中找到目前定義的開發版本。處理多個 Node.js 版本的最簡單方法是使用 NVM。設定好 NVM 後，使用它來安裝所需的 Node.js 版本

    $ nvm install

    接下來，全域安裝 pnpm

    $ npm install -g pnpm

    最後，透過以下方式設定專案

    $ pnpm install
    $ pnpm run setup

    第二個指令會執行兩項操作

    • 透過 pnpm run clean 清除（可能的）現有建置成品

      如果您已編譯程式碼，此指令將移除它們以及子套件的所有相依性。

    • 編譯專案 pnpm run compile:all

      最後一步，您需要建置所有子套件，以解決內部相依性。WebdriverIO 使用 @wdio/compiler，這是一個內部套件，使用 Esbuild 來編譯專案。

  • 執行測試以確保所有設定皆正確

    # run the complete unit test suite
    $ pnpm test

    # run test for a specific sub project (e.g. webdriver)
    $ npx vitest ./packages/webdriver/tests

    它應該會給您一個通過的結果。現在您可以繼續設定您的開發環境並開始編寫一些程式碼。如果測試未通過，請建立問題並提供錯誤記錄。

處理套件​

如果您開始變更特定套件，請確保您會監聽檔案變更，並在每次按下儲存時轉譯程式碼。要對所有套件執行此操作，請執行

pnpm run dev

如果您只處理單一套件，您可以透過呼叫來只監看該套件

# e.g. `$ pnpm run dev wdio-runner`
$ pnpm run dev <package-name>

在單一套件上開發時，最好也以監看模式執行 vitest，以查看變更是否會影響任何測試

npx vitest ./packages/<package-name>/tests

TypeScript 定義​

WebdriverIO 使用 TypeScript 來確保程式碼是靜態類型，並避免常犯的誤用錯誤。如果您是 TypeScript 的新手，請查看 這些很棒的基本資源以開始使用它。

WebdriverIO 為使用 TypeScript 的專案提供自己的類型定義。鑑於命令數量龐大，如果不自動化這些命令的生成過程，將使其難以維護。但是，某些邊緣情況需要人工操作。

所有類型定義都是由 TypeScript 編譯器生成的。有一些必要的套件用於此

  • @wdio/types 套件提供程式碼庫中使用的所有通用類型，例如 Capabilities、Options 等。如果您需要在多個套件中使用類型定義，則最好在此處定義它們
  • @wdio/protocol 套件定義所有協定命令、其函式參數和傳回類型
  • 所有其他類型都應在它們使用的套件中定義，這裡我們傾向於在 types.ts 檔案中定義通用類型

協定類型是作為 @wdio/compiler 建置指令的一部分生成的，並且是 generate-types 外掛程式的一部分。

測試變更​

為了開發 WebdriverIO 程式碼庫，您可以使用維護者在 examples 目錄中建立的範例檔案。它們涵蓋各種使用案例，並且經過設定，因此它們可以使用儲存庫中的程式碼執行。假設您對 WDIO 測試執行器進行了變更，並且想查看它們是否已正確套用，您可以執行測試執行器範例，方法是呼叫

cd ./examples/wdio
$ pnpm run test:mocha

這將使用 Mochajs 執行一個使用測試執行器的簡單測試套件。對於其他架構、自訂服務和回報程式，以及使用開發工具協定作為自動化引擎，也有類似的範例。如果您正在處理的功能有助於測試，請隨時新增範例。

測試管道​

當提交 PR 時，WebdriverIO 會執行以下檢查

  • 相依性檢查 我們會自動檢查每個子套件是否已安裝其 package.json 中的所有相依性。您可以透過呼叫手動觸發此檢查 
    $ pnpm run test:depcheck
  • ESLint 一個通用的 ESLint 測試，可以對齊程式碼樣式並及早偵測語法錯誤。您可以透過呼叫手動觸發此檢查 
    $ pnpm run test:eslint
  • TypeScript 定義測試 當我們生成類型定義時，我們希望謹慎地確保生成的定義實際定義了預期的介面。請在測試類型定義處閱讀更多相關資訊。您可以透過呼叫手動觸發此檢查 
    $ pnpm run test:typings
  • 單元測試 就像每個專案一樣，我們會對我們的程式碼進行單元測試，並確保新修補程式經過適當的測試。覆蓋率門檻相當高，因此請確保您的變更涵蓋所有必要的程式碼路徑。我們在此使用 Vitest 作為單元測試架構。您可以透過呼叫手動觸發此檢查 
    $ pnpm run test:unit
  • 冒煙測試 雖然單元測試已經涵蓋了許多案例，但我們還會額外執行冒煙測試，模擬在單元層級難以測試的測試情境，因為它們包含在單元測試中被虛擬化的相依性功能。例如，此類情境是正確的測試重試或失敗處理。冒煙測試會執行實際的 e2e 測試，其中驅動程式會被虛擬化（透過 @wdio/smoke-test-service）以傳回虛假的結果。您可以透過呼叫手動觸發此檢查 
    $ pnpm run test:smoke
  • e2e 測試 最後但同樣重要的是，我們會使用真正的無頭瀏覽器執行實際的 e2e 測試，以確保我們可以在所有支援的變體中啟動測試，並確保從頭到尾的某些服務。您可以透過呼叫手動觸發此檢查 
    $ pnpm run test:e2e

單元測試​

專案嘗試保持高測試覆蓋率，以確保對程式碼的變更是有意的且經過深思熟慮的。因此，對於每個程式碼檔案，「通常」都有一個單元測試檔案，位於 test 目錄中。例如，以下項目的單元測試

packages/webdriverio/src/commands/element/getCSSProperty.ts

位於

packages/webdriverio/tests/commands/element/getCSSProperty.test.ts

如果不是這種情況，則該檔案的功能可能會透過不同的檔案進行測試。我們建議為程式碼庫中編寫的每個新函式編寫單元測試。我們建議使用 Vitest 的虛擬化功能來虛擬化與其他套件或模組的每個相依性。

在開發過程中，專注於為單一檔案執行單元測試，而不是整個程式碼庫是有意義的。例如，如果您正在處理 getCSSProperty 命令，則最好僅透過呼叫來執行該特定命令的單元測試

npx vitest packages/webdriverio/tests/commands/element/getCSSProperty.test.ts

使用 --watch 旗標，只要您變更檔案中的內容，單元測試就會重新執行。

使用冒煙測試執行 e2e 體驗​

WebdriverIO 維護一組冒煙測試套件，可讓您呈現使用者執行 wdio 測試執行器的完整 e2e 體驗。它經過設定，使其不需要實際的瀏覽器驅動程式，因為所有請求都會使用 @wdio/webdriver-mock-service 進行虛擬化。這讓您有機會在不設定瀏覽器驅動程式和測試頁面的情況下執行 wdio 測試套件。您可以透過以下方式執行所有冒煙測試

pnpm run test:smoke

有一個 smoke.runner.js 檔案會觸發所有測試。它包含數個定義好的測試套件，這些套件會在不同的環境中執行，例如 Mocha、Jasmine 和 Cucumber。您可以透過呼叫特定的測試套件來執行，例如：

pnpm run test:smoke mochaTestrunner

每個測試套件都是一個函式，它會使用 launch 輔助方法，以程式化的方式觸發 wdio 測試執行器。您只需傳入組態檔的路徑，以及您想要覆寫組態的內容。大多數的冒煙測試都使用一個通用組態檔，並覆寫其特定使用案例的屬性。

如果您要測試自訂的 WebDriver 命令，您可以在 @wdio/webdriver-mock-service 中定義您自己的模擬回應情境。

測試類型定義​

為了確保我們不會不小心更改類型並導致使用者的測試中斷，我們會執行一些簡單的 TypeScript 檢查。您可以透過執行以下指令來執行所有類型定義測試：

pnpm run test:typings

這會針對 WebdriverIO 提供的所有類型定義執行所有測試。這些測試只會檢查 TypeScript 是否可以根據產生的類型定義進行編譯。所有類型檢查都位於 /webdriverio/tests/typings 中。如果您擴展 WebdriverIO 命令或其他類型定義的介面，請確保您已在這些檔案中使用它。該目錄包含 WebdriverIO 非同步使用的測試。

例如，要測試 touchActions 屬性，我們在 /tests/typings/webdriverio/async.ts 中進行測試

// touchAction
const ele = await $('')
const touchAction: WebdriverIO.TouchAction = {
    action: "longPress",
    element: await $(''),
    ms: 0,
    x: 0,
    y: 0
}
await ele.touchAction(touchAction)
await browser.touchAction(touchAction)

以及在 /tests/typings/sync/sync.ts 中進行測試

const ele = $('')
const touchAction: WebdriverIO.TouchAction = {
    action: "longPress",
    element: $(''),
    ms: 0,
    x: 0,
    y: 0
}
ele.touchAction(touchAction)
browser.touchAction(touchAction)

文件​

此儲存庫包含設定、建置和部署 WebdriverIO 文件頁面的所有內容。我們使用 Docusaurus (v2) 來產生頁面。內容是根據以下內容產生：

  • 來自 docs 目錄中 markdown 檔案的指南頁面
  • 來自此儲存庫中這些套件的 readme 檔案的服務和報告器文件
  • 來自第三方外掛程式（在 這些 JSON 檔案中定義）的服務和報告器文件，這些文件從 GitHub 下載並進行解析
  • 來自 @wdio/protocols 套件的協定 API
  • 從個別命令的 JSDoc 註解中解析出的 WebdriverIO API（例如，execute 命令）

對文件的變更需要在這些地方之一完成。請注意，對組態檔的變更必須在多個地方更新，因為組態檔在此儲存庫中廣泛分佈（作為範例或測試檔案）。一種好的方法是尋找組態的特定字串的所有出現位置，並更新所有結果中的變更。

在本機部署文件​

在您 設定專案 後，您可以進入 website 目錄來設定文件頁面並在您的本機電腦上執行它。若要執行此操作，請執行：

cd website
$ pnpm install
$ pnpm start

這會設定在 localhost:3000 上執行頁面所需的一切。如果您需要在不同的主機或埠上執行，請將它們作為額外引數傳遞給 pnpm start，例如 -- --host 0.0.0.0。

您現在可以修改 /website/docs 檔案的內容，以及變更樣式和範本。頁面將自動更新。如果您在其他地方新增文件，您必須重新執行 pnpm start 指令碼以重新產生文件。

在生產環境中部署文件​

每次將新版本推送到 GitHub 時，都需要建置 WebdriverIO 文件並將其重新部署到專案的 S3 儲存桶。此流程在 GitHub Actions pipeline 中定義。您（作為維護者）只需觸發 pipeline。其餘的由工作流程處理。

建立新套件​

所有 WebdriverIO 子套件都需要特定的結構才能在 wdio 生態系統中工作。為了簡化建立新子套件的流程，我們建立了一個 NPM 指令碼，它可以為您完成所有樣板工作。只需執行：

pnpm run create

它會詢問您新套件的類型和名稱，並為您建立所有檔案。

回溯錯誤修復​

從 v6 開始，WebdriverIO 團隊嘗試回溯所有仍與舊版本向後相容的功能。團隊嘗試每年發布一個新的主要版本（通常在 12 月/1 月左右）。隨著新的主要版本更新（例如 v7），我們會繼續維護最後一個版本（例如 v6）並棄用先前維護的版本（例如 v5、v4 和更低版本）。因此，團隊致力於始終支援 2 個主要版本。

作為分類者​

每個分類或審閱 PR 的人都應該使用 backport-requested 標籤標記它，如果變更可以應用於維護的（先前）版本。通常，每個不會對先前版本造成重大變更的 PR 都應考慮回溯。如果變更依賴於僅在目前版本中可用的功能或程式碼片段，如果您覺得可以進行必要的調整，仍然可以考慮回溯。也就是說，如果時間投入和複雜性太高，請不要強迫回溯程式碼。回溯功能是任何貢獻者都可以做出的合理貢獻。

作為合併者​

一旦具有 backport-requested 標籤的 PR 被合併，您就有責任將修補程式回溯到舊版本。為此，請從 GitHub 中提取最新的程式碼：

git pull
$ git fetch --all
$ git checkout v6

在開始之前，請將 GITHUB_AUTH 權杖匯出到您的環境中，以允許執行指令碼擷取有關提取請求的資料並設定適當的標籤。前往您的個人存取權杖設定頁面，並產生一個只啟用 public_repo 欄位的權杖。然後將其匯出到您的環境中並執行回溯指令碼。它會擷取所有與標記為 backport-requested 的 PR 連接的提交，並將它們 cherry-pick 到維護分支中。透過互動式主控台，您可以再次審閱 PR，以及是否要回溯它。若要開始此流程，只需執行：

pnpm run backport

如果在過程中 cherry-pick 失敗，您可以隨時中止並手動進行疑難排解。如果您無法解決問題，請在儲存庫中建立一個問題並包含該 PR 的作者。成功回溯兩個 PR 會如下所示：

$ pnpm run backport

> webdriverio-monorepo@ backport /path/to/webdriverio/webdriverio
> node ./scripts/backport.js

? You want to backport "Backporting Test PR" by christian-bromann?
(See PR https://github.com/webdriverio/webdriverio/pull/4890) Yes
Backporting sha 264b7bc49dfc3fe8f1ed8b58d681ce562aaf1544 from v6 to v5
[cb-backport-process e47c5527] Backporting Test PR (#4890)
 Author: Christian Bromann <mail@christian-bromann.com>
 Date: Mon Dec 16 14:54:02 2019 +0100
 1 file changed, 2 insertions(+)
? You want to backport "Second backport test" by christian-bromann?
(See PR https://github.com/webdriverio/webdriverio/pull/4891) Yes
Backporting sha 77dc52fdb86c51242b92f299998d2904004cb347 from v6 to v5
[cb-backport-process 35a3ad41] Second backport test (#4891)
 Author: Christian Bromann <mail@christian-bromann.com>
 Date: Mon Dec 16 16:01:46 2019 +0100
 1 file changed, 2 deletions(-)

Successfully backported 2 PRs 👏!
Please now push them to `v6` and make a new v6.x release!

如有任何問題，您可以隨時在 Matrix 上聯繫 webdriverio/ProjectCommitters 頻道。

發布新版本​

套件發布是使用 Lerna 的發布功能作為 GitHub 工作流程來完成的，並且僅由技術指導委員會執行。您只需前往 Manual NPM Publish 工作流程並觸發新的執行。根據語義版本控制選擇適當的版本升級。為了協助選擇正確的發布類型，以下是一些一般指南：

  • 重大變更：永遠不要自己執行這些變更！主要版本發布始終是所有 TSC 成員之間的協作努力。它需要所有成員達成共識。
  • 次要版本發布：如果將新的、以使用者為中心的功能新增到其中一個套件，則始終需要次要版本發布。例如，如果將命令新增到 WebdriverIO，或者如果服務提供新的整合形式，則適用於次要版本變更。但是，如果像 @wdio/local-runner 這樣的內部套件公開僅在內部使用的新介面，我們可以將其視為修補程式發布。
  • 修補程式發布：每次修復錯誤、更新文件（包括 TypeScript 定義）或改進現有功能時，我們都應該進行修補程式發布。

如果您不確定要選擇哪種發布類型，請在 webdriverio/TSC Matrix 頻道中聯繫。透過設定 NPM 標籤，您也可以使用例如 next 標籤來發布目前版本，以便在我們將其推出給所有使用者之前測試變更。

研討會​

作為 OpenJS World 2020 合作者峰會 的一部分，WebdriverIO 團隊舉辦了一個關於「貢獻 WebdriverIO」的研討會，可以幫助您熟悉程式碼庫和專案。請觀看：

此儲存庫包含 WebdriverIO 專案的所有必要套件（不包括第三方開發人員貢獻的外掛程式）。這些套件在它們的 README 檔案（/packages/<package>/README.md）中都有個別的描述，其中提供有關其範圍和責任的資訊。即使每個套件的建置指令可能不同，但它們的工作方式是相同的。此專案使用 Lerna 來管理此整體儲存庫中的所有子專案。

歡迎！請問有什麼可以幫您？

WebdriverIO AI Copilot