Настройка JavaScript для Azure Pipelines

Azure Pipelines можно использовать для создания приложений JavaScript без необходимости настраивать собственную инфраструктуру. Средства, которые обычно используются для сборки, тестирования и запуска приложений JavaScript, таких как npm, Node, Yarn и Gulp, предварительно установлены на размещенных майкрософт агентах в Azure Pipelines.

Сведения о версиях Node.js и npm, предварительно установленных, см. в агентах, размещенных корпорацией Майкрософт. Чтобы установить определенную версию этих средств на размещенных корпорацией Майкрософт агентах, добавьте задачу установщика средств node в начало процесса. Вы также можете использовать локальный агент.

Чтобы создать первый конвейер с помощью JavaScript, ознакомьтесь с кратким руководством по JavaScript.

Использование определенной версии Node.js

Если вам нужна версия Node.js и npm, которая еще не установлена в агенте, размещенном корпорацией Майкрософт, используйте задачу установщика средства node. Добавьте следующий фрагмент кода в azure-pipelines.yml файл.

Примечание.

Размещенные агенты регулярно обновляются, и настройка этой задачи приводит к значительному обновлению времени до более новой дополнительной версии при каждом запуске конвейера. Используйте эту задачу только в том случае, если в конвейере требуется определенная версия узла.

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

Чтобы обновить только средство npm, выполните npm i -g npm@version-number команду в процессе сборки.

Использование нескольких версий узлов

Вы можете создавать и тестировать приложение на нескольких версиях Node с помощью задачи установщика средства 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

Установка средств в агенте сборки

Если у вас есть средства, которые являются зависимостями разработки в проекте package.json или package-lock.json файле, установите средства и зависимости через npm. Точную версию средств, определенных в проекте, изолированную от других версий, существующих в агенте сборки.

Используйте скрипт или задачу npm.

Использование скрипта для установки с помощью package.json

- script: npm install --only=dev

Использование задачи npm для установки с помощью package.json

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

Запустите средства, установленные таким образом, с помощью средства выполнения пакета npm npx , который обнаруживает средства, установленные таким образом в разрешении пути. В следующем примере вызывается mocha средство выполнения теста, но ищет версию, установленную в качестве зависимости разработки, прежде чем использовать глобально установленную (через npm install -g) версию.

- script: npx mocha

Чтобы установить средства, необходимые для проекта, но не заданные в качестве зависимостей разработки package.json, вызовите npm install -g из этапа скрипта в конвейере.

В следующем примере устанавливается последняя версия Angular CLI с помощью npm. Остальная часть конвейера может затем использовать ng средство с других script этапов.

Примечание.

В агентах Linux, размещенных в Корпорации Майкрософт, предусловит команду следующим sudoобразом sudo npm install -g.

- script: npm install -g @angular/cli

Совет

Эти задачи выполняются каждый раз при запуске конвейера, поэтому учитывайте влияние установки средств на время сборки. Рассмотрите возможность настройки локальных агентов с версией необходимых средств, если затраты становятся серьезным воздействием на производительность сборки.

Управление зависимостями

В сборке используйте Yarn или Azure Artifacts для скачивания пакетов из общедоступного реестра npm. Этот реестр представляет собой тип частного реестра npm, который указывается в .npmrc файле.

Использование npm

Npm можно использовать следующим образом, чтобы скачать пакеты для сборки:

• Напрямую запустите npm install конвейер, так как это самый простой способ скачивания пакетов из реестра без проверки подлинности. Если сборка не требует зависимостей разработки от агента, можно ускорить сборку с --only=prod помощью параметра npm install.
• Используйте задачу npm. Эта задача полезна при использовании проверенного реестра.
• Используйте задачу проверки подлинности npm. Эта задача полезна при выполнении из средств выполнения npm install задач — Gulp, Grunt или Maven.

Если вы хотите указать реестр npm, поместите URL-адреса в .npmrc файл в репозиторий. Если веб-канал проходит проверку подлинности, создайте подключение службы npm на вкладке "Службы " в параметрах проекта для управления учетными данными.

Чтобы установить пакеты npm со скриптом в конвейере, добавьте следующий фрагмент azure-pipelines.ymlкода в .

- script: npm install

Чтобы использовать частный реестр, указанный в .npmrc файле, добавьте следующий фрагмент azure-pipelines.ymlкода в .

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

