NPM Test

The npm-test job is used to run tests for Node.js applications using npm test scripts.

Overview

This job:

Installs npm dependencies
Runs npm test scripts
Supports custom test paths and Node.js versions
Can be extended to include test reports

Variables

The following variables can be configured:

Variable	Description	Default	Required
`NPM_BUILD_PATH`	The path to the directory containing `package.json`	`'./'`	No
`NODE_IMAGE`	The Docker image to use for Node.js commands	`'node:16.3.0-alpine'`	No

Variable Details

NPM_BUILD_PATH: The directory path where package.json is located. Defaults to the project root (./)
NODE_IMAGE: The Node.js Docker image version to use. Defaults to node:16.3.0-alpine (Alpine-based for smaller image size)

Usage

Basic Usage

variables:
  NPM_BUILD_PATH: './'
  NODE_IMAGE: 'node:16.3.0-alpine'

.npm-test:
  image: $NODE_IMAGE
  before_script:
    - cd $NPM_BUILD_PATH && npm install
  script:
    - cd $NPM_BUILD_PATH && npm test

Job Details

Before Script

The before_script section installs npm dependencies:

cd $NPM_BUILD_PATH && npm install

Changes to the directory containing package.json
Runs npm install to install all project dependencies
Dependencies are installed fresh for each pipeline run (not cached by default)

Script

The main script runs the test suite:

cd $NPM_BUILD_PATH && npm test

Changes to the test directory
Executes npm test which runs the test script defined in package.json
The test script is typically defined in the scripts.test field of package.json

Configuration Examples

Basic Test Job

variables:
  NPM_BUILD_PATH: './'
  NODE_IMAGE: 'node:16.3.0-alpine'

stages:
  - test

test:
  extends: .npm-test
  stage: test

Custom Test Path

variables:
  NPM_BUILD_PATH: 'frontend/'
  NODE_IMAGE: 'node:18-alpine'

test-frontend:
  extends: .npm-test
  stage: test

Different Node.js Version

variables:
  NPM_BUILD_PATH: './'
  NODE_IMAGE: 'node:20-alpine'

test:
  extends: .npm-test
  stage: test

With Test Reports

variables:
  NPM_BUILD_PATH: './'
  NODE_IMAGE: 'node:16.3.0-alpine'

.npm-test:
  image: $NODE_IMAGE
  before_script:
    - cd $NPM_BUILD_PATH && npm install
  script:
    - cd $NPM_BUILD_PATH && npm test
  artifacts:
    reports:
      junit: $NPM_BUILD_PATH/test-results.xml  # If using JUnit reporter
    paths:
      - $NPM_BUILD_PATH/coverage/  # If generating coverage reports
    expire_in: 1 week

test:
  extends: .npm-test
  stage: test

With Coverage Reports

variables:
  NPM_BUILD_PATH: './'
  NODE_IMAGE: 'node:16.3.0-alpine'

.npm-test:
  image: $NODE_IMAGE
  before_script:
    - cd $NPM_BUILD_PATH && npm install
  script:
    - cd $NPM_BUILD_PATH && npm test -- --coverage
  coverage: '/Lines\s*:\s*(\d+\.\d+)%/'
  artifacts:
    paths:
      - $NPM_BUILD_PATH/coverage/
    expire_in: 1 week

test:
  extends: .npm-test
  stage: test

Multiple Test Jobs

variables:
  NODE_IMAGE: 'node:16.3.0-alpine'

stages:
  - test

test-unit:
  extends: .npm-test
  variables:
    NPM_BUILD_PATH: './'
  stage: test
  script:
    - cd $NPM_BUILD_PATH && npm run test:unit

test-integration:
  extends: .npm-test
  variables:
    NPM_BUILD_PATH: './'
  stage: test
  script:
    - cd $NPM_BUILD_PATH && npm run test:integration

test-e2e:
  extends: .npm-test
  variables:
    NPM_BUILD_PATH: './'
  stage: test
  script:
    - cd $NPM_BUILD_PATH && npm run test:e2e

Complete Pipeline Example

variables:
  NPM_BUILD_PATH: './'
  NODE_IMAGE: 'node:16.3.0-alpine'

stages:
  - install
  - test
  - build

.npm-test:
  image: $NODE_IMAGE
  before_script:
    - cd $NPM_BUILD_PATH && npm install
  script:
    - cd $NPM_BUILD_PATH && npm test

