Memindahkan Puppeteer ke TypeScript

Jack Franklin

Kami sangat menyukai TypeScript di tim DevTools—bahkan kode baru di DevTools ditulis dalam TypeScript dan kami sedang melakukan migrasi besar-besaran seluruh codebase agar diperiksa jenisnya oleh TypeScript. Anda dapat mengetahui lebih lanjut migrasi tersebut dalam pembicaraan kami di Chrome Dev Summit 2020. Oleh karena itu, sangat masuk akal untuk mempertimbangkan migrasi codebase Puppeteer ke TypeScript juga.

Merencanakan migrasi

Saat merencanakan cara melakukan migrasi, kami ingin dapat membuat kemajuan dalam langkah-langkah kecil. Hal ini akan mengurangi overhead migrasi—Anda hanya mengerjakan sebagian kecil kode dalam satu waktu—dan juga mengurangi risiko. Jika terjadi masalah pada salah satu langkah, Anda dapat dengan mudah mengembalikannya. Puppeteer memiliki banyak pengguna dan rilis yang rusak akan menyebabkan masalah bagi banyak pengguna, jadi sangat penting bagi kami untuk meminimalkan risiko perubahan yang dapat menyebabkan gangguan.

Kami juga beruntung karena Puppeteer memiliki serangkaian pengujian unit yang andal yang mencakup semua fungsinya. Artinya, kami dapat yakin bahwa kami tidak merusak kode saat melakukan migrasi, tetapi juga bahwa kami tidak memperkenalkan perubahan pada API kami. Tujuan migrasi ini adalah menyelesaikannya tanpa membuat pengguna Puppeteer menyadari bahwa kami telah melakukan migrasi, dan pengujian adalah bagian penting dari strategi tersebut. Jika belum memiliki cakupan pengujian yang baik, kami akan menambahkannya sebelum melanjutkan migrasi.

Melakukan perubahan kode apa pun tanpa pengujian sangat berisiko, tetapi perubahan yang menyentuh seluruh file atau keseluruhan codebase sangat berisiko. Saat melakukan perubahan mekanis, langkah-langkahnya dapat terlewat dengan mudah, dan dalam beberapa kesempatan, pengujian menemukan masalah yang terlewatkan oleh pelaksana dan peninjau.

Satu hal yang kami investasikan sejak awal adalah penyiapan Continuous Integration (CI). Kami mendapati bahwa CI yang dijalankan terhadap pull request tidak stabil dan sering gagal. Hal ini sering terjadi sehingga kami terbiasa mengabaikan CI dan menggabungkan permintaan pull, dengan asumsi bahwa kegagalan tersebut adalah masalah sekali saja di CI, bukan masalah di Puppeteer.

Setelah melakukan beberapa pemeliharaan umum dan meluangkan waktu untuk memperbaiki beberapa kegagalan pengujian reguler, kami berhasil membuatnya lulus secara lebih konsisten, sehingga kami dapat memantau CI dan mengetahui bahwa kegagalan mengindikasikan masalah yang sebenarnya. Pekerjaan ini tidaklah menarik, dan melihat proses CI yang berjalan tanpa henti bisa membuat frustrasi, tetapi sangat penting untuk memastikan suite pengujian berjalan dengan andal mengingat banyaknya permintaan pull yang dihasilkan oleh migrasi.

Memilih dan melepaskan satu file

Pada tahap ini, migrasi kami sudah siap dan server CI yang andal serta penuh dengan pengujian siap mendukung kami. Daripada langsung memigrasikan file apa pun, kita sengaja memilih file kecil untuk dimigrasikan. Latihan ini berguna karena memungkinkan Anda memvalidasi proses yang direncanakan yang akan Anda lakukan. Jika berhasil pada file ini, pendekatan Anda valid; jika tidak, Anda dapat kembali ke tahap awal.

Selain itu, melakukan migrasi file per file (dan dengan rilis Puppeteer reguler, sehingga semua perubahan tidak dikirim dalam versi npm yang sama) dapat mengurangi risiko. Kami memilih DeviceDescriptors.js sebagai file pertama, karena merupakan salah satu file yang paling mudah dalam codebase. Mungkin terasa sedikit kurang memuaskan untuk melakukan semua persiapan ini dan hanya mendapatkan perubahan kecil, tetapi tujuannya bukan untuk melakukan perubahan besar secara langsung, melainkan untuk melanjutkan dengan hati-hati dan sistematis file demi file. Waktu yang dihabiskan untuk memvalidasi pendekatan ini pasti akan menghemat waktu nanti dalam migrasi saat Anda menemukan file yang lebih rumit.

