Personalizar JavaScript para Pipelines do Azure

Você pode usar o Azure Pipelines para criar seus aplicativos JavaScript sem precisar configurar nenhuma infraestrutura própria. As ferramentas que você normalmente usa para criar, testar e executar 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, consulte Agentes hospedados pela Microsoft. Para instalar uma versão específica dessas ferramentas em agentes hospedados pela Microsoft, adicione a tarefa Node Tool Installer ao início do processo. Você também pode usar um agente auto-hospedado .

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

Use 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 do instalador da ferramenta Node. Adicione o seguinte trecho ao seu azure-pipelines.yml arquivo.

Nota

Os agentes hospedados são atualizados regularmente e a configuração dessa tarefa resulta em gastar tempo significativo atualizando para uma versão secundária mais recente toda vez que o pipeline é executado. Use esta tarefa somente quando precisar de uma versão específica do nó em 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 npm i -g npm@version-number comando em seu processo de compilação.

Usar várias versões de nós

Você pode criar e testar seu aplicativo em várias versões do Node com a tarefa do instalador da ferramenta 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 em seu agente de compilação

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

Use um script ou a tarefa npm.

Use um script para instalar com package.json

- script: npm install --only=dev

Use a tarefa npm para instalar com package.json

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

Execute ferramentas instaladas dessa maneira usando o executor de pacote npm npx , que deteta ferramentas instaladas dessa maneira em sua 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 (através npm install -gde).

- script: npx mocha

Para instalar ferramentas de que seu projeto precisa, mas que não estão definidas como dependências de desenvolvimento no package.json, ligue npm install -g de um estágio de script em seu pipeline.

O exemplo a seguir instala a versão mais recente da CLI Angular usando npmo . O restante do pipeline pode usar a ng ferramenta de outros script estágios.

Nota

Em agentes Linux hospedados pela Microsoft, prefacie o comando com sudo, como sudo npm install -g.

- script: npm install -g @angular/cli

Gorjeta

Essas tarefas são executadas sempre que o pipeline é executado, portanto, esteja atento ao impacto que a instalação de ferramentas tem nos tempos de compilação. Considere configurar agentes auto-hospedados com a versão das ferramentas necessárias se a sobrecarga se tornar um sério impacto no desempenho da compilação.

Gerir dependências

Em sua compilação, use o Yarn ou o Azure Artifacts para baixar pacotes do registro npm público. Este registro é um tipo de registro npm privado que você especifica no .npmrc arquivo.

Usar npm

Você pode usar o npm das seguintes maneiras para baixar pacotes para sua compilação:

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

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

Para instalar pacotes npm com um script em seu pipeline, adicione o seguinte trecho ao azure-pipelines.yml.

- script: npm install

Para usar um registro privado especificado em seu .npmrc arquivo, adicione o seguinte trecho ao azure-pipelines.yml.

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

Para passar credenciais do Registro para comandos npm por meio de executores de tarefas como Gulp, adicione a seguinte tarefa antes azure-pipelines.yml de chamar o executor de tarefas.

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

Se suas compilações falharem ocasionalmente devido a problemas de conexão ao restaurar pacotes do registro npm, você poderá usar os Artefatos do Azure com fontes upstream e armazenar os pacotes em cache. As credenciais do pipeline são usadas automaticamente quando você se conecta aos Artefatos do Azure. Essas credenciais geralmente são derivadas da conta do Serviço de Compilação da Coleção de Projetos.

Se você estiver usando agentes hospedados pela Microsoft, receberá uma nova máquina toda vez que executar uma compilação - o que significa restaurar as dependências sempre, o que pode levar uma quantidade significativa de tempo. Para atenuar, você pode usar os Artefatos do Azure ou um agente auto-hospedado - então você obtém o benefício de usar o cache do pacote.

Usar fios

