Создание и тестирование для Node.js

Введение

В этом руководстве показано, как получить рабочий процесс непрерывной интеграции (CI), который создает и тестирует код Node.js. Если тесты CI проходят правильно, может потребоваться развернуть код или опубликовать пакет.

Предварительные требования

Рекомендуется иметь базовое представление о Node.js, YAML, параметрах конфигурации рабочих процессов, а также о том, как создавать файл рабочего процесса. Дополнительные сведения можно найти в разделе

• "Изучение GitHub Actions"
• Начало работы с Node.js

Использование начального рабочего процесса Node.js

GitHub предоставляет начальный рабочий процесс Node.js, который будет работать для большинства проектов Node.js. В этом руководстве приведены примеры npm и Yarn, которые можно использовать для настройки начального рабочего процесса. Дополнительные сведения см. в разделе Начальный рабочий процесс Node.js.

Чтобы быстро приступить к работе, добавьте начальный рабочий процесс в каталог .github/workflows своего репозитория. В показанном ниже рабочем процессе предполагается, что ветвью по умолчанию для вашего репозитория является main.

name: Node.js CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:

    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [14.x, 16.x, 18.x, 20.x]

    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

Выполнение заданий в другой операционной системе

Начальный рабочий процесс настраивает задания для запуска в Linux с помощью размещенных в GitHub средств выполнения ubuntu-latest. Можно изменить ключ runs-on для выполнения заданий в другой операционной системе. Например, можно использовать размещенные в GitHub средства выполнения Windows.

runs-on: windows-latest

Кроме этого, можно выполнять задания на размещенных в GitHub средствах выполнения macOS.

runs-on: macos-latest

Можно также выполнять задания в контейнерах Docker или предоставить локальное средство выполнения, которое выполняется в собственной инфраструктуре. Дополнительные сведения см. в разделе Синтаксис рабочего процесса для GitHub Actions.

Указание версии Node.js

Самый простой способ указать версию Node.js заключается в использовании действия setup-node, предоставляемого GitHub. Дополнительные сведения см. описании setup-node.

Действие setup-node принимает версию Node.js в качестве входных данных и настраивает ее в средстве выполнения. Действие setup-node находит определенную версию Node.js из кэша инструментов в каждом средстве запуска и добавляет необходимые двоичные файлы в переменную PATH, которая сохраняется до конца задания. Применение действия setup-node представляет собой рекомендуемый способ использования Node.js с GitHub Actions, так как он обеспечивает согласованное поведение в разных средствах выполнения и различных версиях Node.js. При использовании локального средства выполнения необходимо установить Node.js и добавить его в PATH.

Начальный рабочий процесс включает матричную стратегию, которая создает и тестирует код с четырьмя версиями Node.js: 14.x, 16.x, 18.x и 20.x. Здесь "x" — это подстановочный знак, соответствующий последнему дополнительному выпуску и выпуску исправлений, доступному для версии. Каждая версия Node.js, указанная в массиве node-version, создает задание, которое выполняет одни и те же действия.

Каждое задание может получить доступ к значению, определенному в массиве node-version матрицы, с помощью контекста matrix. Действие setup-node использует контекст в качестве входных данных node-version. Действие setup-node настраивает каждое задание с использованием разных версий Node.js перед созданием и тестированием кода. Дополнительные сведения о матричных стратегиях и контекстах см. в разделах Синтаксис рабочего процесса для GitHub Actions и Контексты.

strategy:
  matrix:
    node-version: [14.x, 16.x, 18.x, 20.x]

steps:
- uses: actions/checkout@v3
- name: Use Node.js ${{ matrix.node-version }}
  uses: actions/setup-node@v3
  with:
    node-version: ${{ matrix.node-version }}

Кроме того, можно создавать и тестировать код с использованием конкретных версий Node.js.

strategy:
  matrix:
    node-version: [10.17.0, 17.9.0]

Либо можно создавать и тестировать код с помощью одной версии Node.js.

name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18.x'
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

Если не указать версию Node.js, GitHub использует версию Node.js по умолчанию, заданную для среды. Дополнительные сведения см. в разделе О средствах выполнения, размещенных в GitHub.

Установка зависимостей

Для размещенных в GitHub средств выполнения установлены диспетчеры зависимостей npm и Yarn. Вы можете использовать npm и Yarn для установки зависимостей в рабочем процессе перед созданием и тестированием кода. В Windows и Linux для размещенных в GitHub средств выполнения также установлены Grunt, Gulp и Bower.

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

Пример использования npm

В этом примере устанавливаются зависимости, определенные в файле package.json. Дополнительные сведения см. на веб-сайте npm install.

steps:
- uses: actions/checkout@v3
- name: Use Node.js
  uses: actions/setup-node@v3
  with:
    node-version: '18.x'
- name: Install dependencies
  run: npm install

При использовании npm ci версии устанавливаются в файл package-lock.json или npm-shrinkwrap.json, а также запрещается изменение файла блокировки. Выполнение npm ci обычно осуществляется быстрее, чем npm install. Дополнительные сведения см. в описании npm ci и разделе Знакомство с npm ci для получения более быстродействующих и надежных сборок.

