Migrer Puppeteer vers TypeScript

Jack Franklin

L'équipe DevTools est une grande fan de TypeScript. À tel point que nous écrivons du nouveau code dans DevTools et que nous sommes en pleine migration de l'intégralité du codebase pour qu'il soit vérifié par TypeScript. Pour en savoir plus sur cette migration, consultez notre présentation lors du Chrome Dev Summit 2020. Il était donc tout à fait logique d'envisager de migrer le code de base de Puppeteer vers TypeScript.

Planifier la migration

Lorsque nous élaborons notre stratégie de migration, nous souhaitions pouvoir progresser en quelques étapes. Cela réduit les coûts de la migration (vous ne travaillez que sur une petite partie du code à la fois) et les risques. Si l'une de ces étapes ne fonctionne pas correctement, vous pouvez facilement la rétablir. Puppeteer compte un grand nombre d'utilisateurs et une version non fonctionnelle entraînerait des problèmes pour un grand nombre d'entre eux. Il était donc essentiel de réduire au maximum le risque de casser les modifications.

Nous avons également eu la chance que Puppeteer dispose d'un ensemble robuste de tests unitaires couvrant toutes ses fonctionnalités. Cela nous a permis de nous assurer que nous ne cassons pas le code lors de la migration, mais aussi que nous n'apportons pas de modifications à notre API. L'objectif de la migration était d'éviter que les utilisateurs de Puppeteer s'en rendent compte, et les tests ont joué un rôle essentiel dans cette stratégie. Si nous n'avions pas bénéficié d'une bonne couverture de test, nous aurions pu l'ajouter avant de poursuivre la migration.

Il est risqué d'effectuer n'importe quelle modification de code sans effectuer de test. En revanche, il est particulièrement risqué d'apporter des modifications à des fichiers entiers ou à l'intégralité du codebase. Lorsque vous apportez des modifications mécaniques, il est facile de manquer une étape. À plusieurs reprises, les tests ont détecté un problème qui avait échappé à l'implémentateur et à l'examinateur.

Nous avons consacré du temps à la configuration de l'intégration continue (CI). Nous avons constaté que les builds CI sur les demandes de tirage étaient instables et échouaient souvent. Cela se produisait si souvent que nous avions pris l'habitude d'ignorer notre CI et de fusionner les requêtes pull, en supposant que l'échec était un problème ponctuel sur la CI plutôt qu'un problème dans Puppeteer.

Après une maintenance générale et un temps consacré à corriger des erreurs de test régulières, nous avons obtenu un état de réussite beaucoup plus cohérent, ce qui nous a permis d'écouter la CI et de savoir qu'un échec indiquait un problème réel. Ce travail n'est pas glamour et il peut être frustrant de voir des exécutions CI sans fin. Cependant, il était essentiel que notre suite de tests s'exécute de manière fiable, compte tenu du nombre de demandes d'extraction générées par la migration.

Sélectionner et placer un fichier

À ce stade, notre migration était prête et nous disposions d'un serveur CI robuste rempli de tests pour nous protéger. Plutôt que d'examiner un fichier arbitraire, nous avons volontairement sélectionné un petit fichier à migrer. Cet exercice est utile car il vous permet de valider le processus planifié que vous êtes sur le point de suivre. Si cela fonctionne avec ce fichier, votre approche est valide. Dans le cas contraire, vous pouvez revenir à la planche à dessin.

En outre, en procédant par fichier (et avec des versions régulières de Puppeteer, de sorte que toutes les modifications ne soient pas publiées dans la même version npm), nous avons réduit le risque. Nous avons choisi DeviceDescriptors.js comme premier fichier, car il s'agit de l'un des fichiers les plus simples du codebase. Il peut sembler un peu décevant de réaliser tout ce travail de préparation pour obtenir une si petite modification, mais l'objectif n'est pas d'apporter d'énormes changements immédiatement, mais de procéder avec prudence et méthodiquement, fichier par fichier. Le temps passé à valider l'approche vous permet de gagner du temps plus tard dans la migration lorsque vous rencontrez des fichiers plus complexes.

