Personalizar JavaScript para Azure Pipelines

Você pode usar o Azure Pipelines para criar seus aplicativos JavaScript sem precisar configurar uma infraestrutura própria. As ferramentas que você normalmente usa para criar, testar e executar os aplicativos JavaScript, como npm, Node, Yarn e Gulp, são pré-instaladas em agentes hospedados pela Microsoft no Azure Pipelines.

Para obter a versão do Node.js e do npm pré-instalada, veja agentes hospedados pela Microsoft. Para instalar uma versão específica dessas ferramentas em agentes hospedados pela Microsoft, adicione a tarefa Instalador de Ferramentas do Node ao início do processo. Você também pode usar um agente auto-hospedado.

Para criar seu primeiro pipeline com JavaScript, confira o início rápido do JavaScript.

Usar uma versão específica do Node.js

Se você precisar de uma versão do Node.js e do npm que ainda não esteja instalada no agente hospedado pela Microsoft, use a tarefa Instalador de Ferramentas do Node. Adicione o snippet de código a seguir ao seu arquivo azure-pipelines.yml.

Observação

Os agentes hospedados são atualizados regularmente e a configuração dessa tarefa resulta em um tempo significativo de atualização para uma versão secundária mais recente, sempre que o pipeline é executado. Use essa tarefa somente quando precisar de uma versão específica do Node no seu pipeline.

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

Para atualizar apenas a ferramenta npm, execute o comando npm i -g npm@version-number no seu processo de build.

Usar várias versões do Node

Você pode criar e testar seu aplicativo em várias versões do Node com a tarefa Instalador de Ferramentas do 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

Instalar ferramentas no agente de build

Se você tiver ferramentas que são dependências de desenvolvimento no arquivo package.json ou package-lock.json do seu projeto, instale suas ferramentas e dependências pelo npm. A versão exata das ferramentas é definida no projeto, isolada de outras versões que existem no agente de build.

Use um script ou a tarefa npm.

Usar um script para instalar com o package.json

- script: npm install --only=dev

Usar a tarefa npm para instalar com o package.json

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

Execute as ferramentas instaladas dessa forma usando o executor de pacote npx do npm, que detecta as ferramentas instaladas dessa forma na resolução de caminho. O exemplo a seguir chama o executor de teste mocha, mas procura a versão instalada como uma dependência de desenvolvimento, antes de usar uma versão instalada globalmente (por meio do npm install -g).

- script: npx mocha

Para instalar as ferramentas necessários para seu projeto precisa, mas que não estão definidas como dependências de desenvolvimento no package.json, chame npm install -g em uma fase de script do seu pipeline.

O exemplo a seguir instala a versão mais recente da CLI do Angular usando npm. O restante do pipeline pode usar a ng ferramenta de outras fases script.

Observação

Nos agentes do Linux hospedados pela Microsoft, introduza o comando com sudo, como sudo npm install -g.

- script: npm install -g @angular/cli

Dica

Essas tarefas são executadas sempre que o pipeline é executado. Portanto, lembre-se do impacto que a instalação das ferramentas tem nos tempos de build. Configure os agentes auto-hospedados com a versão das ferramentas necessárias, se a sobrecarga se tornar um impacto sério no desempenho do build.

Gerenciar dependências

No seu build, use o Yarn ou o Azure Artifacts para baixar pacotes do registro npm público. Esse registro é um tipo de registro npm privado que você especifica no arquivo .npmrc.

Usar npm

Você pode usar o npm das seguintes maneiras para baixar pacotes para seu build:

• Execute npm install diretamente no seu pipeline, pois é a maneira mais simples de baixar pacotes de um registro sem autenticação. Se o build não precisar de dependências de desenvolvimento no agente para ser executado, você poderá acelerar os tempos de build com a opção --only=prod para npm install.
• Use uma tarefa npm. Essa tarefa é útil quando você está usando um registro autenticado.
• Use uma tarefa npm authenticate. Essa tarefa é útil quando você executa npm install de dentro dos seus executores de tarefas – Gulp, Grunt ou Maven.

Se você quiser especificar um registro npm, coloque as URLs em um arquivo .npmrc no seu repositório. Se o feed for autenticado, crie uma conexão de serviço do npm na guia Serviços nas Configurações do projeto para gerenciar suas credenciais.

Para instalar pacotes npm com um script no seu pipeline, adicione o snippet a seguir a azure-pipelines.yml.

- script: npm install

