GitLab CI Test Pipeline Example: A Reusable YAML Workflow for Automated QA
GitLab CIpipeline templatesautomated QAtest reportsDevOps workflows

GitLab CI Test Pipeline Example: A Reusable YAML Workflow for Automated QA

TTester.live Editorial Team
2026-11-04
7 min read

Build a reusable GitLab CI test pipeline with unit, API, end-to-end, smoke tests, reports, artifacts, and protected deployments.

This GitLab CI test pipeline example gives you a practical starting point for automated QA: separate unit, API, and end-to-end checks into clear stages, preserve reports and failure evidence, and protect deployments with a final smoke test. The YAML is intentionally modular so you can begin with a small suite and expand it without turning the pipeline into an opaque collection of scripts.

Overview

A useful CI/CD testing workflow should answer three questions quickly: did the change build, does it behave correctly, and is it safe to release? Those questions usually map to different test types and different levels of execution cost.

  • Unit tests validate small pieces of application logic and should normally run first.
  • API or integration tests check service boundaries, persistence, authentication, and important workflows without requiring a full browser.
  • End-to-end tests exercise the application through a browser or client in a way that resembles user behavior.
  • Smoke tests provide a short post-deployment check for the most important production-like paths.

Separating these checks makes failures easier to interpret. A failed unit job usually points to application logic or a local dependency. A failed API job may indicate a contract, database, or service configuration problem. A failed browser job may involve the application, test data, timing, or the browser environment.

The example below assumes a repository with scripts named test:unit, test:api, test:e2e, and test:smoke. Adapt those commands to your framework. Playwright, Cypress, a custom HTTP client, or another test automation tool can fit the same pipeline shape.

Template structure

Save the following as .gitlab-ci.yml. It uses stages for ordering, artifacts for reports and screenshots, and a protected deployment job that runs only from the default branch. The deployment command is a placeholder: replace it with the command used by your environment.

stages:
  - install
  - unit
  - api
  - e2e
  - deploy
  - smoke

variables:
  NODE_ENV: test
  npm_config_cache: "$CI_PROJECT_DIR/.npm"

cache:
  key:
    files:
      - package-lock.json
  paths:
    - .npm/
    - node_modules/

.default-node:
  image: node:20
  before_script:
    - npm ci

install:
  extends: .default-node
  stage: install
  script:
    - npm run build
  artifacts:
    expire_in: 1 week
    paths:
      - dist/

unit_tests:
  extends: .default-node
  stage: unit
  script:
    - npm run test:unit -- --ci
  artifacts:
    when: always
    expire_in: 1 week
    reports:
      junit: reports/unit-junit.xml
    paths:
      - reports/

api_tests:
  extends: .default-node
  stage: api
  services:
    - name: postgres:16
      alias: db
  variables:
    DATABASE_URL: postgresql://postgres:postgres@db:5432/app_test
  script:
    - npm run db:migrate:test
    - npm run test:api
  artifacts:
    when: always
    expire_in: 1 week
    reports:
      junit: reports/api-junit.xml
    paths:
      - reports/

end_to_end_tests:
  extends: .default-node
  stage: e2e
  script:
    - npm run start:test &
    - npm run wait-for-app
    - npm run test:e2e
  artifacts:
    when: always
    expire_in: 1 week
    reports:
      junit: reports/e2e-junit.xml
    paths:
      - reports/
      - test-results/
      - playwright-report/

 deploy:
  stage: deploy
  image: alpine:latest
  script:
    - ./scripts/deploy.sh "$CI_COMMIT_SHA"
  environment:
    name: staging
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
      when: manual

smoke_tests:
  extends: .default-node
  stage: smoke
  variables:
    BASE_URL: $STAGING_BASE_URL
  script:
    - npm run test:smoke
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  artifacts:
    when: always
    expire_in: 1 week
    paths:
      - reports/
      - test-results/

GitLab runs stages in sequence by default, while jobs within the same stage can run in parallel when runners are available. That makes unit tests, API tests, and browser tests independent at the stage level, while still preventing later checks from running after an earlier stage has failed.