Valider le modèle et le répéter

Heureusement, le changement vers DeviceDescriptors.js a bien été intégré au codebase, et le plan a fonctionné comme nous l'espérions. À ce stade, vous êtes prêt à vous mettre au travail, ce qui est exactement ce que nous avons fait. L'utilisation d'un libellé GitHub est un excellent moyen de regrouper toutes les demandes d'extraction. Nous avons trouvé cela utile pour suivre la progression.

Faites-le migrer et améliorez-le plus tard

Pour chaque fichier JavaScript, nous avons suivi la procédure suivante:

  1. Renommez le fichier .js en .ts.
  2. Exécutez le compilateur TypeScript.
  3. Résoudre les problèmes.
  4. Créez la demande d'extraction.

La majeure partie du travail dans ces requêtes pull initiales consistait à extraire des interfaces TypeScript pour les structures de données existantes. Dans le cas de la première requête pull qui a migré DeviceDescriptors.js, le code est passé de:

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

Et est devenu:

interface Device {
  name: string,
  …
}

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

module.exports = devices;

Dans le cadre de ce processus, nous avons passé en revue chaque ligne du codebase à la recherche de problèmes. Comme pour tout codebase qui existe depuis quelques années et qui a évolué au fil du temps, il existe des possibilités de refactorisation du code et d'amélioration de la situation. En particulier avec le passage à TypeScript, nous avons identifié des endroits où une légère restructuration du code nous permettrait de nous appuyer davantage sur le compilateur et d'améliorer la sécurité des types.

Il est très important, contre-intuitif, de résister à ces changements tout de suite. L'objectif de la migration est d'importer le codebase dans TypeScript. Au cours d'une migration de grande envergure, vous devez à tout moment penser au risque de dysfonctionnement du logiciel et de vos utilisateurs. En limitant les modifications initiales, nous avons réduit ce risque. Une fois le fichier fusionné et migré vers TypeScript, nous avons pu apporter des modifications ultérieures pour améliorer le code et exploiter le système de types. Veillez à définir des limites strictes pour votre migration et à essayer de les respecter.

Migrer les tests pour tester nos définitions de types

Une fois que nous avons migré l'intégralité du code source vers TypeScript, nous avons pu nous concentrer sur nos tests. Nos tests avaient une couverture optimale, mais ils étaient tous écrits en JavaScript. Par conséquent, nos définitions de type n'ont pas été testées. L'un des objectifs à long terme du projet (sur lequel nous travaillons toujours) est de fournir des définitions de type de haute qualité prêtes à l'emploi avec Puppeteer. Toutefois, nous n'avions aucune vérification dans notre codebase concernant nos définitions de type.

En migrant les tests vers TypeScript (en suivant le même processus, en passant fichier par fichier), nous avons identifié des problèmes avec TypeScript, qui auraient autrement été laissés à la discrétion des utilisateurs. Désormais, nos tests couvrent non seulement l'ensemble de nos fonctionnalités, mais servent également de contrôle qualité de TypeScript.

En tant qu'ingénieurs travaillant sur le codebase Puppeteer, nous avons déjà beaucoup bénéficié de TypeScript. Associé à notre environnement de CI beaucoup amélioré, cela nous a permis d'être plus productifs lorsque nous travaillions sur Puppeteer et de laisser TypeScript détecter les bugs qui auraient autrement été inclus dans une version npm. Nous sommes ravis de pouvoir proposer des définitions TypeScript de haute qualité pour que tous les développeurs utilisant Puppeteer puissent également en profiter.

Télécharger les canaux de prévisualisation

Envisagez d'utiliser Chrome Canary, Dev ou Bêta comme navigateur de développement par défaut. Ces canaux de prévisualisation vous donnent accès aux dernières fonctionnalités de DevTools, vous permettent de tester les API de plates-formes Web de pointe et vous aident à détecter les problèmes sur votre site avant vos utilisateurs.

Contacter l'équipe des outils pour les développeurs Chrome

Utilisez les options suivantes pour discuter des nouvelles fonctionnalités, des mises à jour ou de tout autre élément lié aux outils pour les développeurs.