Personnaliser JavaScript pour Azure Pipelines

Vous pouvez utiliser Azure Pipelines pour créer vos applications JavaScript sans avoir à configurer votre propre infrastructure. Les outils que vous utilisez couramment pour générer, tester et exécuter des applications JavaScript, comme npm, Node, Yarn et Gulp, sont préinstallés sur les agents hébergés par Microsoft dans Azure Pipelines.

Pour connaître la version de Node.js et npm préinstallée, reportez-vous aux agents hébergés par Microsoft. Pour installer une version spécifique de ces outils sur des agents hébergés par Microsoft, ajoutez la tâche Programme d’installation de l’outil Node au début de votre processus. Vous pouvez également utiliser un agent auto-hébergé.

Pour créer votre premier pipeline avec JavaScript, consultez le guide de démarrage rapide JavaScript.

Utiliser une version spécifique de Node.js

Si vous avez besoin d’une version de Node.js et de npm qui n’est pas déjà installée sur l’agent hébergé par Microsoft, utilisez la tâche d’installation de l’outil Node. Ajoutez l’extrait de code suivant à votre fichier azure-pipelines.yml.

Notes

Les agents hébergés sont régulièrement mis à jour, et la configuration de cette tâche entraîne un temps considérable de mise à jour vers une version mineure plus récente chaque fois que le pipeline est exécuté. Utilisez cette tâche uniquement lorsque vous avez besoin d’une version spécifique de Node dans votre pipeline.

- task: UseNode@1
  inputs:
    version: '16.x' # replace this value with the version that you need for your project

Pour mettre à jour uniquement l’outil npm, exécutez la commande npm i -g npm@version-number dans votre processus de build.

Utiliser plusieurs versions de nœud

Vous pouvez générer et tester votre application sur plusieurs versions de Node avec la tâche du programme d’installation de l’outil Node.

pool:
  vmImage: 'ubuntu-latest'
strategy:
  matrix:
    node_16_x:
      node_version: 16.x
    node_13_x:
      node_version: 18.x

steps:
- task: UseNode@1
  inputs:
    version: $(node_version)

- script: npm install

Installer des outils sur votre agent de build

Si vous avez des outils qui sont des dépendances de développement dans le fichier package.json ou package-lock.json de votre projet, installez vos outils et dépendances via npm. La version exacte des outils est définie dans le projet, isolée des autres versions qui existent sur l’agent de build.

Utilisez un script ou la tâche npm.

Utiliser un script pour installer avec package.json

- script: npm install --only=dev

Utiliser la tâche npm pour installer avec package.json

- task: Npm@1
  inputs:
     command: 'install'

Exécutez les outils installés de cette façon à l’aide de l’exécuteur de package npm npx, qui détecte les outils installés de cette façon dans sa résolution de chemin. L’exemple suivant appelle l’exécuteur de test mocha, mais recherche la version installée en tant que dépendance de développement avant d’utiliser une version installée globalement (via npm install -g).

- script: npx mocha

Pour installer des outils dont votre projet a besoin, mais qui ne sont pas définis en tant que dépendances de développement dans package.json, appelez npm install -g à partir d’une phase de script dans votre pipeline.

L’exemple suivant installe la dernière version de l’interface CLI Angular à l’aide de npm. Le reste du pipeline peut ensuite utiliser l’outil ng à partir d’autres phases script.

Notes

Sur les agents Linux hébergés par Microsoft, précédez la commande avec sudo, comme sudo npm install -g.

- script: npm install -g @angular/cli

Conseil

Ces tâches s’exécutent chaque fois que votre pipeline s’exécute. Tenez donc compte de l’impact de l’installation des outils sur les temps de build. Envisagez de configurer des agents auto-hébergés avec la version des outils dont vous avez besoin si la surcharge devient un impact sérieux sur les performances de votre build.

Gérer les dépendances

Dans votre build, utilisez Yarn ou Azure Artifacts pour télécharger des packages à partir du registre npm public. Ce registre est un type de registre npm privé que vous spécifiez dans le fichier .npmrc.

Utiliser npm

Vous pouvez utiliser npm des manières suivantes pour télécharger des packages pour votre build :

