Skip to content

GitLab CI template for Postman

This project implements a GitLab CI/CD template to run your automated (API) tests with Postman.

Usage

This template can be used both as a CI/CD component or using the legacy include:project syntax.

Use as a CI/CD component

Add the following to your gitlab-ci.yml:

include:
  # 1: include the component
  - component: gitlab.com/to-be-continuous/postman/gitlab-ci-postman@3.5.0
    # 2: set/override component inputs
    inputs:
      # ⚠ this is only an example
      collections: "e2e/*collection.json"
      review-enabled: "true"

Use as a CI/CD template (legacy)

Add the following to your gitlab-ci.yml:

include:
  # 1: include the template
  - project: 'to-be-continuous/postman'
    ref: '3.5.0'
    file: '/templates/gitlab-ci-postman.yml'

variables:
  # 2: set/override template variables
  # ⚠ this is only an example
  POSTMAN_COLLECTIONS: "e2e/*collection.json"
  REVIEW_ENABLED: "true"

postman job

This job starts Postman automated tests.

It uses the following variable:

Input / Variable Description Default value
image / POSTMAN_IMAGE The Docker image used to run Postman CLI. registry.hub.docker.com/postman/newman:latest
collections / POSTMAN_COLLECTIONS The matcher to select Postman collection file(s) to run. postman/*collection.json
extra-args / POSTMAN_EXTRA_ARGS Newman extra run options (to use global variables, an environment or a data source for e.g.) none
review-enabled / REVIEW_ENABLED Set to true to enable Postman tests on review environments (dynamic environments instantiated on development branches) none (disabled)

In addition to a textual report in the console, this job produces the following reports, kept for one day:

Report Format Usage
reports/postman-*.xunit.xml JUnit test report(s) GitLab integration

Postman {{base_url}} auto evaluation

By default, the Postman template auto-evaluates a {{base_url}} variable (i.e. the variable pointing at server under test) by looking either for a $environment_url variable or for an environment_url.txt file.

Therefore if an upstream job in the pipeline deployed your code to a server and propagated the deployed server url, either through a dotenv variable $environment_url or through a basic environment_url.txt file, then the Postman test will automatically be run on this server.

⚠ all our deployment templates implement this design. Therefore even purely dynamic environments (such as review environments) will automatically be propagated to your Postman tests.

Hook scripts

The Postman template supports optional hook scripts from your project, located in the root directory to perform additional project-specific logic:

  • pre-postman.sh is executed before running Postman,
  • post-postman.sh is executed after running Postman (whichever the tests status).