Crear y probar en Node.js

Introducción

Esta guía te muestra cómo crear un flujo de trabajo de integración continua (CI) que construye y prueba código Node.js. Si tus pruebas de CI se superan, es posible que desees implementar tu código o publicar un paquete.

Prerrequisitos

Te recomendamos que tengas una comprensión básica de Node.js, YAML, las opciones de configuración de flujo de trabajo y cómo crear un archivo de flujo de trabajo. Para obtener más información, consulta:

• "Aprende sobre las GitHub Actions"
• "Iniciar con Node.js"

Utilizar ejecutores auto-hospedados en GitHub Enterprise Server

Cuando utilices acciones de configuración, (tales como actions/setup-LANGUAGE) en GitHub Enterprise Server con ejecutores auto-hospedados, tal vez necesites configurar el caché de las herramientas en los ejecutores que no tienen acceso a internet. Para obtener más información, consulta la sección " Configurar el caché de herramientas en ejecutores auto-hospedados sin acceso a internet".

Comenzar con una plantilla de flujo de trabajo de Node.js

GitHub proporciona una plantilla de flujo de trabajo de Node.js que funcionará para la mayoría de los proyectos Node.js. Esta guía incluye ejemplos de npm y Yarn que puedes usar para personalizar la plantilla. Para obtener más información, consulta la Plantilla de flujo de trabajo Node.js.

Para comenzar rápidamente, agrega la plantilla al directorio .github/workflows de tu repositorio. El flujo de trabajo que se muestra a continuación asume que la rama predeterminada de tu repositorio es main.

name: Node.js CI

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

jobs:
  build:

    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [10.x, 12.x, 14.x, 15.x]

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

Ejecución en un sistema operativo diferente

La plantilla inicial de flujo de trabajo configura los jobs para que se ejecuten en Linux, utilizando los ejecutores ubuntu-latest hospedados en GitHub. Puedes cambiar la clave runs-on para ejecutar tus jobs en un sistema operativo diferente. Por ejemplo, puedes utilizar los ejecutores de Windows hospedados en GitHub.

runs-on: windows-latest

O puedes utilizar los ejecutores de macOS hospedados en GitHub.

runs-on: macos-latest

También puedes ejecutar jobs en contenedores de Docker, o puedes proporcionar un ejecutor auto-hospedado que se ejecute en tu propia infraestructura. Para obtener más información, consulta "Sintaxis de flujo de trabajo para GitHub Actions".

Especificar la versión de Node.js

La forma más fácil de especificar una versión de Node.js es por medio de la acción setup-node proporcionada por GitHub. Para obtener más información, consulta setup-node.

La acción setup-node toma una versión de Node.js como una entrada y configura esa versión en el ejecutor. La acción setup-node encuentra una versión específica de Node.js de la caché de herramientas en cada ejecutor y añade los binarios necesarios a PATH, que continúan para el resto del trabajo. Usar la acción setup-node es la forma recomendada de usar Node.js con GitHub Actions porque asegura un comportamiento consistente a través de diferentes ejecutores y diferentes versiones de Node.js. Si estás usando un ejecutor autoalojado, debes instalar Node.js y añadirlo a PATH.

La plantilla incluye una estrategia de matriz que crea y prueba tu código con cuatro versiones de Node.js: 10.x, 12.x, 14.x, y 15.x. La 'x' es un carácter comodín que coincide con el último lanzamiento menor y de parche disponible para una versión. Cada versión de Node.js especificada en la matriz node-version crea un trabajo que ejecuta los mismos pasos.

Cada trabajo puede acceder al valor definido en la matriz node-version por medio del contexto matrix. La acción setup-node utiliza el contexto como la entrada node-version. La acción setup-node configura cada trabajo con una versión diferente de Node.js antes de construir y probar código. Para obtener más información acerca de las estrategias y los contextos de la matriz, consulta las secciones "Sintaxis de flujo de trabajo para las GitHub Actions" y "Contextos".

strategy:
  matrix:
    node-version: [10.x, 12.x, 14.x, 15.x]

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

Como alternativa, puedes construir y probar con las versiones exactas de Node.js.

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

O bien, puedes construir y probar mediante una versión única de Node.js.

name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

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

Si no especificas una versión de Node.js, GitHub utiliza la versión de Node.js por defecto del entorno. Para obtener más información, consulta la sección "Especificaciones para los ejecutores hospedados en GitHub".

Instalar dependencias

Los ejecutores alojados en GitHub tienen instalados administradores de dependencias de npm y Yarn. Puedes usar npm y Yarn para instalar dependencias en tu flujo de trabajo antes de construir y probar tu código. Los ejecutores Windows y Linux alojados en GitHub también tienen instalado Grunt, Gulp y Bower.

