將 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、Dev 或 Beta 版做為預設的開發瀏覽器。這些預覽管道可讓您存取最新的 DevTools 功能，測試最新的網路平台 API，並在使用者發現問題前，協助您找出網站的問題！

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

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