Personalizacion de JavaScript para Azure Pipelines

Puede usar Azure Pipelines para compilar las aplicaciones de JavaScript sin tener que configurar ninguna infraestructura propia. Las herramientas que se usan normalmente para compilar, probar y ejecutar aplicaciones JavaScript, como npm, Node, Yarn y Gulp, se instalan previamente en agentes hospedados por Microsoft en Azure Pipelines.

Para saber cuál es la versión de Node.js y npm preinstalada, consulte Agentes hospedados por Microsoft. Para instalar una versión específica de estas herramientas en agentes hospedados por Microsoft, agregue la tarea Instalador de herramientas de Node al principio del proceso. También puede usar un agente autohospedado.

Para crear la primera canalización con JavaScript, consulte el inicio rápido de JavaScript.

Uso de una versión específica de Node.js

Si necesita una versión de Node.js y npm que aún no esté instalada en el agente hospedado por Microsoft, use la tarea Instalador de herramientas de Node. Agregue el siguiente fragmento de código a su archivo azure-pipelines.yml.

Nota:

Los agentes hospedados se actualizan periódicamente y la configuración de esta tarea da como resultado invertir un tiempo considerable en una actualización a una versión secundaria más reciente cada vez que se ejecuta la canalización. Use esta tarea solo cuando necesite una versión específica de Node en la canalización.

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

Para actualizar solo la herramienta npm, ejecute el comando npm i -g npm@version-number en el proceso de compilación.

Uso de varias versiones de Node

Puede compilar y probar la aplicación en varias versiones de Node con la tarea Instalador de herramientas de 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

Instalación de herramientas en el agente de compilación

Si tiene herramientas que son dependencias de desarrollo en el archivo de proyecto package.json o package-lock.json, instale las herramientas y dependencias mediante npm. La versión exacta de las herramientas se define en el proyecto, aislada de otras versiones existentes en el agente de compilación.

Use un script o la tarea npm.

Uso de un script para instalar con package.json

- script: npm install --only=dev

Uso de la tarea npm para instalar con package.json

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

Ejecute las herramientas instaladas de esta manera mediante el ejecutor de paquetes npm npx, que detecta las herramientas instaladas de esta manera en su resolución de ruta de acceso. En el ejemplo siguiente llama al ejecutor de pruebas mocha, pero busca la versión instalada como una dependencia de desarrollo antes de usar una versión instalada globalmente (mediante npm install -g).

- script: npx mocha

Para instalar herramientas necesarias para el proyecto, pero que no están establecidas como dependencias de desarrollo en package.json, llame a npm install -g desde una fase de script de la canalización.

En el ejemplo siguiente se instala la versión más reciente de la CLI de Angular mediante npm. A continuación, el resto de la canalización puede usar la herramienta ng de otras fases script.

Nota:

En los agentes de Linux hospedados por Microsoft, comience el comando con sudo, como sudo npm install -g.

- script: npm install -g @angular/cli

Sugerencia

Estas tareas se ejecutan cada vez que se ejecuta la canalización, por lo que tenga en cuenta el impacto que tienen las herramientas de instalación en los tiempos de compilación. Considere la posibilidad de configurar agentes autohospedados con la versión de las herramientas que necesita si la sobrecarga se convierte en un impacto grave en el rendimiento de la compilación.

Administración de dependencias

En la compilación, use Yarn o Azure Artifacts para descargar paquetes del registro npm público. Este registro es un tipo de registro npm privado que se especifica en el archivo .npmrc.

Uso de npm

Puede usar npm de las siguientes formas a fin de descargar paquetes para la compilación:

• Ejecute directamente npm install en la canalización, ya que es la manera más sencilla de descargar paquetes desde un registro sin autenticación. Si la compilación no necesita dependencias de desarrollo en el agente para ejecutarse, puede acelerar los tiempos de compilación con la opción --only=prod para npm install.
• Use una tarea npm. Esta tarea es útil cuando se usa un registro autenticado.
• Use una tarea de autenticación de npm. Esta tarea es útil cuando se ejecuta npm install desde dentro de los ejecutores de tareas: Gulp, Grunt o Maven.

Si desea especificar un registro npm, coloque las direcciones URL en un archivo .npmrc en el repositorio. Si la fuente se autentica, cree una conexión de servicio npm en la pestaña Servicios de Configuración del proyecto para administrar sus credenciales.

Para instalar paquetes npm con un script en la canalización, agregue el siguiente fragmento de código a azure-pipelines.yml.

- script: npm install