Cuando utilizas ejecutores hospedados en GitHub, también puedes guardar las dependencias en el caché para acelerar tu flujo de trabajo. Para obtener más información, consulta la sección "Almacenar las dependencias en caché para agilizar los flujos de trabajo".

Ejemplo con npm

Este ejemplo instala las dependencias definidas en el archivo package.json. Para obtener más información, consulta Instalar npm.

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

Mediante npm ci se instalan las versiones en el archivo package-lock.json o npm-shrinkwrap.json y se evitan las actualizaciones al archivo de bloqueo. Usar npm ci generalmente es más rápido que ejecutar npm install. Para obtener más información, consulta npm ci e Introducir npm ci para construcciones más rápidas y confiables."

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

Ejemplo con Yarn

Este ejemplo instala las dependencias definidas en el archivo package.json. Para obtener más información, consulta Instalar yarn.

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

De forma alternativa, puede pasar --frozen-lockfile para instalar las versiones en el archivo yarn.lock y evitar actualizaciones al archivo yarn.lock.

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

Ejemplo de uso de un registro privado y la creación del archivo .npmrc

Puedes utilizar la acción setup-node para crear un archivo local de tipo .npmrc en el ejecutor que configura el registro y alcance predeterminados. La acción setup-node también acepta un token de autenticación como entrada, el cual se utiliza para acceder a los registros privados o paquetes de nodo publicados. Para obtener más información, consulta la sección setup-node.

Para autenticar tu registro privado, necesitarás almacenar tu token de autenticación de npm como un secreto. Por ejemplo, crea un repositorio secreto que se llame NPM_TOKEN. Para más información, consulta "Crear y usar secretos cifrados."

En el siguiente ejemplo, el secreto NPM_TOKEN almacena el token de autenticación npm. La acción setup-node configura el archivo .npmrc para leer el token de autenticación npm desde la variable de entorno NODE_AUTH_TOKEN. Cuando utilices la acción setup-node para crear un archivo .npmrc, debes configurar la variable de ambiente NODE_AUTH_TOKEN con el secreto que contiene tu token de autenticación de npm.

Antes de instalar dependencias, utiliza la acción setup-node para crear el archivo .npmrc. La acción tiene dos parámetros de entrada. El parámetro node-version establece la versión de Node.js y el parámetro registry-url establece el registro predeterminado. Si tu registro de paquetes usa ámbitos, debes usar el parámetro scope. Para obtener más información, consulta npm-scope.

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

El ejemplo anterior crea un archivo .npmrc con el siguiente contenido:

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

Ejemplo de dependencias en caché

Cuando utilices ejecutores hospedados en GitHub, puedes guardarlos en caché y restablecer las dependencias utilizando la acción setup-node.

El siguiente ejemplo guarda las dependencias en caché para npm.

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

El siguiente ejemplo guarda las dependencias en caché para Yarn.

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

El siguiente ejemplo guarda las dependencias en caché para pnpm (v6.10+).

# This workflow uses actions that are not certified by GitHub.
# Estas las proporcionan entidades terceras y las gobiernan
# condiciones de servicio, políticas de privacidad y documentación de soporte
# documentación.

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

steps:
- uses: actions/checkout@v2
- uses: pnpm/action-setup@646cdf48217256a3d0b80361c5a50727664284f2
  with:
    version: 6.10.0
- uses: actions/setup-node@v2
  with:
    node-version: '14'
    cache: 'pnpm'
- run: pnpm install
- run: pnpm test

Para guardar las dependencias en caché, debes tener un archivo de package-lock.json, yarn.lock, o pnpm-lock.yaml en la raíz del repositorio. Si necesitas una personalización más flexible, puedes utilizar la acción cache. Para obtener más información, consulta la sección "Almacenar las dependencias en caché para agilizar los flujos de trabajo".

Construir y probar tu código

Puedes usar los mismos comandos que usas de forma local para construir y probar tu código. Por ejemplo, si ejecutas npm run build para ejecutar pasos de construcción definidos en tu archivo package.json y npm test para ejecutar tu conjunto de pruebas, añadirías esos comandos en tu archivo de flujo de trabajo.

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

Empaquetar datos de flujo de trabajo como artefactos

Puedes guardar los artefactos de tus pasos de construcción y prueba para verlos después de que se complete un trabajo. Por ejemplo, es posible que debas guardar los archivos de registro, los vaciados de memoria, los resultados de las pruebas o las capturas de pantalla. Para obtener más información, consulta "Conservar datos de flujo de trabajo mediante artefactos."

Publicar en registros de paquetes

Puedes configurar tu flujo de trabajo para que publique tu paquete Node.js en un registro de paquete después de que se aprueben tus pruebas de CI. Para obtener más información acerca de la publicación a npm y Registro del paquete de GitHub, consulta Publicar paquetes Node.js."