Criar e testar Node.js

Introdução

Este guia mostra como criar um fluxo de trabalho de integração contínua (CI) que cria e testa o código Node.js. Se o seu teste de CI for aprovado, é possível que você deseje publicar seu código ou um pacote.

Pré-requisitos

Recomendamos que você tenha um entendimento básico do Node.js, YAML, das opções de configuração do fluxo de trabalho e de como criar um arquivo do fluxo de trabalho. Para obter mais informações, consulte:

Usando o fluxo de trabalho inicial do Node.js

GitHub fornece um fluxo de trabalho inicial do Node.js que funcionará para a maioria dos projetos do Node.js. Esse guia inclui exemplos de npm e Yarn que você pode usar para personalizar o fluxo de trabalho inicial. Para obter mais informações, confira o fluxo de trabalho inicial do Node.js.

Os fluxos de trabalho inicial padrão são excelentes pontos de partida ao criar seu fluxo de trabalho de criação e teste, e você pode personalizar o fluxo de trabalho inicial para atender às necessidades do seu projeto.

Para experimentar uma introdução rápida, adicione o fluxo de trabalho inicial ao diretório .github/workflows do repositório.

YAML

# Nome do fluxo de trabalho. O GitHub exibe os nomes dos fluxos de trabalho na guia "Ações" do repositório. Se você omitir `name`, o GitHub exibirá o caminho do arquivo de fluxo de trabalho em relação à raiz do repositório.
name: Node.js CI

# This example workflow assumes that the default branch for your repository is `main`. If the default branch has a different name, edit this example and add your repository's default branch.
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]

#
jobs:
build:

# 
# Você pode executar esse fluxo de trabalho usando um sistema operacional diferente.
#
# O fluxo de trabalho inicial configura os trabalhos a serem executados no Linux usando os executores `ubuntu-latest` hospedados no GitHub. É possível alterar a chave `runs-on` para executar seus trabalhos em outro sistema operacional.
#
# Por exemplo, você pode usar os executores Windows hospedados no GitHub especificando `runs-on: windows-latest`. Ou você pode executar os executores macOS hospedados no GitHub usando `runs-on: macos-latest`.
#
# Você também pode executar tarefas em contêineres Docker ou fornecer um executor de auto-hospedagem que funciona na sua própria infraestrutura. Para obter mais informações, confira "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)".
runs-on: ubuntu-latest

# This job uses a matrix strategy to run the job four times, once for each specified Node version. For more information, see "[AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs)."
strategy:
matrix:
node-version: [14.x, 16.x, 18.x, 20.x]
#
steps:
# Esta etapa usa a ação `actions/checkout` para fazer download de uma cópia do repositório no executor.
- uses: actions/checkout@v4
# This step uses the `actions/setup-node` action to set up Node.js for each version indicated by the `matrix.node-version` key above.
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
# This step runs `npm ci` to install any dependencies listed in your `package.json` file.
- run: npm ci
# This step runs the `build` script if there is one specified under the `scripts` key in your `package.json` file.
- run: npm run build --if-present
# This step runs the `test` script that is specified under the `scripts` key in your `package.json` file.
- run: npm test

name: Node.js CI

Nome do fluxo de trabalho. O GitHub exibe os nomes dos fluxos de trabalho na guia "Ações" do repositório. Se você omitir name, o GitHub exibirá o caminho do arquivo de fluxo de trabalho em relação à raiz do repositório.

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

This example workflow assumes that the default branch for your repository is main. If the default branch has a different name, edit this example and add your repository's default branch.

jobs:
  build:

    runs-on: ubuntu-latest

Você pode executar esse fluxo de trabalho usando um sistema operacional diferente.

O fluxo de trabalho inicial configura os trabalhos a serem executados no Linux usando os executores ubuntu-latest hospedados no GitHub. É possível alterar a chave runs-on para executar seus trabalhos em outro sistema operacional.

Por exemplo, você pode usar os executores Windows hospedados no GitHub especificando runs-on: windows-latest. Ou você pode executar os executores macOS hospedados no GitHub usando runs-on: macos-latest.

Você também pode executar tarefas em contêineres Docker ou fornecer um executor de auto-hospedagem que funciona na sua própria infraestrutura. Para obter mais informações, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".

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

This job uses a matrix strategy to run the job four times, once for each specified Node version. For more information, see "Usando uma matriz para seus trabalhos."

    steps:

      - uses: actions/checkout@v4

Esta etapa usa a ação actions/checkout para fazer download de uma cópia do repositório no executor.

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

