GitLab CI Test

Testing GitLab CI pipelines using gitlab-ci-local.

Warning

This project will use your docker socket to run the pipeline. Using this tool on untrusted pipelines will lead to arbitrary code execution.

Prerequisites

• Docker
• Node.js
• npm install -g gitlab-ci-test

Setup

• Create a folder for your test project
• In the folder, create a .gitlab-ci.yml file with the pipeline
• If you want to test a template, it should be stored as templates/*.yml in your current working directory and referenced in the pipeline:

1include:
2  - local: templates/template.yml

Usage

Javascript file

• Create a js file describing your test:

1// gitlab-ci-test and chai are imported globally
2it("My project pipeline is successful", async () => {
3  const jobs = await runPipeline("project-path", {
4    variables: {
5      KEY: "value",
6    },
7  })
8
9  assert.ok(isSuccess(jobs))
10})

• Run gitlab-ci-test <test-file.js>

See test/example.test.js for a complete example.

Yaml file

• Create a yaml file describing your test:

1# test definition
2description: My project pipeline is successful
3project: project-path
4asserts:
5  - test: "success"
6---
7# template variables
8KEY: VALUE

• In the template project root, run gitlab-ci-test <test-file.yml>

Result object

The context used for assertions has the following structure:

1{
2  success: boolean, // true if the pipeline succeeded
3  run_jobs: ["node-build"], // list of jobs that ran
4  jobs: { // list of all jobs in the pipeline
5    "node-build": {
6      stdout: "line\nline", // stdout of the job
7      stderr: "line\nline", // stderr of the job
8      artifacts: {
9        exists: (path) => boolean, // check if an artifact exists
10      },
11      // many other properties provided by gitlab-ci-local
12    },
13    // ...
14  }
15}

See all yaml files in test folder for a complete example.