Para usar un registro privado especificado en el archivo.npmrc, agregue el siguiente fragmento de código a azure-pipelines.yml.

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

Para pasar las credenciales del registro a los comandos npm a través de ejecutores de tareas como Gulp, agregue la siguiente tarea a azure-pipelines.yml antes de llamar al ejecutor de tareas.

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

Si las compilaciones producen errores ocasionalmente debido a problemas de conexión al restaurar paquetes desde el registro npm, puede usar Azure Artifacts con orígenes ascendentes y almacenar en caché los paquetes. Las credenciales de la canalización se usan automáticamente al conectarse a Azure Artifacts. Estas credenciales se derivan normalmente de la cuenta del servicio de compilación de recopilación de proyectos.

Si usa agentes hospedados por Microsoft, obtendrá una nueva máquina cada vez que ejecute una compilación, lo que significa restaurar las dependencias cada vez, haciendo que pueda tardar un tiempo significativo. Para mitigarlo, puede usar Azure Artifacts o un agente autohospedado; a continuación, obtendrá la ventaja de usar la caché de paquetes.

Uso de Yarn

Use una fase de script a fin de invocar a Yarn para restaurar las dependencias. Yarn se instala previamente en algunos agentes hospedados por Microsoft. Puede instalarlo y configurarlo en agentes autohospedados como cualquier otra herramienta.

- script: yarn install

Ejecución de compiladores de JavaScript

Use compiladores como Babel y el compilador TypeScripttsc para convertir el código fuente en versiones utilizables por el entorno de ejecución de Node.js o en exploradores web.

Si tiene un objeto de script configurado en el archivo de proyecto package.json que ejecuta el compilador, invóquelo en la canalización mediante una tarea de script.

- script: npm run compile

Puede llamar a los compiladores directamente desde la canalización mediante la tarea de script. Estos comandos se ejecutan desde la raíz del repositorio de código fuente clonado.

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

Ejecutar pruebas unitarias

Configure las canalizaciones para ejecutar las pruebas de JavaScript y que generen resultados con formato XML JUnit. A continuación, puede publicar los resultados mediante la tarea de resultados de la prueba de publicación integrada.

Si la plataforma de pruebas no admite la salida de JUnit, agregue compatibilidad mediante un módulo de informes de asociados, como mocha-junit-reporter. Puede actualizar el script de prueba para usar el informador de JUnit, o si el informador admite opciones de línea de comandos, pase esas opciones a la definición de la tarea.

En la tabla siguiente se enumeran los ejecutores de pruebas más usados y los informadores que se pueden usar para generar resultados XML:

Ejecutor de pruebas	Informadores para generar informes XML
mocha	mocha-junit-reporter cypress-multi-reporter
jasmine	jasmine-reporters
jest	jest-junit jest-junit-reporter
karma	karma-junit-reporter
Ava	tap-xunit

En el ejemplo siguiente se usa mocha-junit-reporter y se invoca a mocha test directamente mediante un script. Este script genera la salida XML de JUnit en la ubicación predeterminada de ./test-results.xml.

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

Si ha definido un script test en el archivo package.json del proyecto, puede invocarlo mediante npm test.

- script: npm test

Publicación de los resultados de las pruebas

Para publicar los resultados, use la tarea Publicar resultados de pruebas.

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

Publicación de resultados de cobertura de código

Si los scripts de prueba ejecutan una herramienta de cobertura de código, como Istanbul, agregue la tarea Publicar resultados de cobertura de código. Al hacerlo, puede encontrar métricas de cobertura en el resumen de compilación y descargar informes HTML para su posterior análisis. La tarea espera la salida de informes de Cobertura o JaCoCo, por lo que debe asegurarse de que la herramienta de cobertura de código se ejecuta con las opciones necesarias para generar la salida correcta. Por ejemplo, --report cobertura.

En el ejemplo siguiente se usa nyc, la interfaz de la línea de comandos de Istanbul, junto con mocha-junit-reporter y se invoca el comando 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'

Prueba del explorador de un extremo a otro

Ejecute pruebas en exploradores sin periféricos como parte de la canalización con herramientas como Protractor o Karma. A continuación, publique los resultados de la compilación en Azure DevOps con los pasos siguientes:

1. Instale un controlador de prueba de explorador sin periféricos, como Chrome o Firefox, o una herramienta de simulacro de explorador como PhantomJS, en el agente de compilación.
2. Configure la plataforma de pruebas para usar la opción de controlador o explorador sin periféricos que prefiera según la documentación de la herramienta.
3. Configure la plataforma de pruebas (normalmente con un complemento informador o una configuración) para generar salidas de pruebas con formato JUnit.
4. Configure una tarea de script para ejecutar los comandos de la CLI necesarios para iniciar las instancias del explorador sin periféricos.
5. Ejecute las pruebas de un extremo a otro en las fases de canalización junto con las pruebas unitarias.
6. Publique los resultados mediante la misma tarea Publicar resultados de pruebas junto con las pruebas unitarias.

Empaquetar aplicaciones web

Empaquetar aplicaciones para agrupar todos los módulos de aplicación con salidas intermedias y dependencias en recursos estáticos listos para la implementación. Agregue una fase de canalización después de la compilación y las pruebas para ejecutar una herramienta como webpack o ng build mediante la CLI de Angular.

En el primer ejemplo se llama a webpack. Para conseguirlo, asegúrese de que webpack está configurado como una dependencia de desarrollo en el archivo de proyecto package.json. Esto ejecuta webpack con la configuración predeterminada a menos que tenga un archivo webpack.config.js en la carpeta raíz del proyecto.

- script: webpack

En el ejemplo siguiente se usa la tarea npm para llamar a npm run build y luego al objeto de script build definido en el archivo package.json del proyecto. El uso de objetos de script en el proyecto mueve la lógica de la compilación en el código fuente y fuera de la canalización.

- script: npm run build

Implementación de plataformas de JavaScript

Angular

Para las aplicaciones de Angular, puede incluir comandos específicos de Angular, como ng test, ng build y ng e2e. Para usar los comandos de la CLI de Angular en la canalización, instale el paquete angular/cli npm en el agente de compilación.

Nota:

En los agentes de Linux hospedados por Microsoft, comience el comando con sudo, como sudo npm install -g.

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

Para las pruebas de la canalización que requieren que se ejecute un explorador, como el comando ng test en la aplicación de inicio, que ejecuta Karma, use un explorador sin periféricos en lugar de un explorador estándar. En la aplicación de inicio de Angular:

1. Cambie la entrada browsers del archivo de proyecto karma.conf.js de browsers: ['Chrome'] a browsers: ['ChromeHeadless'].

2. Cambie la entrada singleRun del archivo de proyecto karma.conf.js de un valor de false a true. Este cambio ayuda a asegurarse de que el proceso Karma se detiene después de que se ejecute.

React y Vue

Todas las dependencias de las aplicaciones de React y Vue se capturan en el archivo package.json. El archivo azure-pipelines.yml contiene el script de Node.js estándar:

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

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

Los archivos de compilación están en una carpeta nueva, dist para Vue o build para React. Este fragmento de código compila un artefacto, www, que está listo para su lanzamiento. Usa las tareas Instalador de nodo, Copiar archivosy Publicar artefactos de compilación.

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

Para liberarla, dirija la tarea de liberación al artefacto dist o build y use la tarea Implementación de aplicación web de Azure.

Webpack

Puede usar un archivo de configuración de webpack para especificar un compilador, como Babel o TypeScript, para transpilar JSX o TypeScript a JavaScript sin formato y para agrupar la aplicación.

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

Ejecutores de tareas de compilación

Es habitual usar Gulp o Grunt como ejecutor de tareas para compilar y probar una aplicación de JavaScript.

Gulp

Gulp se preinstala en agentes hospedados de Microsoft. Ejecute el comando gulp en el archivo YAML:

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

Si los pasos del archivo de gulpfile.js requieren autenticación con un registro npm:

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

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

Agregue la tarea Publicar resultados de pruebas para publicar resultados de pruebas JUnit o xUnit en el servidor.

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

Agregue la tarea Publicar resultados de cobertura de código para publicar los resultados de cobertura de código en el servidor. Puede encontrar métricas de cobertura en el resumen de compilación y puede descargar informes HTML para su posterior análisis.

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

Grunt

Grunt se instala previamente en agentes hospedados de Microsoft. Para ejecutar el comando Grunt en el archivo YAML:

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

Si los pasos del archivo Gruntfile.js requieren autenticación con un registro npm:

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

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

Empaquetado y entrega del código

Después de compilar y probar la aplicación, puede cargar la salida de compilación en Azure Pipelines, crear y publicar un paquete npm o Maven o empaquetar la salida de compilación en un archivo .zip para la implementación en una aplicación web.

Publicación de archivos en Azure Pipelines

Para cargar todo el directorio de trabajo de los archivos, use la tarea Publicar artefactos de compilación y agregue lo siguiente al archivo azure-pipelines.yml.

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