Use um estágio de script para invocar o Yarn para restaurar dependências. O Yarn é 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 seu código-fonte em versões utilizáveis pelo tempo de execução .js nó ou em navegadores da web.

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

- script: npm run compile

Você pode chamar compiladores diretamente do pipeline usando a tarefa de script. Esses comandos são executados a partir da 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 para que eles produzam resultados formatados no formato XML JUnit. Em seguida, você pode publicar os resultados usando a tarefa interna de publicação de resultados de teste .

Se sua estrutura de teste não suportar a saída JUnit, adicione suporte por meio de um módulo de relatório de parceiro, como mocha-junit-reporter. Você pode atualizar seu script de teste para usar o repórter JUnit ou, se o repórter oferecer suporte a opções de linha de comando, passar essas opções para a definição de tarefa.

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

Corredor de teste	Repórteres para produzir relatórios XML
Mocha	Mocha-Junit-Repórter cipreste-multi-repórteres
Jasmim	Jasmine-Repórteres
brincadeira	Jest-Junit jest-junit-repórter
carma	karma-junit-repórter
Ava	torneira-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 JUnit no local padrão do ./test-results.xml.

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

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

- script: npm test

Publicar resultados de testes

Para publicar os resultados, use a tarefa Publicar resultados do 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 encontrar métricas de cobertura no resumo da compilação e baixar relatórios HTML para análise adicional. A tarefa espera saída de relatório Cobertura ou JaCoCo, portanto, certifique-se de que sua ferramenta de cobertura de código seja 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 npm test Istambul, juntamente com mocha-junit-reporter e invoca o comando.

- 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'

Teste o navegador de ponta a ponta

Execute testes em navegadores sem cabeça como parte do seu pipeline com ferramentas como Protractor ou Karma. Em seguida, publique os resultados da compilação no Azure DevOps com as seguintes etapas:

1. Instale um driver de teste de navegador sem cabeça, como Chrome ou Firefox sem cabeça, ou uma ferramenta de simulação de navegador, como PhantomJS, no agente de compilação.
2. Configure sua estrutura de teste para usar a opção de navegador/driver sem cabeça 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 repórter) para produzir resultados de teste formatados em JUnit.
4. Configure uma tarefa de script para executar quaisquer comandos da CLI necessários para iniciar as instâncias do navegador sem cabeça.
5. Execute os testes de ponta a ponta nos estágios de pipeline junto com seus testes de unidade.
6. Publique os resultados usando a mesma tarefa Publicar resultados do teste ao lado dos testes de unidade.

Empacotar aplicativos Web

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

O primeiro exemplo chama webpack. Para ter esse trabalho, certifique-se de que webpack está configurado como uma dependência de desenvolvimento em seu arquivo de projeto package.json. Isso é executado webpack com a configuração padrão, a menos que você tenha um webpack.config.js arquivo na pasta raiz do seu projeto.

- script: webpack

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

- script: npm run build

Implementar estruturas JavaScript

Angular

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

Nota

Em agentes Linux hospedados pela Microsoft, prefacie o comando com sudo, como sudo npm install -g.

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

Para testes em seu 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 cabeça em vez de um navegador padrão. No aplicativo Angular starter:

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

2. Altere a singleRun entrada em seu arquivo de projeto karma.conf.js de um valor de false para true. Essa alteração ajuda a garantir que o processo de Karma pare depois de ser executado.

Reagir e Vue

Todas as dependências para seus aplicativos React e Vue são capturadas em seu arquivo package.json . Seu arquivo azure-pipelines.yml contém o script Node.js padrão:

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

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

Os arquivos de compilação estão em uma nova pasta, dist (para Vue) ou build (para React). Este trecho constrói um artefato - - www que está pronto para lançamento. Ele usa as tarefas Node Installer, Copy Files e Publish Build Artifacts .

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 liberar, aponte sua tarefa de liberação para o dist artefato ou build e use a tarefa Implantar do Aplicativo Web do Azure.

Pacote Web

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

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