Чтобы передать учетные данные реестра в команды npm с помощью средств выполнения задач, таких как Gulp, добавьте следующую задачу перед azure-pipelines.yml вызовом средства выполнения задач.

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

Если сборки иногда завершаются сбоем из-за проблем с подключением при восстановлении пакетов из реестра npm, можно использовать Azure Artifacts с вышестоящими источниками и кэшировать пакеты. Учетные данные конвейера автоматически используются при подключении к Azure Artifacts. Эти учетные данные обычно являются производными от учетной записи службы сборки коллекции проектов.

Если вы используете агенты, размещенные Корпорацией Майкрософт, вы получаете новый компьютер при каждом запуске сборки, что означает восстановление зависимостей каждый раз, что может занять значительное время. Чтобы устранить проблему, можно использовать azure Artifacts или локальный агент, а затем воспользоваться преимуществами кэша пакетов.

Использование Yarn

Используйте этап скрипта для вызова Yarn для восстановления зависимостей. Yarn предварительно установлен на некоторых размещенных корпорацией Майкрософт агентах. Его можно установить и настроить на локальных агентах, таких как любой другой инструмент.

- script: yarn install

Запуск компиляторов JavaScript

Используйте компиляторы, такие как Babel и компилятор TypeScripttsc, чтобы преобразовать исходный код в версии, доступные для использования средой выполнения Node.js или в веб-браузерах.

Если у вас есть объект скрипта, настроенный в файле проектаpackage.json, который запускает компилятор, вызовите его в конвейере с помощью задачи скрипта.

- script: npm run compile

Компиляторы можно вызывать непосредственно из конвейера с помощью задачи скрипта. Эти команды выполняются из корня клонированного репозитория исходного кода.

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

Выполнение модульных тестов

Настройте конвейеры для выполнения тестов JavaScript, чтобы они отображали результаты в формате JUnit XML. Затем можно опубликовать результаты с помощью встроенной задачи публикации результатов теста.

Если тестовая платформа не поддерживает выходные данные JUnit, добавьте поддержку с помощью модуля отчетов партнера, например mocha-junit-reporter. Вы можете обновить тестовый скрипт для использования репортера JUnit или, если репортер поддерживает параметры командной строки, передайте эти параметры в определение задачи.

В следующей таблице перечислены наиболее часто используемые тестовые средства выполнения и репортеры, которые можно использовать для получения результатов XML:

Средство выполнения теста	Репортеры для создания XML-отчетов
мокко	mocha-junit-репортер cypress-multi-репортеры
жасмин	jasmine-reporters
шутка	jest-junit jest-junit-репортер
карма	карма-хунит-репортер
Ava	tap-xunit

В следующем примере используется mocha-junit-reporter и вызывается mocha test непосредственно с помощью скрипта. Этот скрипт создает выходные данные XML JUnit в расположении ./test-results.xmlпо умолчанию.

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

Если вы определили test скрипт в файле package.json проекта, его можно вызвать с помощью npm test.

- script: npm test

Опубликовать результаты теста

Чтобы опубликовать результаты, используйте задачу "Опубликовать результаты теста ".

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

Публикация результатов покрытия кода

Если тестовые скрипты запускают средство покрытия кода, например Стамбул, добавьте задачу "Результаты покрытия кода публикации". При этом можно найти метрики покрытия в сводке сборки и скачать HTML-отчеты для дальнейшего анализа. Задача ожидает вывода отчетов Cobertura или JaCoCo, поэтому убедитесь, что средство покрытия кода выполняется с необходимыми параметрами для создания правильных выходных данных. Например, --report cobertura.

В следующем примере используется nyc, интерфейс командной строки Стамбула, а также mocha-junit-reporter и вызывает 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'

Тестирование сквозного браузера

Запустите тесты в браузерах без головы в рамках конвейера с такими инструментами, как Protractor или Карма. Затем опубликуйте результаты сборки в Azure DevOps, выполнив следующие действия:

1. Установите драйвер тестирования браузера без головы, например без головы Chrome или Firefox, или средство для макетирования браузера, например PhantomJS, на агенте сборки.
2. Настройте тестовую платформу для использования выбранного варианта браузера или драйвера без головы в соответствии с документацией средства.
3. Настройте платформу тестирования (обычно с подключаемым модулем или конфигурацией репортера) для вывода результатов теста в формате JUnit.
4. Настройте задачу скрипта для выполнения любых команд CLI, необходимых для запуска экземпляров браузера без головы.
5. Запустите сквозные тесты на этапах конвейера вместе с модульными тестами.
6. Опубликуйте результаты с помощью той же задачи "Опубликовать результаты теста " вместе с модульными тестами.

Пакеты веб-приложений

Пакеты приложений для упаковки всех модулей приложений с промежуточными выходными данными и зависимостями в статические ресурсы, готовые к развертыванию. Добавьте этап конвейера после компиляции и тестов для запуска средства, например webpack или ng build с помощью Angular CLI.

Первый пример вызовов webpack. Чтобы обеспечить эту работу, убедитесь, что webpack она настроена в качестве зависимости разработки в файле проекта package.json. Это выполняется webpack с конфигурацией по умолчанию, если у вас webpack.config.js нет файла в корневой папке проекта.

- script: webpack

В следующем примере задача npm используется для вызова npm run build объекта скриптаbuild, определенного в проекте package.json. Использование объектов скриптов в проекте перемещает логику сборки в исходный код и из конвейера.

- script: npm run build

Реализация платформ JavaScript

Angular

Для приложений Angular можно включить такие команды, как ng test, ng build и ng e2e. Чтобы использовать команды Angular CLI в конвейере, установите пакет angular/cli npm в агенте сборки.

Примечание.

В агентах Linux, размещенных в Корпорации Майкрософт, предусловит команду следующим sudoобразом sudo npm install -g.

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

Для тестов в конвейере, для выполнения которых требуется запустить браузер, например команду ng test в начальном приложении, которое запускает Карму, используйте головной браузер вместо стандартного браузера. В начальном приложении Angular:

1. Измените browsers запись в файле проекта karma.conf.js на browsers: ['Chrome'] browsers: ['ChromeHeadless'].

2. Измените singleRun запись в файле проекта karma.conf.js на значение false true. Это изменение помогает убедиться, что процесс Кармы останавливается после его выполнения.

React и Vue

Все зависимости для приложений React и Vue записываются в файл package.json . Файл azure-pipelines.yml содержит стандартный скрипт Node.js:

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

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

Файлы сборки находятся в новой папке dist (для Vue) или build (для React). Этот фрагмент создает артефакт - www который готов к выпуску. В нем используются задачи установщика узлов, копирования файлови задач публикации артефактов сборки.

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

Чтобы освободить, укажите задачу выпуска в dist или build артефакт и используйте задачу развертывания веб-приложений Azure.

веб-пакета

Файл конфигурации webpack можно использовать для указания компилятора, например Babel или TypeScript, для транспилирования JSX или TypeScript на обычный JavaScript и для упаковки приложения.

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

Запуски задач сборки

Обычно для создания и тестирования приложения JavaScript используется Gulp или Grunt в качестве средства выполнения задач.

Gulp

Gulp получает предварительно установленное в агентах, размещенных корпорацией Майкрософт. gulp Выполните команду в ФАЙЛЕ YAML:

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

Если действия в файле gulpfile.js требуют проверки подлинности с помощью реестра npm:

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

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

Добавьте задачу "Опубликовать результаты теста", чтобы опубликовать результаты теста JUnit или xUnit на сервере.

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

Добавьте задачу "Публикация результатов покрытия кода", чтобы опубликовать результаты покрытия кода на сервере. Метрики покрытия можно найти в сводке сборки и скачать отчеты HTML для дальнейшего анализа.

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

Grunt

Grunt получает предварительно установленное в агентах, размещенных корпорацией Майкрософт. Чтобы выполнить команду grunt в ФАЙЛЕ YAML:

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

Если действия в Gruntfile.js файле требуют проверки подлинности с помощью реестра npm:

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

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

Упаковка и доставка кода

После создания и тестирования приложения можно отправить выходные данные сборки в Azure Pipelines, создать и опубликовать пакет npm или Maven или упаковать выходные данные сборки в файл .zip для развертывания в веб-приложение.

Публикация файлов в Azure Pipelines

Чтобы отправить весь рабочий каталог файлов, используйте задачу "Опубликовать артефакты сборки" и добавьте следующий azure-pipelines.yml файл.

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

