Compartir a través de


Pipelines para aplicaciones de JavaScript

En este artículo se explica cómo funciona Azure Pipelines con aplicaciones de JavaScript. Los agentes hospedados por Microsoft preinstalan herramientas comunes de compilación, prueba e implementación de JavaScript, como npm, Node.js, Yarn y Gulp sin necesidad de configurar ninguna infraestructura. También puede configurar agentes autohospedados.

Para crear rápidamente una canalización para JavaScript, consulte el inicio rápido de JavaScript.

Instaladores de herramientas de node

Para instalar Node.js y versiones de npm que no están preinstaladas o para instalar las herramientas en agentes autohospedados:

Para instalar una versión de Node.js específica, agregue el código siguiente al archivo azure-pipelines.yml :

- task: UseNode@1
  inputs:
    version: '16.x' # replace with the version you need

Nota:

Esta tarea puede requerir una cantidad significativa de tiempo para actualizarse a una versión menor más reciente cada vez que se ejecuta la tubería. Los agentes hospedados por Microsoft se actualizan periódicamente, por lo que use esta tarea solo para instalar versiones específicas de Node que no estén preinstaladas. Para averiguar qué Node.js y las versiones de npm están preinstaladas en agentes hospedados por Microsoft, consulte Software.

Uso de varias versiones de Node

Puede usar la tarea Usar Node.js ecosistema v1 con una matrix estrategia para compilar y probar la aplicación en varias versiones de Node.js. Para obtener más información, consulte Configuración de varios trabajos.

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 la herramienta de gestión de dependencias

Si tiene herramientas de dependencia de desarrollo en el proyecto package.json o package-lock.json archivo, instale las herramientas y las dependencias a través de npm. El archivo de proyecto define la versión exacta de las herramientas, independientemente de otras versiones que existen en el agente de compilación.

Para instalar estas herramientas en el agente de compilación, use un script, la tarea npm o una tarea de línea de comandos en la canalización.

Para usar un script:

- script: npm install --only=dev

Para usar la tarea npm:

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

Las herramientas que instale de esta manera usan el ejecutor de paquetes npm npx , que detecta las herramientas en su resolución PATH. En el ejemplo siguiente se llama al mocha ejecutor de pruebas y se usa la versión de dependencia de desarrollo en lugar de la versión instalada globalmente a través de npm install -g.

- script: npx mocha

Para instalar herramientas que el proyecto necesita y que no están definidas como dependencias de desarrollo en package.json, ejecute npm install -g desde un script del pipeline. En el ejemplo siguiente se instala la versión más reciente de la CLI de Angular mediante npm. Luego, otros scripts de la canalización pueden usar los comandos de Angular ng.

- script: npm install -g @angular/cli

Nota:

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

Estas tareas de instalación de herramientas se ejecutan cada vez que se ejecuta la canalización, por lo que debe tener en cuenta su impacto en los tiempos de compilación. Si la sobrecarga afecta seriamente al rendimiento de la compilación, considere la posibilidad de usar agentes autohospedados preconfigurados con las versiones de herramientas que necesita.

Nota:

Estas tareas de instalación de herramientas se ejecutan cada vez que se ejecuta la canalización, por lo que debe tener en cuenta su impacto en los tiempos de compilación.

Descargas de paquetes de dependencias

Puede usar Yarn o Azure Artifacts para descargar paquetes desde el registro público de npm o un registro npm privado que especifique en un archivo *.npmrc . Para especificar un registro de npm, agregue su dirección URL al archivo *.npmrc en el repositorio de código.

Uso de npm

Puede usar npm para descargar paquetes de compilación en la canalización de las maneras siguientes:

  • Para obtener la manera más sencilla de descargar paquetes sin autenticación, ejecute npm installdirectamente .
  • Para usar un registro autenticado, agregue la tarea npm .
  • Para ejecutar npm install desde los ejecutores de tareas Gulp, Grunt o Maven, use la tarea de autenticación de npm .

Nota:

Si la fuente de npm usa la autenticación, debe crear una conexión de servicio npm en la pestaña Servicios en la configuración del proyecto de Azure DevOps para administrar sus credenciales.

Para instalar paquetes de npm directamente, use el siguiente script en azure-pipelines.yml. Si el agente de compilación no necesita dependencias de desarrollo, puede acelerar los tiempos de compilación agregando la --only=prod opción a npm install.

- script: npm install --only=prod

Para usar un registro privado especificado en el archivo *.npmrc, agregue la tarea Npm@1 a azure-pipelines.yml.

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

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

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

Nota:

Los agentes hospedados por Microsoft usan una nueva máquina con cada compilación. La restauración de dependencias puede tardar un tiempo considerable. Para mitigar el problema, puede usar Azure Artifacts o un agente autohospedado con la caché de paquetes.

Si las compilaciones producen errores ocasionalmente debido a problemas de conexión al restaurar paquetes desde el registro de npm, puede usar Azure Artifacts con orígenes ascendentes para almacenar en caché los paquetes. Azure Artifacts usa automáticamente las credenciales de la canalización, que normalmente se derivan de la cuenta del Servicio de Compilación de la Colección de Proyectos.

Nota:

La restauración de dependencias puede tardar un tiempo considerable. Para mitigar el problema, puede usar Azure Artifacts o un agente autohospedado con la caché de paquetes.

Si las compilaciones producen errores ocasionalmente debido a problemas de conexión al restaurar paquetes desde el registro de npm, puede usar Azure Artifacts con orígenes ascendentes para almacenar en caché los paquetes. Azure Artifacts usa automáticamente las credenciales de la canalización, que normalmente se derivan de la cuenta del Servicio de Compilación de la Colección de Proyectos.

Uso de Yarn

Use un script para instalar Yarn para restaurar las dependencias. Yarn está preinstalado en algunos agentes hospedados por Microsoft. Puede instalar y configurar Yarn en agentes autohospedados como cualquier otra herramienta.

- script: yarn install

También puede usar la tarea CLI o la tarea Bash en su canalización para invocar Yarn.

Compiladores de JavaScript

Las aplicaciones de JavaScript usan compiladores como Babel y el compilador de 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 package.json del proyecto para ejecutar el compilador, puede invocarlo en la canalización.

- script: npm run compile

También puede llamar a compiladores directamente desde la canalización mediante un 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

Puede usar la tarea npm para compilar el código si el proyectopackage.json define un script de compilación. Si no define un script de compilación, puede usar la tarea de Bash para compilar el código.

Pruebas unitarias

Puede configurar las canalizaciones para ejecutar las pruebas de JavaScript para que generen resultados en el formato XML JUnit. Después, puede publicar los resultados mediante la tarea Publicar resultados de pruebas .

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

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

Ejecutor de pruebas Periodistas para informes XML
Mocha mocha-junit-reporter
cypress-multi-reporter
Jazmín 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 definió un test script 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 resultados de pruebas, 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 Estambul, agregue la tarea Publicar resultados de cobertura de código . A continuación, puede ver las 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. Asegúrese 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 la interfaz de línea de comandos de Estambul nyc junto con mocha-junit-reporter e invoca 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'

Pruebas de explorador de un extremo a otro

La canalización puede usar herramientas como Protractor o Karma para ejecutar pruebas en exploradores sin encabezado y, a continuación, publicar resultados de pruebas. Para configurar las pruebas del explorador y publicar resultados, siga estos pasos:

  1. Instale un controlador de prueba de explorador sin encabezado, como Chrome o Firefox, o una herramienta simulada del explorador, como PhantomJS, en el agente de compilación.
  2. Configure el framework de pruebas para usar tu navegador sin cabeza o la opción de controlador según la documentación de la herramienta.
  3. Configura tu marco de pruebas para generar resultados de pruebas con formato JUnit, normalmente con un complemento de informe o una configuración.
  4. Agregue un script o una tarea de la CLI para iniciar las instancias del explorador sin encabezado.
  5. Ejecute las pruebas de un extremo a otro en las fases de canalización junto con las pruebas unitarias.
  6. Publique los resultados junto con las pruebas unitarias mediante la misma tarea Publicar resultados de pruebas .

Empaquetado y entrega

Después de compilar y probar la aplicación, puede hacer lo siguiente:

  • Cargue la salida de compilación en Azure Pipelines.
  • Cree y publique un paquete npm o Maven.
  • Empaquete 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 el directorio de trabajo completo, agregue la tarea Publicar artefactos de compilación 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 de ensayo 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 npm módulo para que otros proyectos usen y no sea una aplicación web, use la tarea npm para publicar el módulo en un registro local o en el registro de npm público. Proporcione una combinación de nombre y versión única cada vez que publique.

En el ejemplo siguiente se usa el script para publicar en el registro de npm público. En el ejemplo se supone que administra información de versión como la versión de npm a través de un archivo package.json en el control de versiones.

- script: npm publish

En el ejemplo siguiente se publica en un registro personalizado definido en el archivo *.npmrc del repositorio. 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 siguiente 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 obtener 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 versionar mis paquetes de npm como parte del proceso de compilación.

Empaquetar e implementar una aplicación web

