Node.js 빌드 및 테스트하기

Node.js 프로젝트를 빌드하고 테스트하는 지속적 통합(CI) 워크플로를 만드는 방법을 알려드릴게요. CI 테스트가 통과하면 코드를 배포하거나 패키지를 게시할 수 있어요.

출처: 문서

본문

Node.js 코드를 빌드하고 테스트하는 지속적 통합(CI) 워크플로를 만드는 방법을 알아봅니다. CI 테스트가 통과하면 코드를 배포하거나 패키지를 게시하고 싶을 수 있습니다.

사전 요구 사항

Node.js, YAML, 워크플로 구성 옵션, 워크플로 파일 작성 방법에 대한 기본적인 이해를 권장합니다. 자세한 내용은 다음을 참고하세요:

Node.js 워크플로 템플릿 사용하기

빠르게 시작하려면 저장소의 .github/workflows 디렉터리에 워크플로 템플릿을 추가하세요.

GitHub는 대부분의 Node.js 프로젝트에서 작동하는 Node.js용 워크플로 템플릿을 제공합니다. 이 가이드의 이후 섹션은 이 워크플로 템플릿을 사용자 지정하는 방법의 예시를 제공합니다.

GitHub에서 저장소의 메인 페이지로 이동합니다.
저장소 이름 아래에서 Actions를 클릭합니다.
저장소에 이미 워크플로가 있다면 New workflow를 클릭합니다.
"Choose a workflow" 페이지에 추천 워크플로 템플릿 목록이 표시됩니다. "Node.js"를 검색하세요.
Continuous integration을 클릭해서 워크플로 선택을 필터링합니다.
"Node.js" 워크플로에서 Configure를 클릭합니다.
필요에 따라 워크플로를 편집합니다. 예를 들어 사용할 Node 버전을 변경합니다.
Commit changes를 클릭합니다.

node.js.yml 워크플로 파일이 저장소의 .github/workflows 디렉터리에 추가됩니다.

Node.js 버전 지정하기

Node.js 버전을 지정하는 가장 쉬운 방법은 GitHub가 제공하는 setup-node 액션을 사용하는 것입니다. 자세한 내용은 setup-node을 참고하세요.

setup-node 액션은 Node.js 버전을 입력으로 받아 러너에 해당 버전을 구성합니다. setup-node 액션은 각 러너의 도구 캐시에서 특정 Node.js 버전을 찾아 필요한 바이너리를 PATH에 추가하며, 이는 잡의 나머지 기간 동안 유지됩니다. setup-node 액션을 사용하는 것은 다양한 러너와 다양한 Node.js 버전에서 일관된 동작을 보장하므로 GitHub Actions에서 Node.js를 사용하는 권장 방법입니다. 셀프 호스팅 러너를 사용한다면 Node.js를 설치하고 PATH에 추가해야 합니다.

워크플로 템플릿에는 node-version에 나열된 Node.js 버전으로 코드를 빌드하고 테스트하는 매트릭스 전략이 포함되어 있습니다. 버전 번호의 'x'는 해당 버전에 사용할 수 있는 최신 마이너 및 패치 릴리스를 매칭하는 와일드카드 문자입니다. node-version 배열에 지정된 각 Node.js 버전은 같은 스텝을 실행하는 잡 하나를 만듭니다.

각 잡은 matrix 컨텍스트를 사용해서 매트릭스 node-version 배열에 정의된 값에 접근할 수 있습니다. setup-node 액션은 이 컨텍스트를 node-version 입력으로 사용합니다. setup-node 액션은 코드를 빌드하고 테스트하기 전에 각 잡을 다른 Node.js 버전으로 구성합니다. 매트릭스 전략과 컨텍스트에 대한 자세한 내용은 Workflow syntax for GitHub Actions와 Contexts reference를 참고하세요.

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

steps:
- uses: actions/checkout@v6
- name: Use Node.js ${{ matrix.node-version }}
  uses: actions/setup-node@v7
  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@v6
      - name: Use Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '20.x'
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

Node.js 버전을 지정하지 않으면 GitHub는 환경의 기본 Node.js 버전을 사용합니다. 자세한 내용은 GitHub-hosted runners를 참고하세요.

의존성 설치하기

GitHub 호스팅 러너에는 npm과 Yarn 의존성 관리자가 설치되어 있습니다. 코드를 빌드하고 테스트하기 전에 워크플로에서 npm과 Yarn을 사용해서 의존성을 설치할 수 있습니다. Windows와 Linux GitHub 호스팅 러너에는 Grunt, Gulp, Bower도 설치되어 있습니다.