Para usar um registro privado especificado no seu arquivo .npmrc, adicione o snippet a seguir a azure-pipelines.yml.

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

Para passar credenciais do registro para comandos npm usando os executores de tarefas, como o Gulp, adicione a tarefa a seguir a azure-pipelines.yml, antes de chamar o executor de tarefas.

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

Se os builds falharem ocasionalmente devido a problemas de conexão ao restaurar pacotes do registro npm, você poderá usar o Azure Artifacts com upstream fontes e armazenar em cache os pacotes. As credenciais do pipeline são usadas automaticamente, quando você se conecta ao Azure Artifacts. Normalmente, essas credenciais são derivadas da conta do Serviço de Build da Coleção de Projetos.

Se você estiver usando agentes hospedados pela Microsoft, receberá um novo computador sempre que executar um build, o que significa restaurar as dependências todas as vezes, o que pode levar um tempo significativo. Para mitigação, você pode usar o Azure Artifacts ou um agente auto-hospedado e, em seguida, obter o benefício de usar o cache de pacotes.

Usar Yarn

Use uma fase de script para invocar o Yarn para restaurar dependências. O Yarn vem pré-instalado em alguns agentes hospedados pela Microsoft. Você pode instalá-lo e configurá-lo em agentes auto-hospedados como qualquer outra ferramenta.

- script: yarn install

Executar compiladores JavaScript

Use compiladores como Babel e o compilador TypeScripttsc para converter o código-fonte em versões utilizáveis pelo runtime do Node.js ou em navegadores da Web.

Se você tiver um objeto de script configurado no arquivo de projeto package.json que executa o compilador, invoque-o no seu pipeline usando uma tarefa script.

- script: npm run compile

Você pode chamar os compiladores diretamente do pipeline usando a tarefa script. Esses comandos são executados na raiz do repositório de código-fonte clonado.

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

Executar testes de unidade

Configure seus pipelines para executar seus testes javaScript de modo que produzam resultados formatados no formato XML JUnit. Você pode publicar os resultados usando a tarefa interna Publicar resultados de teste.

Se a estrutura de teste não der suporte à saída JUnit, adicione suporte usando um módulo de relatório de parceiros, como mocha-junit-reporter. Você pode atualizar o script de teste para usar o repórter do JUnit ou, se o relator der suporte a opções de linha de comando, passe essas opções para a definição da tarefa.

A tabela a seguir lista os executores de teste mais usados e os relatores que podem ser usados para produzir resultados XML:

Executor de teste	Relatores para produzir relatórios XML
mocha	mocha-junit-reporter cypress-multi-reporters
jasmine	jasmine-reporters
jest	jest-junit jest-junit-reporter
karma	karma-junit-reporter
Yasmin	tap-xunit

O exemplo a seguir usa o mocha-junit-reporter e invoca mocha test diretamente usando um script. Esse script produz a saída XML do JUnit no local padrão de ./test-results.xml.

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

Se você definiu um script test no arquivo package.json do projeto, poderá invocá-lo usando npm test.

- script: npm test

Publicar resultados de teste

Para publicar os resultados, use a tarefa Publicar Resultados de Teste.

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

Publicar resultados de cobertura de código

Se os scripts de teste executarem uma ferramenta de cobertura de código, como Istambul, adicione a tarefa Publicar Resultados de Cobertura de Código. Ao fazer isso, você pode localizar as métricas de cobertura no resumo do build e baixar os relatórios HTML para análise posterior. A tarefa espera a saída de relatórios de Cobertura ou JaCoCo. Portanto, verifique se a ferramenta de cobertura de código é executada com as opções necessárias para gerar a saída certa. Por exemplo, --report cobertura.

O exemplo a seguir usa nyc, a interface de linha de comando de Istambul, juntamente com o comando 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'

Testar navegador de ponta a ponta

Execute testes nos navegadores sem periféricos como parte do pipeline com ferramentas como Protractor ou Karma. Em seguida, publique os resultados do build no Azure DevOps com as seguintes etapas:

1. Instale um driver de teste de navegador sem periféricos, como o Chrome ou Firefox sem periféricos, ou uma ferramenta de simulação de navegador, como o PhantomJS, no agente de build.
2. Configure sua estrutura de teste para usar a opção de driver/navegador sem periféricos de sua escolha de acordo com a documentação da ferramenta.
3. Configure sua estrutura de teste (geralmente com um plug-in ou configuração de relator) para gerar resultados de teste formatados em JUnit.
4. Configure uma tarefa de script para executar todos os comandos da CLI necessários para iniciar as instâncias do navegador sem periféricos.
5. Execute os testes de ponta a ponta nas fases do pipeline, juntamente com os testes de unidade.
6. Publique os resultados usando a mesma tarefa Publicar Resultados de Teste junto com seus testes de unidade.