Puede empaquetar aplicaciones para agrupar todos los módulos 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 la compilación ng de la CLI de Angular.

En el ejemplo siguiente se llama a webpack. Para que este proceso funcione, asegúrese de que webpack esté configurado como una dependencia de desarrollo en el archivo de package.json. Este script se 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 npm run build para llamar al build objeto de script definido en el archivo package.json del proyecto. El uso del objeto de script en su proyecto mueve la lógica de compilación al código fuente y fuera de la canalización.

- script: npm run build

También puede usar la CLI o tarea Bash en su canalización para invocar su herramienta de empaquetado, como webpack o la de Angular ng build.

Para crear un archivo *.zip archivo que esté listo para publicar 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 en Azure App Service mediante Azure Pipelines.

Marcos de JavaScript

Puede instalar paquetes en la canalización para admitir varios frameworks de JavaScript.

Angular

En el caso de las aplicaciones de Angular, puede ejecutar comandos específicos de Angular, como ng test, ng buildy 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.

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

Nota:

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

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

  • Cambie la entrada browsers del archivo de proyecto karma.conf.js de browsers: ['Chrome'] a browsers: ['ChromeHeadless'].
  • Cambie la entrada singleRun del archivo de proyecto karma.conf.js de false a true. Este cambio ayuda a garantizar que el proceso de Karma se detenga después de ejecutarse.

React y Vue

Todas las dependencias de las aplicaciones react y Vue se capturan en el archivo package.json . El archivo azure-pipelines.yml contiene los scripts estándar npm .

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

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

Los archivos de compilación se encuentran en una carpeta nueva, dist para Vue o compilación para React. En el ejemplo siguiente se compila un artefacto, www, que está listo para su lanzamiento. La canalización usa las tareas Usar Node.js, Copiar archivo y 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 publicar la aplicación, apunte la tarea de versión al artefacto dist o build y use la tarea Azure Web App.

Webpack

Puede usar un archivo de configuración de webpack para especificar un compilador como Babel o TypeScript, para transpilar JavaScript XML (JSX) o TypeScript a JavaScript plano y para empaquetar su 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 ejecutores de tareas para compilar y probar aplicaciones de JavaScript.

Gulp

Gulp está preinstalado en agentes hospedados por Microsoft.

Puede ejecutar el gulp comando en el archivo de canalización de YAML.

- script: gulp # add any needed options

Si los pasos del archivo gulpfile.js requieren autenticación con un registro de npm, agregue la tarea de autenticación de npm .

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

- script: gulp

Para publicar resultados de pruebas de JUnit o xUnit en el servidor, agregue la tarea Publicar resultados de pruebas .

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

Para publicar los resultados de cobertura de código en el servidor, agregue la tarea Publicar resultados de cobertura de código . 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 está preinstalado en agentes hospedados por Microsoft.

Puede ejecutar el grunt comando en el archivo YAML.

- script: grunt # add any needed options

Si los pasos del archivo Gruntfile.js requieren autenticación con un registro de npm, agregue la tarea de autenticación de npm .

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

- script: grunt

Solución de problemas

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

  • Compruebe que las versiones de Node.js y del 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 las versiones instaladas en el agente. Utilice la Use Node.js tarea para instalar la misma versión en el agente, o ejecute npm install comandos para actualizar las versiones de la herramienta.

  • Si las compilaciones fallan de forma intermitente mientras se restauran los paquetes, ya sea que el registro de NPM tenga problemas o haya problemas de red entre el centro de datos de Azure y el registro. 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 versiones diferentes de Node.js, considere la posibilidad de cambiar a la tarea Usar Node.js (UseNode@1). nvm se instala por motivos históricos en la imagen de macOS. nvm administra varias versiones de Node.js agregando alias de shell y modificando PATH, lo que interactúa mal con la forma en que Azure Pipelines ejecuta cada tarea en un nuevo proceso. Para más información, consulte Ejecuciones de canalización.

    La Use Node.js tarea controla este modelo correctamente. Sin embargo, si su trabajo requiere usar nvm, puedes agregar el siguiente script al principio de cada tubería:

    steps:
    - bash: |
        NODE_VERSION=16  # or your preferred version
        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

¿Cómo puedo solucionar un fallo de canalización con el mensaje 'ERROR IRRECUPERABLE: CALL_AND_RETRY_LAST Falló la asignación - el montón de JavaScript está sin memoria'?

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

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

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. La siguiente canalización de YAML tiene un repositorio de GitHub y el paquete se implementa en npmjs. Se produce un error en la compilación si hay una discrepancia entre la versión del paquete en npmjs y el archivo 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