將 Puppeteer 遷移至 TypeScript

Jack Franklin

開發工具團隊非常喜歡 TypeScript，因此會在 DevTools 中編寫新程式碼，並正在進行大規模遷移作業，將整個程式碼庫遷移至 TypeScript 的型別檢查。如要進一步瞭解遷移作業，請參閱 Chrome Dev Summit 2020 的演講內容。因此，我們也建議您考慮將 Puppeteer 的程式碼集遷移至 TypeScript。

規劃遷移作業

在規劃遷移方式時，我們希望能夠逐步進行。這樣一來，遷移作業的負擔就會降低，因為您每次只會處理程式碼的一小部分，風險也會降低。如果其中一個步驟發生錯誤，您可以輕鬆還原。Puppeteer 有許多使用者，如果發布版本有問題，會對許多使用者造成影響，因此我們必須盡可能降低發生重大變更的風險。

幸運的是，Puppeteer 已提供完整的單元測試組合，涵蓋所有功能。這表示我們可以確信在遷移過程中不會破壞程式碼，也不會對 API 引入變更。遷移作業的目標是讓使用者完全察覺不到遷移作業，而測試是這項策略的重要一環。如果測試涵蓋範圍不佳，我們會在繼續遷移作業前新增測試。

在未進行測試的情況下進行任何程式碼變更都存在風險，但如果變更會影響整個檔案或整個程式碼庫，風險就會特別高。在進行機械變更時，很容易遺漏步驟，而且在許多情況下，測試會找出實作人員和審查人員都未發現的問題。

我們一開始就花時間進行持續整合 (CI) 設定。我們發現，針對合併請求執行 CI 時，系統經常會發生異常，這種情況經常發生，因此我們養成了習慣，無視 CI 並合併提取要求，假設失敗是 CI 的一次性問題，而非 Puppeteer 的問題。

經過一些一般維護作業，並花時間修正一些常見的測試問題，我們讓測試結果更穩定地通過，讓我們能監控 CI，並瞭解失敗代表實際問題。這項工作並非光鮮亮麗，而且看著無止盡的 CI 執行作業也會令人感到沮喪，但考量到遷移作業會產生多少個拉取要求，因此讓測試套件可靠地執行至關重要。

挑選並登錄一個檔案

此時，我們已準備好進行遷移作業，並建立了可執行各種測試的穩健 CI 伺服器，以便監控作業。我們並未隨意處理任何檔案，而是有意挑選小型檔案進行遷移。這項練習很實用，因為可以讓您驗證即將執行的預定程序。如果這個檔案可正常運作，表示你的做法有效；如果無法運作，則可回到繪圖板。

此外，逐一處理檔案 (並搭配定期的 Puppeteer 版本，以免所有變更都發布在同一個 npm 版本中) 可降低風險。我們選擇 DeviceDescriptors.js 做為第一個檔案，因為這是程式碼集中最簡單的檔案之一。完成所有準備工作後，只看到這麼小的變更，可能會讓您覺得有點失望，但我們的目標並非立即進行大規模變更，而是謹慎且有條理地逐一處理檔案。驗證方法所花的時間，絕對會在日後遇到更複雜的檔案時，節省遷移作業的時間。

證明模式並重複執行

幸好，我們成功將 DeviceDescriptors.js 的變更納入程式碼庫，而且計畫也如預期運作！此時，您已準備好全力以赴，這正是我們所做的。使用 GitHub 標籤是將所有提取要求分組的絕佳方法，我們發現這有助於追蹤進度。

先遷移，再進行改善

對於任何個別 JavaScript 檔案，我們的處理程序如下：

  1. 將檔案重新命名，從 .js 改為 .ts。
  2. 執行 TypeScript 編譯器。
  3. 修正任何問題。
  4. 建立提取要求。

這些初始提取要求中的大部分工作，都是為現有資料結構擷取 TypeScript 介面。在先前討論的第一個提取要求中，用於遷移 DeviceDescriptors.js 的程式碼從以下變更：

module.exports = [
  { 
    name: 'Pixel 4',
    … // Other fields omitted to save space
  }, 
  …
]

並變成：

interface Device {
  name: string,
  …
}

const devices: Device[] = [{name: 'Pixel 4', …}, …]

module.exports = devices;

這個程序的一部分是檢查程式碼庫的每行程式碼，看看是否有問題。就像任何使用多年且不斷擴充的程式碼庫一樣，您可以透過重構程式碼來改善情況。特別是轉換至 TypeScript 後，我們發現在某些地方，只要稍微重構程式碼，就能讓編譯器發揮更大作用，並提升類型安全性。

雖然這與直覺相反，但請務必避免立即進行這些變更。遷移的目標是將程式碼庫轉換為 TypeScript，在大型遷移作業期間，您應隨時考量導致軟體和使用者發生故障的風險。我們將初始變更降到最低，以降低風險。檔案合併並遷移至 TypeScript 後，我們就可以進行後續變更，以改善程式碼並善用類型系統。請務必為遷移作業設定嚴格的限制，並盡量遵守這些限制。

遷移測試以測試類型定義

將整個原始碼遷移至 TypeScript 後，我們就可以專注於測試。我們的測試涵蓋範圍很廣，但都是以 JavaScript 編寫。這表示他們沒有測試我們的類型定義。這個專案的長期目標之一 (我們仍在努力) 是透過 Puppeteer 提供高品質的類型定義，但我們的程式碼庫中並未針對類型定義進行任何檢查。

我們將測試作業遷移至 TypeScript (依循相同程序，逐一處理檔案)，發現 TypeScript 中的問題，否則這些問題會由使用者自行找出。如今，我們的測試不僅涵蓋所有功能，還能做為 TypeScript 的品質檢查！

我們是 Puppeteer 程式碼集的工程師，因此 TypeScript 為我們帶來了極大助益。搭配我們大幅改善的 CI 環境，我們在使用 Puppeteer 時可更有效率，並讓 TypeScript 找出原本會納入 npm 版本的錯誤。我們很高興能提供高品質的 TypeScript 定義，讓所有使用 Puppeteer 的開發人員也能從這項工作中受益。

下載預覽管道

建議您將 Chrome Canary、開發人員版或Beta 版設為預設開發人員版瀏覽器。這些預覽管道可讓您存取最新的 DevTools 功能，測試最新的網路平台 API，並在使用者發現問題前，協助您找出網站的問題！

與 Chrome 開發人員工具團隊聯絡

請使用下列選項討論新功能、更新或任何與開發人員工具相關的內容。