Empacotar aplicativos Web

Empacotar aplicativos para agrupar todos os módulos de aplicativo com saídas intermediárias e dependências em ativos estáticos prontos para implantação. Adicione uma fase de pipeline após a compilação e os testes para executar uma ferramenta como webpack ou ng build usando a CLI do Angular.

O primeiro exemplo chama webpack. Para que isso funcione, verifique se webpack está configurado como uma dependência de desenvolvimento no arquivo de projeto package.json. Ele executa o webpack com a configuração padrão, a menos que você tenha um arquivo webpack.config.js na pasta raiz do projeto.

- script: webpack

O próximo exemplo usa a tarefa npm para chamar npm run build, para chamar o objeto de script build definido no package.json do projeto. O uso de objetos de script no seu projeto move a lógica do build para o código-fonte e para fora do pipeline.

- script: npm run build

Implementar estruturas JavaScript

Angular

Para aplicativos do Angular, você pode incluir comandos específicos do Angular, como ng test, ng build e ng e2e. Para usar os comandos da CLI do Angular no seu pipeline, instale o pacote angular/cli npm no agente de build.

Observação

Nos agentes do Linux hospedados pela Microsoft, introduza o comando com sudo, como sudo npm install -g.

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

Para testes no pipeline que exigem a execução de um navegador, como o comando ng test no aplicativo inicial, que executa o Karma, use um navegador sem periféricos, em vez de um navegador padrão. No aplicativo inicial do Angular:

1. Altere a entrada browsers no arquivo de projeto karma.conf.js de browsers: ['Chrome'] para browsers: ['ChromeHeadless'].

2. Altere a entrada singleRun no arquivo de projeto karma.conf.js de um valor de false para true. Essa alteração ajuda a garantir que o processo do Karma seja interrompido após a execução.

React e Vue

Todas as dependências dos aplicativos React e Vue são capturadas no arquivo package.json. O arquivo azure-pipelines.yml contém o script do Node.js padrão:

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

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

Os arquivos de build estão em uma nova pasta dist (para Vue) ou build (para React). Esse snippet cria um artefato, www, que está pronto para lançamento. Ele usa as tarefas Instalador do Node, Copiar Arquivos e Publicar Artefatos 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

Para lançar, aponte sua tarefa de lançamento para o artefato dist ou build e use a tarefa Implantar Aplicativo Web do Azure.

Webpack

Você pode usar um arquivo de configuração de webpack para especificar um compilador, como Babel ou TypeScript, para transcompilar JSX ou TypeScript para JavaScript sem formatação e agrupar seu aplicativo.

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

Compilar executores de tarefas

É comum usar Gulp ou Grunt como executor de tarefas para criar e testar um aplicativo JavaScript.

Gulp

O Gulp vem pré-instalado nos agentes hospedados pela Microsoft. Execute o comando gulp no arquivo YAML:

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

Se as etapas no arquivo gulpfile.js exigirem autenticação com um registro npm:

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

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

Adicione a tarefa Publicar Resultados de Teste para publicar os resultados de teste JUnit ou xUnit no servidor.

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

Adicione a tarefa Publicar Resultados de Cobertura de Código para publicar os resultados de cobertura de código no servidor. Você pode localizar as métricas de cobertura no resumo do build e baixar os relatórios HTML para análise posterior.

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

Grunt

O Grunt vem pré-instalado nos agentes hospedados pela Microsoft. Para executar o comando do Grunt no arquivo YAML:

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

Se as etapas no arquivo Gruntfile.js exigirem autenticação com um registro npm:

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

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

Empacotar e entregar seu código

Depois de criar e testar seu aplicativo, você pode carregar a saída da compilação no Azure Pipelines, criar e publicar um pacote npm ou Maven ou empacotar a saída de build em um arquivo .zip para ser implantado em um aplicativo Web.

Publicar arquivos no Azure Pipelines

Para carregar todo o diretório de trabalho de arquivos, use a tarefa Publicar Artefatos de Build e adicione o seguinte ao arquivo azure-pipelines.yml.

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

Para carregar um subconjunto de arquivos, primeiro copie os arquivos necessários do diretório de trabalho em um diretório de preparo com a tarefa Copiar Arquivos e use a tarefa Publicar Artefatos de Build.

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