The artifacts:reports:junit entries assume your test runner creates JUnit XML files at those paths. If your framework uses another format, keep the raw files under artifacts:paths or add a reporting conversion step. Screenshots, videos, traces, and browser reports should generally be collected with when: always so a failure leaves evidence behind.

How to customize

Match the commands to your repository

Replace every example script with a command that works locally and in a clean checkout. A good first check is to run the exact CI commands inside the same container image used by the runner. This reduces differences caused by Node versions, missing system packages, or untracked local files.

If your repository is not a Node project, replace the image, dependency installation, cache paths, and commands. The important design is the separation of responsibilities, not the language or framework.

Control test data explicitly

API and end-to-end tests should create or reset predictable data rather than relying on records left by a previous job. Use dedicated test databases, seed scripts, disposable environments, or isolated tenants where appropriate. Never place production credentials or real customer data in test fixtures. For additional guidance, see Test Data Management for Automated QA.

Choose the right deployment gate

The sample deployment is manual and limited to the default branch. That is a conservative starting point: a reviewer can inspect unit, API, and end-to-end results before promoting the build. Teams that deploy automatically may change when: manual to when: on_success, but should first define rollback and environment ownership.

Use GitLab protected environments and protected variables for deployment credentials. Keep secrets out of YAML, logs, test output, and command-line arguments where possible. A pipeline should prove that a build is ready; it should not expose the credentials used to release it.

Make browser jobs diagnosable

For Playwright or another browser framework, install the required browsers and system dependencies in the image or in a setup step. Save screenshots, traces, videos, and HTML reports only when needed if storage is limited, but always preserve enough evidence to explain a failure. If the suite grows, consider parallel test execution by splitting files across jobs and combining reports afterward.

For framework selection and browser coverage decisions, the Cypress vs Playwright comparison and hosted versus self-hosted test infrastructure guide provide useful context.

Examples

A faster merge-request pipeline

Not every check needs to run for every branch. A common approach is to run unit and API tests on every merge request, then run the full browser suite for changes that affect the UI, authentication, or critical workflows. Use GitLab rules carefully and document exceptions so skipped tests do not become invisible gaps.

For example, you could add rules to the end-to-end job that run it for merge requests and the default branch, while allowing a scheduled pipeline to run the complete cross-browser suite. This keeps everyday feedback practical without abandoning broader regression testing.

A parallel browser matrix

When one end-to-end job becomes slow, define several jobs with different variables such as BROWSER=chromium, BROWSER=firefox, or a test shard number. Each job should publish artifacts to a distinct path or use a report-merging step. Start with a small matrix and expand it based on supported browsers and real failure patterns rather than running every combination by default.

A controlled smoke test

A smoke suite should be short and stable. It might open the application, authenticate a test account, load a key page, create a minimal record, and verify one critical API response. It should not duplicate the entire regression suite. If smoke tests fail after deployment, stop promotion or trigger the documented rollback path instead of retrying indefinitely.

When a job fails intermittently, do not hide the problem with unlimited retries. Capture the failure, identify whether the cause is timing, shared state, infrastructure, or a product defect, and track the fix. The flaky test troubleshooting guide and test suite health guide cover practical ways to monitor noise and duration.

When to update

Revisit this GitLab CI test pipeline whenever the application, delivery process, or test inputs change. At minimum, review it when you:

  • change the runtime, package manager, browser version, or base container image;
  • add a service dependency such as a database, queue, or external API;
  • introduce a new deployment environment or change promotion rules;
  • add a critical user journey that is not covered by unit, API, or smoke tests;
  • notice rising queue time, job duration, artifact storage, or flaky failures;
  • change test-report formats or the location of screenshots and traces.

Keep the pipeline maintainable by reviewing it alongside application changes rather than treating it as permanent infrastructure. Start with the template, verify each command locally, add one test layer at a time, and record why a job exists. Before enabling automatic production promotion, use the CI/CD testing checklist to confirm that failures, test data, reports, secrets, and rollback behavior are understood.

The most reliable CI/CD testing setup is not the one with the most jobs. It is the one that gives developers trustworthy feedback, preserves useful evidence, and makes the next action clear when something fails.

Related Topics

#GitLab CI#pipeline templates#automated QA#test reports#DevOps workflows
T

Tester.live Editorial Team

Technical Editors

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.