Buktikan polanya dan ulangi

Untungnya, perubahan pada DeviceDescriptors.js berhasil dimasukkan ke dalam codebase, dan rencana tersebut berhasil seperti yang kita harapkan. Pada tahap ini, Anda siap untuk fokus dan melanjutkannya, yang persis seperti yang kami lakukan. Menggunakan label GitHub adalah cara yang sangat baik untuk mengelompokkan semua permintaan pull, dan kami merasa hal itu berguna untuk melacak progres.

Migrasikan dan tingkatkan kualitasnya nanti

Untuk setiap file JavaScript individual, proses kami adalah:

  1. Ganti nama file dari .js menjadi .ts.
  2. Jalankan compiler TypeScript.
  3. Perbaiki masalah apa pun.
  4. Buat permintaan pull.

Sebagian besar pekerjaan dalam permintaan pull awal ini adalah mengekstrak antarmuka TypeScript untuk struktur data yang ada. Dalam kasus permintaan pull pertama yang memigrasikan DeviceDescriptors.js yang telah kita bahas sebelumnya, kode berubah dari:

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

Dan menjadi:

interface Device {
  name: string,
  …
}

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

module.exports = devices;

Sebagai bagian dari proses ini, kami memeriksa setiap baris codebase untuk mencari masalah. Seperti codebase yang telah ada selama beberapa tahun dan berkembang seiring waktu, ada peluang untuk melakukan refaktorisasi kode dan meningkatkan situasi. Terutama dengan beralih ke TypeScript, kami melihat beberapa bagian yang jika sedikit direstrukturisasi kodenya, akan memungkinkan kami untuk lebih mengandalkan compiler dan mendapatkan keamanan jenis yang lebih baik.

Secara berlawanan dengan intuisi, Anda sebaiknya tidak langsung melakukan perubahan ini. Tujuan migrasi adalah untuk memasukkan codebase ke TypeScript, dan selama migrasi besar, Anda harus selalu memikirkan risiko yang dapat menyebabkan kerusakan pada software dan pengguna Anda. Dengan meminimalkan perubahan awal, kami menjaga risiko tersebut tetap rendah. Setelah file digabungkan dan dimigrasikan ke TypeScript, kami dapat melakukan perubahan lanjutan untuk meningkatkan kualitas kode agar dapat memanfaatkan sistem jenis. Pastikan Anda menetapkan batasan yang ketat untuk migrasi dan mencoba untuk tetap berada dalam batasan tersebut.

Memigrasikan pengujian untuk menguji definisi jenis kita

Setelah seluruh kode sumber dimigrasikan ke TypeScript, kita dapat memfokuskan perhatian pada pengujian. Pengujian kami memiliki cakupan yang luas, tetapi semuanya ditulis dalam JavaScript. Artinya, salah satu hal yang tidak mereka uji adalah definisi jenis kami. Salah satu tujuan jangka panjang project ini (yang masih kami kerjakan) adalah mengirimkan definisi jenis berkualitas tinggi langsung dengan Puppeteer, tetapi kami tidak memiliki pemeriksaan apa pun dalam codebase kami terkait definisi jenis kami.

Dengan memigrasikan pengujian ke TypeScript (mengikuti proses yang sama, file demi file), kami menemukan masalah pada TypeScript yang seharusnya ditemukan oleh pengguna. Sekarang, pengujian kita tidak hanya mencakup semua fungsi, tetapi juga berfungsi sebagai pemeriksaan kualitas TypeScript kita.

Kami telah mendapatkan manfaat besar dari TypeScript sebagai engineer yang mengerjakan codebase Puppeteer. Bersama dengan lingkungan CI kami yang jauh lebih baik, kami menjadi lebih produktif saat mengerjakan Puppeteer dan TypeScript dapat menangkap bug yang seharusnya masuk ke rilis npm. Kami sangat senang dapat mengirimkan definisi TypeScript berkualitas tinggi agar semua developer yang menggunakan Puppeteer juga dapat memperoleh manfaat dari upaya ini.

Mendownload saluran pratinjau

Pertimbangkan untuk menggunakan Chrome Canary, Dev, atau Beta sebagai browser pengembangan default Anda. Saluran pratinjau ini memberi Anda akses ke fitur DevTools terbaru, memungkinkan Anda menguji API platform web canggih, dan membantu Anda menemukan masalah di situs Anda sebelum pengguna Anda menemukannya.

Menghubungi tim Chrome DevTools

Gunakan opsi berikut untuk mendiskusikan fitur baru, update, atau hal lain yang terkait dengan DevTools.