- task: PublishBuildArtifacts@1

Publicar um módulo em um registro npm

Se a saída do projeto for um módulo npm para ser usado por outros projetos e não por um aplicativo Web, use a tarefa npm para publicar o módulo em um registro local ou no registro npm público. Forneça uma combinação de nome/versão exclusiva, sempre que você publicar.

Exemplos

O primeiro exemplo pressupõe que você gerencia as informações de versão (por exemplo, usando uma versão do npm) com alterações no arquivo package.json no controle de versão. O exemplo a seguir usa a tarefa script para publicar no registro público.

- script: npm publish

O próximo exemplo é publicado em um registro personalizado definido no arquivo .npmrc do repositório. Configure uma conexão de serviço do npm para injetar credenciais de autenticação na conexão, à medida que o build é executado.

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

O exemplo final publica o módulo em um feed de gerenciamento de pacotes do Azure DevOps Services.

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

Para obter mais informações sobre controle de versão e publicação de pacotes npm, confira Publicar pacotes npm e Como posso ver meus pacotes npm como parte do processo de build?.

Implantar um aplicativo Web

Para criar um arquivo .zip pronto para publicação em um aplicativo Web, use a tarefa Arquivos Mortos:

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

Para publicar esse arquivo em um aplicativo Web, confira Implantação de aplicativo Web do Azure.

Compilar e enviar imagem por push para o registro de contêiner

Depois que o código-fonte for compilado com êxito e os testes de unidade estiverem em vigor e bem-sucedidos, você também poderá criar uma imagem e efetuar push dela para um registro de contêiner.

Solucionar problemas

Se você puder criar seu projeto no seu computador de desenvolvimento, mas estiver tendo problemas para compilá-lo no Azure Pipelines, explore as seguintes possíveis causas e ações corretivas:

• Verifique se as versões do Node.js e do executor de tarefas no computador de desenvolvimento correspondem às do agente. Você pode incluir scripts de linha de comando como o node --version no pipeline, para verificar o que está instalado no agente. Use o Instalador de Ferramentas do Node (conforme explicado nestas diretrizes) para implantar a mesma versão no agente ou execute os comandos npm install para atualizar as ferramentas para as versões desejadas.

• Se os builds falharem intermitentemente durante a restauração de pacotes, o registro npm terá problemas ou haverá problemas de rede entre o data center do Azure e o registro. Não podemos controlar esses fatores. Explore se o uso do Azure Artifacts com um registro npm como fonte upstream melhora a confiabilidade dos seus builds.

• Se você estiver usando nvm para gerenciar diferentes versões do Node.js, alterne para a tarefa Instalador de Ferramentas do Node. (nvm é instalado por motivos históricos na imagem do macOS.) nvm gerencia várias versões do Node.js adicionando aliases de shell e alterando PATH, que não interage corretamente com a maneira como o Azure Pipelines executa cada tarefa em um novo processo.

  A tarefa Instalador de Ferramentas do Node manipula esse modelo corretamente. No entanto, se o trabalho exigir o uso de nvm, você poderá adicionar o seguinte script ao início de cada 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"
  

  Em seguida, node e outras ferramentas de linha de comando funcionarão para o restante do trabalho de pipeline. Em cada etapa em que você usar o comando nvm, inicie o script com o seguinte código:

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

Perguntas frequentes

P: onde posso saber mais sobre o Azure Artifacts e o serviço de Gerenciamento de Pacotes?

R: Gerenciamento de Pacotes no Azure Artifacts

P: onde posso saber mais sobre o Flask?

R: Tarefas de build, versão e teste

P: como corrigir uma falha de pipeline com a mensagem "ERRO FATAL: falha na alocação CALL_AND_RETRY_LAST – heap do JavaScript sem memória"?

R: esse tipo de falha ocorre quando o pacote de Node.js excede o limite de uso de memória. Para resolve o problema, adicione uma variável como NODE_OPTIONS e atribua a ela um valor de --max_old_space_size=16384.

P: como posso controlar a versão dos meus pacotes npm como parte do processo de build?

R: uma opção é usar uma combinação de controle de versão e versão do npm. No final de uma execução de pipeline, você pode atualizar seu repositório com a nova versão. Neste YAML, há um repositório GitHub e o pacote é implantado no npmjs. O build falhará se houver uma incompatibilidade entre a versão do pacote no npmjs e o arquivo 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