• Exécutez npm install directement dans votre pipeline, car il s’agit du moyen le plus simple de télécharger des packages à partir d’un registre sans authentification. Si votre build n’a pas besoin de dépendances de développement sur l’agent pour s’exécuter, vous pouvez accélérer les temps de build en définissant l’option --only=prod sur npm install.
• Utilisez une tâche npm. Cette tâche est utile lorsque vous utilisez un registre authentifié.
• Utilisez une tâche npm Authenticate. Cette tâche est utile lorsque vous exécutez npm install à partir de vos exécuteurs de tâches (Gulp, Grunt ou Maven).

Si vous souhaitez spécifier un registre npm, placez les URL dans un fichier .npmrc dans votre dépôt. Si votre flux est authentifié, créez une connexion de service npm sous l’onglet Services dans Paramètres du projet pour gérer ses informations d’identification.

Pour installer des packages npm avec un script dans votre pipeline, ajoutez l’extrait de code suivant à azure-pipelines.yml.

- script: npm install

Pour utiliser un registre privé spécifié dans votre fichier .npmrc, ajoutez l’extrait de code suivant à azure-pipelines.yml.

- task: Npm@1
  inputs:
    customEndpoint: <Name of npm service connection>

Pour passer les informations d’identification du Registre aux commandes npm via des exécuteurs de tâches, comme Gulp, ajoutez la tâche suivante à azure-pipelines.yml avant d’appeler l’exécuteur de tâche.

- task: npmAuthenticate@0
  inputs:
    customEndpoint: <Name of npm service connection>

Si vos builds échouent parfois en raison de problèmes de connexion lorsque vous restaurez des packages à partir du registre npm, vous pouvez utiliser Azure Artifacts avec les sources en amont et mettre en cache les packages. Les informations d’identification du pipeline sont automatiquement utilisées lorsque vous vous connectez à Azure Artifacts. Ces informations d’identification sont généralement dérivées du compte de service de build de collection de projets.

Si vous utilisez des agents hébergés par Microsoft, vous obtenez une nouvelle machine chaque fois que vous exécutez une build, ce qui signifie que vous restaurez les dépendances à chaque fois, ce qui peut prendre beaucoup de temps. Pour atténuer les problèmes, vous pouvez utiliser Azure Artifacts ou un agent auto-hébergé. Vous bénéficiez ainsi de l’utilisation du cache de package.

Utiliser Yarn

Utilisez une phase de script pour appeler Yarn afin de restaurer les dépendances. Yarn est préinstallé sur certains agents hébergés par Microsoft. Vous pouvez l’installer et le configurer sur des agents auto-hébergés comme n’importe quel autre outil.

- script: yarn install

Exécuter des compilateurs JavaScript

Utilisez des compilateurs tels que Babel et le compilateur TypeScript tsc pour convertir votre code source en versions utilisables par le runtime Node.js ou dans les navigateurs web.

Si vous avez configuré un objet de script dans votre fichier projet package.json qui exécute votre compilateur, appelez-le dans votre pipeline à l’aide d’une tâche de script.

- script: npm run compile

Vous pouvez appeler des compilateurs directement à partir du pipeline à l’aide de la tâche de script. Ces commandes s’exécutent à partir de la racine du dépôt de code source cloné.

- script: tsc --target ES6 --strict true --project tsconfigs/production.json

Exécuter des tests unitaires

Configurez vos pipelines pour exécuter vos tests JavaScript afin qu’ils produisent des résultats mis en forme au format XML JUnit. Vous pouvez ensuite publier les résultats à l’aide de la tâche intégrée publish test results.

Si votre framework de test ne prend pas en charge la sortie JUnit, ajoutez la prise en charge par le biais d’un module de création de rapports partenaire, comme mocha-junit-reporter. Vous pouvez soit mettre à jour votre script de test pour utiliser le rapporteur JUnit, soit si le rapporteur prend en charge les options de ligne de commande, passer ces options dans la définition de tâche.

Le tableau suivant répertorie les exécuteurs de test et les rapporteurs les plus couramment utilisés pour produire des résultats XML :

Exécuteur de tests	Rapporteurs pour produire des rapports XML
mocha	mocha-junit-reporter cypress-multi-reporters
jasmine	jasmine-reporters
jest	jest-junit jest-junit-reporter
karma	karma-junit-reporter
Ava	tap-xunit