This step uses the actions/setup-node action to set up Node.js for each version indicated by the matrix.node-version key above.

      - run: npm ci

This step runs npm ci to install any dependencies listed in your package.json file.

      - run: npm run build --if-present

This step runs the build script if there is one specified under the scripts key in your package.json file.

      - run: npm test

This step runs the test script that is specified under the scripts key in your package.json file.

# Nome do fluxo de trabalho. O GitHub exibe os nomes dos fluxos de trabalho na guia "Ações" do repositório. Se você omitir `name`, o GitHub exibirá o caminho do arquivo de fluxo de trabalho em relação à raiz do repositório.
name: Node.js CI

# This example workflow assumes that the default branch for your repository is `main`. If the default branch has a different name, edit this example and add your repository's default branch.
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

#
jobs:
  build:

    # <!-- This is a YAML comment for use in annotated code examples. -->
    # Você pode executar esse fluxo de trabalho usando um sistema operacional diferente.
    #
    # O fluxo de trabalho inicial configura os trabalhos a serem executados no Linux usando os executores `ubuntu-latest` hospedados no GitHub. É possível alterar a chave `runs-on` para executar seus trabalhos em outro sistema operacional.
    #
    # Por exemplo, você pode usar os executores Windows hospedados no GitHub especificando `runs-on: windows-latest`. Ou você pode executar os executores macOS hospedados no GitHub usando `runs-on: macos-latest`.
    #
    # Você também pode executar tarefas em contêineres Docker ou fornecer um executor de auto-hospedagem que funciona na sua própria infraestrutura. Para obter mais informações, confira "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)".
    runs-on: ubuntu-latest

    # This job uses a matrix strategy to run the job four times, once for each specified Node version. For more information, see "[AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs)."
    strategy:
      matrix:
        node-version: [14.x, 16.x, 18.x, 20.x]
#
    steps:
      # Esta etapa usa a ação `actions/checkout` para fazer download de uma cópia do repositório no executor.
      - uses: actions/checkout@v4
      # This step uses the `actions/setup-node` action to set up Node.js for each version indicated by the `matrix.node-version` key above.
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      # This step runs `npm ci` to install any dependencies listed in your `package.json` file.
      - run: npm ci
      # This step runs the `build` script if there is one specified under the `scripts` key in your `package.json` file.
      - run: npm run build --if-present
      # This step runs the `test` script that is specified under the `scripts` key in your `package.json` file.
      - run: npm test

Especificar a versão do Node.js

A maneira mais fácil de especificar uma versão do Node.js é usando a ação setup-node fornecida pelo GitHub. Para obter mais informações, confira setup-node.

A ação setup-node usa uma versão do Node.js como entrada e configura essa versão no executor. A ação setup-node localiza uma versão específica do Node.js no cache de ferramentas em cada executor e adiciona os binários necessários a PATH, que é persistente no restante do trabalho. Usar a ação setup-node é a maneira recomendada de usar o Node.js com o GitHub Actions, porque garante um comportamento consistente entre diferentes executores e diferentes versões do Node.js. Se você estiver usando um executor auto-hospedado, precisará instalar o Node.js e adicioná-lo a PATH.

O fluxo de trabalho inicial inclui uma estratégia de matriz que compila e testa seu código com quatro versões do Node.js: 14.x, 16.x, 18.x e 20.x. O "x" é um caractere curinga que corresponde à última versão menor e à versão do patch disponível para uma versão. Cada versão do Node.js especificada na matriz node-version cria um trabalho que executa as mesmas etapas.

Cada trabalho pode acessar o valor definido na matriz node-version da matriz usando o contexto matrix. A ação setup-node usa o contexto como a entrada de node-version. A ação setup-node configura cada trabalho com uma versão diferente do Node.js antes de compilar e testar o código. Para obter mais informações sobre estratégias e contextos de matriz, confira "Sintaxe de fluxo de trabalho para o GitHub Actions" e "Contextos".

YAML

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

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

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

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

Como alternativa, você pode criar e fazes testes com versões exatas do Node.js.

YAML

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

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

Você também pode criar e testar usando uma versão única do Node.js.

YAML

name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

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

name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

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

Se você não especificar uma versão do Node.js, o GitHub usará a versão-padrão do Node.js do ambiente. Para obter mais informações, confira "Using GitHub-hosted runners".

Instalar dependências

Executores hospedados em GitHub têm gerenciadores de dependências npm e Yarn instalados. Você pode usar o npm e o Yarn para instalar dependências no seu fluxo de trabalho antes de criar e testar seu código. Os executores do Windows e Linux hospedados em GitHub também têm o Grunt, Gulp, e Bower instalado.