Criar executores de tarefas

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

Gulp

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

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

Se as etapas em seu 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 do teste para publicar os resultados do 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 resultados de cobertura de código no servidor. Você pode encontrar métricas de cobertura no resumo da compilação e pode baixar relatórios HTML para análise adicional.

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

Grunt

O Grunt é pré-instalado em agentes hospedados pela Microsoft. Para executar o comando grunt no arquivo YAML:

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

Se as etapas em seu Gruntfile.js arquivo 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

Embale e entregue o seu código

Depois de criar e testar seu aplicativo, você pode carregar a saída de compilação no Azure Pipelines, criar e publicar um pacote npm ou Maven ou empacotar a saída de compilação em um arquivo .zip para implantação 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 compilação e adicione o seguinte ao seu azure-pipelines.yml arquivo.

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

Para carregar um subconjunto de arquivos, primeiro copie os arquivos necessários do diretório de trabalho para um diretório de preparo com a tarefa Copiar arquivos e, em seguida, use a tarefa Publicar artefatos de compilação.

- 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 seu projeto for um módulo para uso por outros projetos e não um aplicativo Web, use a tarefa npm para publicar o módulo em um npm registro local ou no registro npm público. Forneça uma combinação exclusiva de nome/versão sempre que publicar.

Exemplos

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

- script: npm publish

O próximo exemplo publica em um registro personalizado definido no arquivo do .npmrc seu repo. Configure uma conexão de serviço npm para injetar credenciais de autenticação na conexão à medida que a compilação é executada.

- 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 dos Serviços de DevOps do Azure.

- 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, consulte Publicar pacotes npm e Como posso fazer a versão dos meus pacotes npm como parte do processo de compilação?.

Implementar uma aplicação Web

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

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

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

Criar e enviar imagem para o registro do contêiner

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

Resolver problemas

Se você pode criar seu projeto em sua máquina de desenvolvimento, mas está tendo problemas para criá-lo no Azure Pipelines, explore as seguintes causas potenciais e ações corretivas:

• Verifique se as versões do Node.js e do executor de tarefas em sua máquina de desenvolvimento correspondem às do agente. Você pode incluir scripts de linha de comando, como node --version em seu pipeline, para verificar o que está instalado no agente. Use o Node Tool Installer (conforme explicado nesta orientação) para implantar a mesma versão no agente ou execute npm install comandos para atualizar as ferramentas para as versões desejadas.

• Se suas compilações falharem intermitentemente enquanto você restaura pacotes, o registro npm tem problemas ou há problemas de rede entre o data center do Azure e o registro. Não podemos controlar esses fatores. Explore se o uso de Artefatos do Azure com um registro npm como uma fonte upstream melhora a confiabilidade de suas compilações.

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

  A tarefa Node Tool Installer lida com esse modelo corretamente. No entanto, se o seu trabalho exigir o uso do nvm, você pode 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 funcionam para o restante do trabalho de pipeline. Em cada etapa em que você usa o comando, inicie o script com o nvm seguinte código:

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

FAQ

P: Onde posso saber mais sobre os Artefatos do Azure e o serviço de Gerenciamento de Pacotes?

R: Gerenciamento de Pacotes em Artefatos do Azure

P: Onde posso saber mais sobre as tarefas?

R: Tarefas de compilação, liberação e teste

P: Como faço para corrigir uma falha de pipeline com a mensagem 'ERRO FATAL: CALL_AND_RETRY_LAST Falha na alocação - pilha JavaScript sem memória'?

R: Este tipo de falha acontece quando o pacote Node.js excede o limite de utilização de memória. Para resolver o problema, adicione uma variável como NODE_OPTIONS e atribua-lhe um valor de --max_old_space_size=16384.

P: Como posso fazer a versão dos meus pacotes npm como parte do processo de compilação?

R: Uma opção é usar uma combinação de controle de versão e versão 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. Sua compilação 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