L’exemple suivant utilise mocha-junit-reporter et appelle mocha test directement à l’aide d’un script. Ce script produit la sortie XML JUnit à l’emplacement par défaut de ./test-results.xml.

- script: mocha test --reporter mocha-junit-reporter

Si vous avez défini un script test dans le fichier package.json de votre projet, vous pouvez l’appeler à l’aide de npm test.

- script: npm test

Publier les résultats des tests

Pour publier les résultats, utilisez la tâche Publier les résultats des tests.

- task: PublishTestResults@2
  condition: succeededOrFailed()
  inputs:
    testRunner: JUnit
    testResultsFiles: '**/test-results.xml'

Publier les résultats de la couverture du code

Si vos scripts de test exécutent un outil de couverture du code, comme Istanbul, ajoutez la tâche Publier les résultats de la couverture du code. Dans ce cas, vous pouvez trouver des métriques de couverture dans le résumé de build et télécharger des rapports HTML pour une analyse plus approfondie. La tâche attend une sortie de création de rapports Cobertura ou JaCoCo. Assurez-vous donc que votre outil de couverture du code s’exécute avec les options nécessaires pour générer la sortie appropriée. Par exemple : --report cobertura.

L’exemple suivant utilise nyc, l’interface de ligne de commande Istanbul, ainsi que la commande mocha-junit-reporter et appelle npm test.

- script: |
    nyc --reporter=cobertura --reporter=html \
    npm test -- --reporter mocha-junit-reporter --reporter-options mochaFile=./test-results.xml
  displayName: 'Build code coverage report'

- task: PublishCodeCoverageResults@2
  inputs: 
    summaryFileLocation: '$(System.DefaultWorkingDirectory)/**/*coverage.xml'

Navigateur de test de bout en bout

Exécutez des tests dans des navigateurs sans interface graphique dans le cadre de votre pipeline avec des outils comme Protractor ou Karma. Publiez ensuite les résultats de la build dans Azure DevOps en procédant comme suit :

1. Installez un pilote de test de navigateur sans interface utilisateur, comme Chrome ou Firefox sans interface utilisateur, ou un outil de simulation de navigateur, comme PhantomJS, sur l’agent de build.
2. Configurez votre framework de test pour utiliser l’option de navigateur/pilote sans interface utilisateur de votre choix en fonction de la documentation de l’outil.
3. Configurez votre framework de test (généralement avec un plug-in ou une configuration de rapporteur) pour générer les résultats des tests au format JUnit.
4. Configurez une tâche de script pour exécuter toutes les commandes CLI nécessaires pour démarrer les instances de navigateur sans interface utilisateur.
5. Exécutez les tests de bout en bout dans les phases de pipeline avec vos tests unitaires.
6. Publiez les résultats à l’aide de la même tâche Publier les résultats des tests avec vos tests unitaires.

Empaqueter des applications web

Empaquetez des applications pour regrouper tous vos modules d’application avec des sorties et des dépendances intermédiaires dans des ressources statiques prêtes pour le déploiement. Ajoutez une phase de pipeline après votre compilation et vos tests pour exécuter un outil comme webpack ou ng build à l’aide de l’interface CLI Angular.

Le premier exemple appelle webpack. Pour effectuer ce travail, assurez-vous que webpack est configuré en tant que dépendance de développement dans votre fichier projet package.json. Cette opération exécute webpack avec la configuration par défaut, sauf si vous avez un fichier webpack.config.js dans le dossier racine de votre projet.

- script: webpack

L’exemple suivant utilise la tâche npm pour appeler npm run build pour appeler l’objet de script build défini dans le fichier projet package.json. L’utilisation d’objets de script dans votre projet déplace la logique de la build dans le code source et en dehors du pipeline.

- script: npm run build

Implémenter des frameworks JavaScript

Angular

Pour les applications Angular, vous pouvez inclure des commandes spécifiques à Angular, comme ng test, ng build et ng e2e. Pour utiliser les commandes CLI Angular dans votre pipeline, installez le package npm angular/cli sur l’agent de build.

Notes

Sur les agents Linux hébergés par Microsoft, précédez la commande avec sudo, comme sudo npm install -g.

- script: |
    npm install -g @angular/cli
    npm install
    ng build --prod