Чтобы отправить подмножество файлов, сначала скопируйте необходимые файлы из рабочего каталога в промежуточный каталог с задачей "Копировать файлы ", а затем используйте задачу "Публикация артефактов сборки".

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

- task: PublishBuildArtifacts@1

Публикация модуля в реестре npm

Если выходные данные проекта — это npm модуль для использования другими проектами, а не веб-приложением, используйте задачу npm для публикации модуля в локальном реестре или общедоступном реестре npm. При каждой публикации укажите уникальное сочетание имен и версий.

Примеры

В первом примере предполагается, что вы управляете сведениями о версиях (например, через версию npm) путем изменения package.json файла в элементе управления версиями. В следующем примере задача скрипта используется для публикации в общедоступном реестре.

- script: npm publish

Следующий пример публикуется в пользовательском реестре, определенном в файле репозитория .npmrc . Настройте подключение службы npm для внедрения учетных данных проверки подлинности в подключение при выполнении сборки.

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

Последний пример публикует модуль в веб-канале управления пакетами Azure DevOps Services.

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

Дополнительные сведения об использовании версий и публикации пакетов npm см. в статье "Публикация пакетов npm" и "Как можно использовать версию пакетов npm в процессе сборки?".

Развертывание веб-приложения

Чтобы создать архив файла .zip, готовый к публикации в веб-приложении, используйте задачу "Архивные файлы ":

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

Сведения о публикации этого архива в веб-приложении см. в статье о развертывании веб-приложений Azure.

Сборка и отправка образа в реестр контейнеров

После успешной сборки исходного кода и выполнения модульных тестов можно также создать образ и отправить его в реестр контейнеров.

Устранение неполадок

Если вы можете создать проект на компьютере разработки, но у вас возникли проблемы с его сборкой в Azure Pipelines, изучите следующие потенциальные причины и корректирующие действия:

• Убедитесь, что версии Node.js и средство выполнения задач на компьютере разработки соответствуют версиям агента. Вы можете включить скрипты командной строки, такие как node --version в конвейере, чтобы проверить, что установлено в агенте. Используйте установщик средств node (как описано в этом руководстве), чтобы развернуть ту же версию агента или выполнить npm install команды, чтобы обновить средства до нужных версий.

• Если сборки завершаются сбоем во время восстановления пакетов, реестр npm имеет проблемы или возникают проблемы с сетью между центром обработки данных Azure и реестром. Мы не можем контролировать эти факторы. Узнайте, повышает ли использование артефактов Azure с реестром npm в качестве вышестоящего источника, что повышает надежность сборок.

• Если вы используете nvm для управления различными версиями Node.js, попробуйте переключиться на задачу установщика средств узлов. (nvm устанавливается по историческим причинам на образе macOS.) nvm управляет несколькими версиями Node.js путем добавления псевдонимов оболочки и изменения PATH, которые плохо взаимодействуют с тем, как Azure Pipelines выполняет каждую задачу в новом процессе.

  Задача установщика средств узла правильно обрабатывает эту модель. Однако если для работы требуется использование nvm, можно добавить следующий скрипт в начало каждого конвейера:

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

  node Затем другие средства командной строки работают для остальных заданий конвейера. На каждом шаге nvm , в котором используется команда, запустите скрипт со следующим кодом:

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

Вопросы и ответы

Вопрос. Где можно узнать больше о артефактах Azure и службе управления пакетами?

Ответ. Управление пакетами в артефактах Azure

Вопрос. Где можно узнать больше о задачах?

Ответ. Сборка, выпуск и тестовые задачи

Вопрос: Разделы справки исправить сбой конвейера с сообщением "НЕУСТРАНИМАЯ ОШИБКА: сбой выделения CALL_AND_RETRY_LAST - куча JavaScript из памяти"?

Ответ. Этот тип сбоя происходит, когда пакет Node.js превышает ограничение использования памяти. Чтобы устранить проблему, добавьте переменную, как NODE_OPTIONS и назначьте ее значение --max_old_space_size=16384.

Вопрос. Как можно использовать версию пакетов npm в процессе сборки?

Ответ. Одним из вариантов является использование сочетания элементов управления версиями и npm. В конце выполнения конвейера можно обновить репозиторий с новой версией. В этом YAML есть репозиторий GitHub и пакет развертывается в npmjs. Сборка завершается ошибкой, если между версией пакета в npmjs и файле 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