steps:
- uses: actions/checkout@v3
- name: Use Node.js
  uses: actions/setup-node@v3
  with:
    node-version: '18.x'
- name: Install dependencies
  run: npm ci

Пример использования Yarn

В этом примере устанавливаются зависимости, определенные в файле package.json. Дополнительные сведения см. на веб-сайте yarn install.

steps:
- uses: actions/checkout@v3
- name: Use Node.js
  uses: actions/setup-node@v3
  with:
    node-version: '18.x'
- name: Install dependencies
  run: yarn

Кроме того, можно передать --frozen-lockfile, чтобы установить версии в файле yarn.lock и запретить изменения файла yarn.lock.

steps:
- uses: actions/checkout@v3
- name: Use Node.js
  uses: actions/setup-node@v3
  with:
    node-version: '18.x'
- name: Install dependencies
  run: yarn --frozen-lockfile

Пример использования частного реестра и создания NPMRC-файла

Действие setup-node можно использовать для создания локального NPMRC-файла в средстве выполнения, который настраивает реестр и область по умолчанию. Действие setup-node также принимает в качестве входных данных маркер проверки подлинности, используемый для доступа к частным реестрам или публикации пакетов узлов. Дополнительные сведения см. на веб-сайте setup-node.

Чтобы пройти проверку подлинности в частном реестре, нужно сохранить маркер проверки подлинности npm в виде секрета. Например, создайте секрет репозитория NPM_TOKEN. Дополнительные сведения см. в разделе Зашифрованные секреты.

В приведенном ниже примере в NPM_TOKEN секрета хранится токен проверки подлинности npm. Действие setup-node настраивает файл NPMRC для чтения маркера проверки подлинности npm из переменной среды NODE_AUTH_TOKEN. При использовании действия setup-node для создания файла NPMRC необходимо задать для переменной среды NODE_AUTH_TOKEN секрет, содержащий маркер проверки подлинности npm.

Перед установкой зависимостей используйте действие setup-node для создания файла NPMRC. Это действие имеет два входных параметра. Параметр node-version задает версию Node.js, а параметр registry-url задает реестр по умолчанию. Если в реестре пакетов используются области, необходимо использовать параметр scope. Дополнительные сведения см. на веб-сайте npm-scope.

steps:
- uses: actions/checkout@v3
- name: Use Node.js
  uses: actions/setup-node@v3
  with:
    always-auth: true
    node-version: '18.x'
    registry-url: https://registry.npmjs.org
    scope: '@octocat'
- name: Install dependencies
  run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

В приведенном выше примере создается файл NPMRC со следующим содержимым:

//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
@octocat:registry=https://registry.npmjs.org/
always-auth=true

Примеры кэширования зависимостей

Можно кэшировать и восстанавливать зависимости с помощью setup-nodeдействия.

В следующем примере кэшируются зависимости для npm.

steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
  with:
    node-version: '14'
    cache: 'npm'
- run: npm install
- run: npm test

В следующем примере кэшируются зависимости для Yarn.

steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
  with:
    node-version: '14'
    cache: 'yarn'
- run: yarn
- run: yarn test

В следующем примере кэшируются зависимости для pnpm (версия 6.10 или более поздняя).

# Этот рабочий процесс использует действия, которые не сертифицированы GitHub.
# Они предоставляются сторонним поставщиком, и на них распространяются
# отдельные условия обслуживания, политика конфиденциальности и поддержка
# документации.

# NOTE: pnpm caching support requires pnpm version >= 6.10.0

steps:
- uses: actions/checkout@v3
- uses: pnpm/action-setup@0609f0983b7a228f052f81ef4c3d6510cae254ad
  with:
    version: 6.10.0
- uses: actions/setup-node@v3
  with:
    node-version: '14'
    cache: 'pnpm'
- run: pnpm install
- run: pnpm test

Если у вас есть особые требования или вам нужно управлять кэшированием более детально, можно использовать действие cache. Дополнительные сведения см. в разделе Кэширование зависимостей для ускорения рабочих процессов.

Создание и тестирование кода

Вы можете использовать те же команды, которые используются для создания и тестирования кода в локальной среде. Например, при запуске npm run build для выполнения шагов сборки, определенных в файле package.json, и npm test для выполнения набора тестов, вам нужно добавить эти команды в свой файл рабочего процесса.

steps:
- uses: actions/checkout@v3
- name: Use Node.js
  uses: actions/setup-node@v3
  with:
    node-version: '18.x'
- run: npm install
- run: npm run build --if-present
- run: npm test

Упаковка данных рабочего процесса в виде артефактов

Вы можете сохранить артефакты из шагов сборки и тестирования, чтобы просмотреть их после завершения задания. Например, может потребоваться сохранить файлы журналов, основные дампы, результаты теста или снимки экрана. Дополнительные сведения см. в разделе Хранение данных рабочего процесса в виде артефактов.

Публикация в реестрах пакетов

Вы можете настроить рабочий процесс для публикации пакета Node.js в реестре пакетов после прохождения тестов CI. Дополнительные сведения о публикации в npm и GitHub Packages см. в разделе Публикация пакетов Node.js.