Pour les tests dans votre pipeline qui nécessitent l’exécution d’un navigateur, comme la commande ng test dans l’application de démarrage, qui exécute Karma, utilisez un navigateur sans interface utilisateur au lieu d’un navigateur standard. Dans l’application de démarrage Angular :

1. Remplacez l’entrée browsers dans votre fichier projet karma.conf.js de browsers: ['Chrome'] à browsers: ['ChromeHeadless'].

2. Remplacez l’entrée singleRun dans votre fichier projet karma.conf.js d’une valeur de false à true. Cette modification permet de s’assurer que le processus Karma s’arrête après son exécution.

React et Vue

Toutes les dépendances de vos applications React et Vue sont capturées dans votre fichier package.json. Votre fichier azure-pipelines.yml contient le script Node.js standard :

- script: |
    npm install
  displayName: 'npm install'

- script: |
    npm run build
  displayName: 'npm build'

Les fichiers de build se trouvent dans un nouveau dossier, dist (pour Vue) ou build (pour React). Cet extrait de code génère un artefact, www, qui est prêt pour la mise en production. Il utilise les tâches Programme d’installation de Node, Copier les fichiers et Publier les artefacts de build.

trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: UseNode@1
  inputs:
    version: '16.x'
  displayName: 'Install Node.js'

- script: |
    npm install
  displayName: 'npm install'

- script: |
    npm run build
  displayName: 'npm build'

- task: CopyFiles@2
  inputs:
    Contents: 'build/**' # Pull the build directory (React)
    TargetFolder: '$(Build.ArtifactStagingDirectory)'

- task: PublishBuildArtifacts@1
  inputs: 
    PathtoPublish: $(Build.ArtifactStagingDirectory) # dist or build files
    ArtifactName: 'www' # output artifact named www

Pour publier, pointez votre tâche de mise en production vers l’artefact dist ou build et utilisez la tâche Déploiement d’application web Azure.

Webpack

Vous pouvez utiliser un fichier de configuration webpack pour spécifier un compilateur, comme Babel ou TypeScript, pour transpiler du code JSX ou TypeScript en JavaScript brut et pour regrouper votre application.

- script: |
    npm install webpack webpack-cli --save-dev
    npx webpack --config webpack.config.js

Exécuteurs de tâches de build

Il est courant d’utiliser Gulp ou Grunt comme exécuteur de tâches pour générer et tester une application JavaScript.

Gulp

Gulp est préinstallé sur les agents hébergés par Microsoft. Exécutez la commande gulp dans le fichier YAML :

- script: gulp                       # include any additional options that are needed

Si les étapes de votre fichier gulpfile.js nécessitent une authentification avec un registre npm :

- task: npmAuthenticate@0
  inputs:
    customEndpoint: <Name of npm service connection>

- script: gulp                       # include any additional options that are needed

Ajoutez la tâche Publier les résultats des tests pour publier les résultats des tests JUnit ou xUnit sur le serveur.

- task: PublishTestResults@2
  inputs:
    testResultsFiles: '**/TEST-RESULTS.xml'
    testRunTitle: 'Test results for JavaScript using gulp'

Ajoutez la tâche Publier les résultats de la couverture du code pour publier les résultats de la couverture du code sur le serveur. Vous trouverez les métriques de couverture dans le résumé de la build, et vous pouvez télécharger des rapports HTML pour une analyse plus approfondie.

- task: PublishCodeCoverageResults@1
  inputs: 
    codeCoverageTool: Cobertura
    summaryFileLocation: '$(System.DefaultWorkingDirectory)/**/*coverage.xml'
    reportDirectory: '$(System.DefaultWorkingDirectory)/**/coverage'

Grunt

Grunt est préinstallé sur les agents hébergés par Microsoft. Pour exécuter la commande grunt dans le fichier YAML :

- script: grunt                      # include any additional options that are needed

Si les étapes de votre fichier Gruntfile.js nécessitent une authentification avec un registre npm :

- task: npmAuthenticate@0
  inputs:
    customEndpoint: <Name of npm service connection>

- script: grunt                      # include any additional options that are needed

Empaqueter et remettre votre code

Une fois que vous avez créé et testé votre application, vous pouvez charger la sortie de build sur Azure Pipelines, créer et publier un package npm ou Maven, ou empaqueter la sortie de build dans un fichier .zip pour le déploiement sur une application web.