의존성을 캐시해서 워크플로를 빠르게 할 수도 있습니다. 자세한 내용은 Dependency caching reference를 참고하세요.

npm을 사용하는 예시

이 예시는 package-lock.json 또는 npm-shrinkwrap.json 파일의 버전을 설치하고 잠금 파일의 업데이트를 방지합니다. npm ci를 사용하는 것이 일반적으로 npm install을 실행하는 것보다 빠릅니다. 자세한 내용은 npm ci와 Introducing npm ci for faster, more reliable builds를 참고하세요.

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

npm install을 사용하면 package.json 파일에 정의된 의존성을 설치합니다. 자세한 내용은 npm install을 참고하세요.

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

Yarn을 사용하는 예시

이 예시는 yarn.lock 파일에 정의된 의존성을 설치하고 yarn.lock 파일의 업데이트를 방지합니다. 자세한 내용은 yarn install을 참고하세요.

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

또는 package.json 파일에 정의된 의존성을 설치할 수 있습니다.

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

비공개 레지스트리를 사용하고 .npmrc 파일 만들기

setup-node 액션을 사용해서 기본 레지스트리와 스코프를 구성하는 러너의 로컬 .npmrc 파일을 만들 수 있습니다. setup-node 액션은 비공개 레지스트리에 접근하거나 node 패키지를 게시하는 데 사용되는 인증 토큰을 입력으로 받기도 합니다. 자세한 내용은 setup-node을 참고하세요.

비공개 레지스트리에 인증하려면 npm 인증 토큰을 시크릿으로 저장해야 합니다. 예를 들어 NPM_TOKEN이라는 저장소 시크릿을 만듭니다. 자세한 내용은 Using secrets in GitHub Actions를 참고하세요.

아래 예시에서 NPM_TOKEN 시크릿은 npm 인증 토큰을 저장합니다. setup-node 액션은 .npmrc 파일이 NODE_AUTH_TOKEN 환경 변수에서 npm 인증 토큰을 읽도록 구성합니다. setup-node 액션으로 .npmrc 파일을 만들 때는 npm 인증 토큰이 포함된 시크릿으로 NODE_AUTH_TOKEN 환경 변수를 설정해야 합니다.

의존성을 설치하기 전에 setup-node 액션을 사용해서 .npmrc 파일을 만듭니다. 이 액션에는 두 개의 입력 파라미터가 있습니다. node-version 파라미터는 Node.js 버전을 설정하고, registry-url 파라미터는 기본 레지스트리를 설정합니다. 패키지 레지스트리가 스코프를 사용한다면 scope 파라미터를 사용해야 합니다. 자세한 내용은 npm-scope을 참고하세요.

steps:
- uses: actions/checkout@v6
- name: Use Node.js
  uses: actions/setup-node@v7
  with:
    always-auth: true
    node-version: '20.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@v6
- uses: actions/setup-node@v7
  with:
    node-version: '20'
    cache: 'npm'
- run: npm install
- run: npm test

다음 예시는 Yarn용 의존성을 캐시합니다.

steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v7
  with:
    node-version: '20'
    cache: 'yarn'
- run: yarn
- run: yarn test

다음 예시는 pnpm(v6.10+)용 의존성을 캐시합니다.

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

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

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

사용자 지정 요구 사항이 있거나 캐싱을 더 세밀하게 제어해야 한다면 cache 액션을 사용할 수 있습니다. 자세한 내용은 Dependency caching reference를 참고하세요.

코드 빌드 및 테스트하기

로컬에서 코드를 빌드하고 테스트하는 데 사용하는 것과 같은 명령을 사용할 수 있습니다. 예를 들어 package.json 파일에 정의된 빌드 스텝을 실행하기 위해 npm run build를 실행하고 테스트 스위트를 실행하기 위해 npm test를 실행한다면, 그 명령들을 워크플로 파일에 추가하면 됩니다.

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

워크플로 데이터를 아티팩트로 패키징하기

잡이 완료된 후 볼 수 있도록 빌드 및 테스트 스텝의 아티팩트를 저장할 수 있습니다. 예를 들어 로그 파일, 코어 덤프, 테스트 결과, 스크린샷을 저장해야 할 수 있습니다. 자세한 내용은 Store and share data with workflow artifacts를 참고하세요.

패키지 레지스트리에 게시하기

CI 테스트가 통과한 후 Node.js 패키지를 패키지 레지스트리에 게시하도록 워크플로를 구성할 수 있습니다. npm과 GitHub Packages에 게시하는 방법에 대한 자세한 내용은 Publishing Node.js packages를 참고하세요.

Node.js 빌드 및 테스트하기