Você também pode armazenar as dependências em cache para acelerar o fluxo de trabalho. Para obter mais informações, confira "Memorizar dependências para acelerar os fluxos de trabalho".

Exemplo de uso do npm

Este exemplo instala as versões no arquivo package-lock.json ou npm-shrinkwrap.json e impede atualizações no arquivo de bloqueio. O uso de npm ci geralmente é mais rápido do que a execução de npm install. Para obter mais informações, confira npm ci e "Apresentação do npm ci para builds mais rápidos e confiáveis".

YAML

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

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

Com npm install, instala as dependências definidas no arquivo package.json. Para obter mais informações, confira npm install.

YAML

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

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

Exemplo de uso do Yarn

Este exemplo instala as dependências definidas no arquivo yarn.lock e evita atualizações no arquivo yarn.lock. Para obter mais informações, confira yarn install.

YAML

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

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

Como alternativa, você pode instalar as dependências definidas no arquivo package.json.

YAML

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

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

Exemplo do uso de um registro privado e de criação o arquivo .npmrc

Você pode usar a ação setup-node para criar um arquivo .npmrc local no executor que configura o registro e o escopo padrão. A ação setup-node também aceita um token de autenticação como entrada, usado para acessar registros privados ou publicar pacotes de nós. Para obter mais informações, confira setup-node.

Para efetuar a autenticação com seu registro privado, você precisará armazenar seu token de autenticação npm como um segredo. Por exemplo, crie um segredo do repositório chamado NPM_TOKEN. Para obter mais informações, confira "Usar segredos em ações do GitHub".

No exemplo abaixo, o segredo NPM_TOKEN armazena o token de autenticação do npm. A ação setup-node configura o arquivo .npmrc para ler o token de autenticação do npm da variável de ambiente NODE_AUTH_TOKEN. Ao usar a ação setup-node para criar um arquivo .npmrc, você precisa definir a variável de ambiente NODE_AUTH_TOKEN com o segredo que contém o token de autenticação do npm.

Antes de instalar as dependências, use a ação setup-node para criar o arquivo .npmrc. A ação tem dois parâmetros de entrada. O parâmetro node-version define a versão do Node.js, e o parâmetro registry-url define o registro padrão. Se o registro de pacote usa escopos, é preciso usar o parâmetro scope. Para obter mais informações, confira npm-scope.

YAML

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  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 }}

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  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 }}

O exemplo acima cria um arquivo .npmrc com o seguinte conteúdo:

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

Exemplo de memorização de dependências

Você pode armazenar em cache e restaurar as dependências usando a ação setup-node.

O exemplo a seguir armazena dependências do npm.

YAML

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

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

O exemplo a seguir armazena dependências para o Yarn.

YAML

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

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

O exemplo a seguir armazena dependências para pnpm (v6.10+).

YAML

# Esse fluxo de trabalho usa ações que não são certificadas pelo GitHub.
# São fornecidas por terceiros e regidas por
# termos de serviço, política de privacidade e suporte separados
# online.

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

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

# Esse fluxo de trabalho usa ações que não são certificadas pelo GitHub.
# São fornecidas por terceiros e regidas por
# termos de serviço, política de privacidade e suporte separados
# online.

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

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

Se você tiver um requisito personalizado ou precisar ter controles mais refinados para o cache, use a ação cache. Para obter mais informações, confira "Memorizar dependências para acelerar os fluxos de trabalho".

Criar e testar seu código

Você pode usar os mesmos comandos usados localmente para criar e testar seu código. Por exemplo, se você executar npm run build para executar as etapas de build definidas no arquivo package.json e npm test para executar o conjunto de testes, adicione esses comandos ao arquivo de fluxo de trabalho.

YAML

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

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

Empacotar dados do fluxo de trabalho como artefatos

Você pode salvar artefatos das suas etapas de criação e teste para serem visualizados após a conclusão de um trabalho. Por exemplo, é possível que você precise salvar os arquivos de registro, os despejos de núcleo, os resultados de teste ou capturas de tela. Para obter mais informações, confira "Armazenar dados do fluxo de trabalho como artefatos".

Publicar nos registros do pacote

Você pode configurar o seu fluxo de trabalho para publicar o seu pacote Node.js em um pacote de registro após os seus testes de CI serem aprovados. Para obter mais informações sobre a publicação no npm e no GitHub Packages, confira "Publicar pacotes do Node.js".

Criar e testar Node.js

Neste artigo