Publier des fichiers sur Azure Pipelines

Pour charger l’intégralité du répertoire de travail des fichiers, utilisez la tâche Publier les artefacts de build et ajoutez ce qui suit à votre fichier azure-pipelines.yml.

- task: PublishBuildArtifacts@1
  inputs:
    PathtoPublish: '$(System.DefaultWorkingDirectory)'

Pour charger un sous-ensemble de fichiers, copiez d’abord les fichiers nécessaires à partir du répertoire de travail vers un répertoire intermédiaire avec la tâche Copier des fichiers, puis utilisez la tâche Publier les artefacts de build.

- task: CopyFiles@2
  inputs:
    SourceFolder: '$(System.DefaultWorkingDirectory)'
    Contents: |
      **\*.js
      package.json
    TargetFolder: '$(Build.ArtifactStagingDirectory)'

- task: PublishBuildArtifacts@1

Publier un module dans un registre npm

Si la sortie de votre projet est un module npm à utiliser par d’autres projets et non par une application web, utilisez la tâche npm pour publier le module dans un registre local ou dans le registre npm public. Fournissez une combinaison nom/version unique chaque fois que vous publiez.

Exemples

Le premier exemple suppose que vous gérez les informations de version (par exemple, via une version npm) par le biais des modifications apportées à votre fichier package.json dans le contrôle de version. L’exemple suivant utilise la tâche de script pour publier dans le registre public.

- script: npm publish

L’exemple suivant publie dans un registre personnalisé défini dans le fichier .npmrc de votre dépôt. Configurez une connexion de service npm pour injecter des informations d’identification d’authentification dans la connexion pendant l’exécution de la build.

- task: Npm@1
  inputs:
     command: publish
     publishRegistry: useExternalRegistry
     publishEndpoint: https://my.npmregistry.com

Le dernier exemple publie le module dans un flux de gestion de package Azure DevOps Services.

- task: Npm@1
  inputs:
     command: publish
     publishRegistry: useFeed
     publishFeed: https://my.npmregistry.com

Pour plus d’informations sur le contrôle de version et la publication de packages npm, consultez Publier des packages npm et Comment puis-je gérer les versions de mes packages npm dans le cadre du processus de build ?.

Déployer une application web

Pour créer une archive de fichiers .zip prête pour la publication dans une application web, utilisez la tâche Archiver les fichiers :

- task: ArchiveFiles@2
  inputs:
    rootFolderOrFile: '$(System.DefaultWorkingDirectory)'
    includeRootFolder: false

Pour publier cette archive dans une application web, consultez Déploiement d’applications web Azure.

Générer et envoyer une image au registre de conteneurs

Une fois que votre code source a été correctement généré et que vos tests unitaires sont en place et ont réussi, vous pouvez également générer une image et l’envoyer à un registre de conteneurs.

Dépanner

Si vous pouvez créer votre projet sur votre machine de développement, mais que vous rencontrez des difficultés pour le créer sur Azure Pipelines, explorez les causes potentielles et les actions correctives suivantes :

• Vérifiez que les versions de Node.js et de l’exécuteur de tâches sur votre ordinateur de développement correspondent à celles de l’agent. Vous pouvez inclure des scripts de ligne de commande comme node --version dans votre pipeline pour vérifier ce qui est installé sur l’agent. Utilisez le programme d’installation de l’outil Node (comme expliqué dans ce guide) pour déployer la même version sur l’agent, ou exécutez npm install des commandes pour mettre à jour les outils vers les versions souhaitées.

• Si vos builds échouent par intermittence pendant la restauration des packages, soit le registre npm rencontre des problèmes soit il y a des problèmes de mise en réseau entre le centre de données Azure et le registre. Nous ne pouvons pas contrôler ces facteurs. Découvrez si l’utilisation d’Azure Artifacts avec un registre npm comme source amont améliore la fiabilité de vos builds.