Para cargar un subconjunto de archivos, copie primero los archivos necesarios del directorio de trabajo en un directorio provisional con la tarea Copiar archivos y, a continuación, use la tarea Publicar artefactos de compilación.

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

- task: PublishBuildArtifacts@1

Publicación de un módulo en un registro npm

Si la salida del proyecto es un módulo npm que usan otros proyectos y no una aplicación web, use la tarea npm para publicar el módulo en un registro local o en el registro npm público. Proporcione una combinación de nombre y versión única cada vez que publique.

Ejemplos

En el primer ejemplo se supone que administra la información de la versión (por ejemplo, con una versión de npm) mediante los cambios en el archivo package.json en el control de versiones. En el ejemplo siguiente se usa la tarea script para publicar en el registro público.

- script: npm publish

En el ejemplo siguiente se publica en un registro personalizado definido en el repositorio del archivo .npmrc. Configure una conexión de servicio npm para insertar credenciales de autenticación en la conexión a medida que se ejecuta la compilación.

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

En el ejemplo final se publica el módulo en una fuente de administración de paquetes de Azure DevOps Services.

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

Para más información sobre el control de versiones y la publicación de paquetes npm, consulte Publicación de paquetes npm y ¿Cómo puedo crear una versión de mis paquetes npm como parte del proceso de compilación?.

Implementación de una aplicación sitio

Para crear un archivo de archivos .zip que esté listo para publicarse en una aplicación web, use la tarea Archivar archivos:

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

Para publicar este archivo en una aplicación web, consulte Implementación de aplicaciones web de Azure.

Compilación e inserción de imágenes en un registro de contenedor

Una vez que el código fuente se compila de forma correcta y las pruebas unitarias se han realizado de modo correcto, también puede compilar una imagen e insertarla en un registro de contenedor.

Solución de problemas

Si puede compilar el proyecto en la máquina de desarrollo pero tiene problemas para compilarlo en Azure Pipelines, explore las siguientes causas potenciales y acciones correctivas:

• Compruebe que las versiones de Node.js y el ejecutor de tareas de la máquina de desarrollo coincidan con las del agente. Puede incluir scripts de línea de comandos como node --version en la canalización para comprobar lo que está instalado en el agente. Use el Instalador de herramientas de Node (como se explica en esta guía) para implementar la misma versión en el agente o ejecutar comandos npm install para actualizar las herramientas a las versiones deseadas.

• Si las compilaciones producen un error intermitente mientras restaura paquetes, el registro npm tiene problemas o hay problemas de red entre el centro de datos de Azure y el registro. No podemos controlar estos factores. Explore si el uso de Azure Artifacts con un registro npm como origen ascendente mejora la confiabilidad de las compilaciones.

• Si usa nvm para administrar diferentes versiones de Node.js, considere la posibilidad de cambiar a la tarea Instalador de herramientas de Node en su lugar. (nvm se instala por tradición en la imagen de macOS). nvm administra varias versiones de Node.js mediante la adición de alias de shell y la modificación de PATH, que interactúa mal con la forma en que Azure Pipelines ejecuta cada tarea en un proceso nuevo.

  La tarea Instalador de herramientas de Node controla correctamente este modelo. Sin embargo, si el trabajo requiere el uso de nvm, puede agregar el siguiente script al principio de cada canalización:

  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"
  

  A continuación, node y otras herramientas de línea de comandos trabajan para el resto del trabajo de canalización. En cada paso en el que se usa el comando nvm, inicie el script con el código siguiente:

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

Preguntas más frecuentes

P: ¿Dónde puedo obtener más información sobre Azure Artifacts y el servicio administración de paquetes?

R: Administración de paquetes en Azure Artifacts

P: ¿Dónde puedo obtener más información sobre las tareas?

R: Tareas de compilación, versión y prueba

P: ¿Cómo puedo corregir un error de canalización con el mensaje "FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory"?

R: Este tipo de error se produce cuando el paquete de Node.js ha superado el límite de uso de la memoria. Para resolver la incidencia, agregue una variable como NODE_OPTIONS y asígnele un valor de --max_old_space_size=16384.

P: ¿Cómo puedo crear una versión de mis paquetes npm como parte del proceso de compilación?

R: Una opción es usar una combinación de control de versiones y versión de npm. Al final de una ejecución de canalización, puede actualizar el repositorio con la nueva versión. En este YAML, hay un repositorio de GitHub y el paquete se implementa en npmjs. Se produce un error en la compilación si la versión del paquete en npmjs y el archivo package.json no coinciden.

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