# Install dependencies once
install-dependencies:
  image: $NODE_IMAGE
  stage: install
  script:
    - cd $NPM_BUILD_PATH && npm ci
  cache:
    key: ${CI_COMMIT_REF_SLUG}-npm
    paths:
      - $NPM_BUILD_PATH/node_modules/
  artifacts:
    paths:
      - $NPM_BUILD_PATH/node_modules/
    expire_in: 1 hour

# Run tests
test:
  extends: .npm-test
  stage: test
  dependencies:
    - install-dependencies
  cache:
    key: ${CI_COMMIT_REF_SLUG}-npm
    paths:
      - $NPM_BUILD_PATH/node_modules/
  artifacts:
    reports:
      junit: $NPM_BUILD_PATH/test-results.xml
    paths:
      - $NPM_BUILD_PATH/coverage/
    expire_in: 1 week

# Build after tests pass
build:
  image: $NODE_IMAGE
  stage: build
  dependencies:
    - install-dependencies
    - test
  script:
    - cd $NPM_BUILD_PATH && npm run build
  artifacts:
    paths:
      - $NPM_BUILD_PATH/dist/
    expire_in: 1 day

Package.json Test Script

The job relies on the test script defined in package.json. Example configurations:

Basic Test Script

{
  "scripts": {
    "test": "jest"
  }
}

With Coverage

{
  "scripts": {
    "test": "jest --coverage",
    "test:unit": "jest --testPathPattern=unit",
    "test:integration": "jest --testPathPattern=integration"
  }
}

With JUnit Reporter

{
  "scripts": {
    "test": "jest --reporters=default --reporters=jest-junit"
  },
  "devDependencies": {
    "jest-junit": "^15.0.0"
  }
}

Test Report Integration

To include test reports in GitLab CI/CD:

JUnit XML Reports

.npm-test:
  image: $NODE_IMAGE
  before_script:
    - cd $NPM_BUILD_PATH && npm install
  script:
    - cd $NPM_BUILD_PATH && npm test
  artifacts:
    reports:
      junit: $NPM_BUILD_PATH/test-results.xml

Coverage Reports

.npm-test:
  image: $NODE_IMAGE
  before_script:
    - cd $NPM_BUILD_PATH && npm install
  script:
    - cd $NPM_BUILD_PATH && npm test -- --coverage
  coverage: '/Lines\s*:\s*(\d+\.\d+)%/'
  artifacts:
    paths:
      - $NPM_BUILD_PATH/coverage/
    expire_in: 1 week

Prerequisites

package.json: A package.json file must exist in the NPM_BUILD_PATH directory
Test Script: The package.json must define a test script in the scripts section
Test Framework: A test framework must be installed (e.g., Jest, Mocha, Jasmine)
Node.js Image: The specified NODE_IMAGE must be available and contain npm

Caching Dependencies

To speed up pipeline execution, consider caching node_modules:

.npm-test:
  image: $NODE_IMAGE
  before_script:
    - cd $NPM_BUILD_PATH && npm install
  script:
    - cd $NPM_BUILD_PATH && npm test
  cache:
    key: ${CI_COMMIT_REF_SLUG}-npm
    paths:
      - $NPM_BUILD_PATH/node_modules/

Notes

The job installs dependencies fresh each time unless caching is configured
The npm test command runs the test script defined in package.json
You can override the script section to run different test commands (e.g., npm run test:unit)
Test reports should be configured in the artifacts section if you want to view them in GitLab
The job uses Alpine-based Node.js images by default for smaller image size and faster pulls
Consider using npm ci instead of npm install in production pipelines for faster, more reliable builds
The job can be extended with coverage reporting, JUnit XML output, or other test reporters
If tests are in a subdirectory, set NPM_BUILD_PATH to that directory path

Overview​

Variables​

Variable Details​

Usage​

Basic Usage​

Job Details​

Before Script​

Script​

Configuration Examples​

Basic Test Job​

Custom Test Path​

Different Node.js Version​

With Test Reports​

With Coverage Reports​

Multiple Test Jobs​

Complete Pipeline Example​

Package.json Test Script​

Basic Test Script​

With Coverage​

With JUnit Reporter​

Test Report Integration​

JUnit XML Reports​

Coverage Reports​

Prerequisites​

Caching Dependencies​

Notes​