gitlab-ci-test-jobs

Overview

Configured via .gitlab-ci.yml at the repo root. Structure: stages (sequential phases) → jobs (parallel within a stage) → steps (a job's script: array).

When to use

• Project hosts on GitLab (self-hosted or .com).
• Existing .gitlab-ci.yml needs standardization.
• The team values GitLab's tight VCS / CI / registry / artifacts integration.

Step 1 - Basic test job

# .gitlab-ci.yml
stages:
  - test

test:
  stage: test
  image: node:22
  script:
    - npm ci
    - npm test

Default: runs on every push to any branch. Per-branch / per-MR filtering via rules: (Step 7).

Step 2 - Parallel matrix

test:
  stage: test
  image: node:22
  parallel:
    matrix:
      - NODE_VERSION: ['20', '22']
        OS_IMAGE: ['node:20', 'node:22']
  script:
    - npm ci
    - npm test

parallel: matrix: runs the job once per matrix entry. Use GitLab's matrix syntax for cross-product / explicit include for specific combinations.

Step 3 - Services (PostgreSQL, Redis)

test:
  stage: test
  image: node:22
  services:
    - name: postgres:15
      alias: postgres
      variables:
        POSTGRES_PASSWORD: test
    - name: redis:7
      alias: redis
  variables:
    DATABASE_URL: 'postgres://postgres:test@postgres:5432/postgres'
    REDIS_URL: 'redis://redis:6379'
  script:
    - npm ci
    - npm test

The service hostname is the alias field; reachable from the job container.

Step 4 - JUnit + coverage reports

test:
  stage: test
  script:
    - npm ci
    - npm test -- --reporters=default --reporters=jest-junit
  artifacts:
    when: always
    reports:
      junit: junit.xml
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml
    paths:
      - junit.xml
      - coverage/
    expire_in: 30 days
  coverage: '/Lines\s*:\s*([0-9.]+)%/'

GitLab natively renders:

• JUnit XML in the MR's "Test summary."
• Coverage in the MR widget (the coverage: regex parses %).
• Cobertura coverage as inline annotations on diff lines.

Step 5 - Stages + needs

stages:
  - lint
  - test
  - integration
  - e2e

lint:
  stage: lint
  script: npm run lint

unit:
  stage: test
  script: npm test
  needs: [lint]   # don't wait for stage; run as soon as lint passes

integration:
  stage: integration
  script: npm run test:integration
  needs: [unit]

e2e:
  stage: e2e
  script: npm run test:e2e
  needs: [integration]

needs: enables DAG-style pipelines (newer GitLab feature) - jobs run as soon as their dependencies finish, not waiting for the full stage.

Step 6 - Retry policy

test:
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure
      - api_failure

Distinguish retry classes:

• runner_system_failure - runner died; safe to retry.
• script_failure - test failed; don't retry (masks bugs).
• unknown_failure - case by case.

Step 7 - Trigger filtering via rules:

test:
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
      changes:
        - 'src/**/*'
        - 'tests/**/*'
        - 'package.json'
    - if: $CI_COMMIT_BRANCH == 'main'
    - if: $CI_PIPELINE_SOURCE == 'schedule'
  script:
    - npm test

Modern rules: replaces older only: / except: (still work but deprecated for new config).

Step 8 - Caching

test:
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - .npm/
      - node_modules/
  script:
    - npm ci --cache .npm --prefer-offline
    - npm test

cache: per-job; speeds repeat installs. Pin the key to package-lock.json so cache invalidates on dep changes.

Step 9 - Variables + secrets

variables:
  CI: 'true'
  NODE_ENV: 'test'

test:
  script:
    - npm test
  variables:
    # Job-level overrides
    NODE_AUTH_TOKEN: $CI_NPM_TOKEN

Secrets configured in Project Settings → CI/CD → Variables (masked + protected for sensitive values).

Anti-patterns

Anti-pattern	Why it fails	Fix
retry: 5 on test failures	Hides flake; never resolved.	retry: when: only for runner / API failures (Step 6).
Hardcoded credentials in .gitlab-ci.yml	Secrets in repo.	CI/CD Variables (Step 9).
One mega-stage with all jobs	No parallelism; slow pipeline.	Stages + needs (Step 5).
Missing artifact upload on failure	Failure debugging needs results.	when: always (Step 4).
Default image: for everything	Pulls Docker image per job; slow.	Pin lightweight default (e.g., alpine:latest for non-build jobs).

Limitations

• GitLab Runner setup for self-hosted. Initial setup adds ops cost.
• SaaS quota. GitLab.com free tier has minute caps; private projects have stricter limits.
• Per-job overhead. Each job pulls images + clones repo; short-lived jobs are inefficient.
• YAML complexity grows. Large pipelines benefit from include: to split across files.

References

• GitLab CI/CD docs at docs.gitlab.com/ee/ci/.
• github-actions-test-jobs, jenkinsfile-test-stages - alternatives.
• ci-test-job-conventions - cross-CI conventions; CircleCI patterns live in its references/circleci.md.
• junit-xml-analysis - JUnit XML parser.
• lcov-analysis - Cobertura parser (GitLab's native coverage format).