• Si vous utilisez nvm pour gérer différentes versions de Node.js, envisagez de passer à la tâche Programme d’installation de l’outil Node à la place. (nvm est installé pour des raisons historiques sur l’image macOS.) nvm gère les versions multiples de Node.js en ajoutant des alias d’interpréteur de commandes et en modifiant PATH, ce qui interagit mal avec la façon dont Azure Pipelines exécute chaque tâche dans un nouveau processus.

  La tâche Programme d’installation de l’outil Node gère ce modèle correctement. Toutefois, si votre travail nécessite l’utilisation de nvm, vous pouvez ajouter le script suivant au début de chaque pipeline :

  steps:
  - bash: |
      NODE_VERSION=16  # or whatever your preferred version is
      npm config delete prefix  # avoid a warning
      . ${NVM_DIR}/nvm.sh
      nvm use ${NODE_VERSION}
      nvm alias default ${NODE_VERSION}
      VERSION_PATH="$(nvm_version_path ${NODE_VERSION})"
      echo "##vso[task.prependPath]$VERSION_PATH"
  

  node et d’autres outils en ligne de commande fonctionnent alors pour le reste du travail de pipeline. À chaque étape où vous utilisez la commande nvm, démarrez le script avec le code suivant :

  - bash: |
      . ${NVM_DIR}/nvm.sh
      nvm <command>
  

Questions fréquentes (FAQ)

Q : Où puis-je en savoir plus sur Azure Artifacts et le service de gestion des packages ?

R : Gestion des packages dans Azure Artifacts

Q : Où puis-je en savoir plus sur les tâches ?

R : Tâches de build, de mise en production et de test

Q : Comment faire pour résoudre un échec de pipeline avec le message « ERREUR IRRÉCUPÉRABLE : échec de l’allocation de CALL_AND_RETRY_LAST – Mémoire JavaScript insuffisante » ?

R : Ce type d’échec se produit lorsque le package Node.js dépasse la limite d’utilisation de la mémoire. Pour résoudre le problème, ajoutez une variable de type NODE_OPTIONS et affectez-lui une valeur de --max_old_space_size=16384.

Q : Comment puis-je gérer les versions de mes packages npm dans le cadre du processus de build ?

R : Une option consiste à utiliser une combinaison du contrôle de version et de la version de npm. À la fin de l’exécution d’un pipeline, vous pouvez mettre à jour votre dépôt avec la nouvelle version. Dans ce YAML, il existe un dépôt GitHub, et le package est déployé sur npmjs. Votre build échoue en cas d’incompatibilité entre la version de votre package sur npmjs et votre fichier package.json.

variables:
    MAP_NPMTOKEN: $(NPMTOKEN) # Mapping secret var

trigger:
- none

pool:
  vmImage: 'ubuntu-latest'

steps: # Checking out connected repo
- checkout: self
  persistCredentials: true
  clean: true
    
- task: npmAuthenticate@0
  inputs:
    workingFile: .npmrc
    customEndpoint: 'my-npm-connection'
    
- task: UseNode@1
  inputs:
    version: '16.x'
  displayName: 'Install Node.js'

- script: |
    npm install
  displayName: 'npm install'

- script: |
    npm pack
  displayName: 'Package for release'

- bash: | # Grab the package version
    v=`node -p "const p = require('./package.json'); p.version;"`
    echo "##vso[task.setvariable variable=packageVersion]$v"

- task: CopyFiles@2
  inputs:
      contents: '*.tgz'
      targetFolder: $(Build.ArtifactStagingDirectory)/npm
  displayName: 'Copy archives to artifacts staging directory'

- task: CopyFiles@2
  inputs:
    sourceFolder: '$(Build.SourcesDirectory)'
    contents: 'package.json' 
    targetFolder: $(Build.ArtifactStagingDirectory)/npm
  displayName: 'Copy package.json'

- task: PublishBuildArtifacts@1 
  inputs:
    PathtoPublish: '$(Build.ArtifactStagingDirectory)/npm'
    artifactName: npm
  displayName: 'Publish npm artifact'

- script: |  # Config can be set in .npmrc
    npm config set //registry.npmjs.org/:_authToken=$(MAP_NPMTOKEN) 
    npm config set scope "@myscope"
    # npm config list
    # npm --version
    npm version patch --force
    npm publish --access public

- task: CmdLine@2 # Push changes to GitHub (substitute your repo)
  inputs:
    script: |
      git config --global user.email "username@contoso.com"
      git config --global user.name "Azure Pipeline"
      git add package.json
      git commit -a -m "Test Commit from Azure DevOps"
      git push -u origin HEAD:main