Documentation

GitLab CI/CD

Learn how to run Verex AI test suites using GitLab CI/CD.

Overview

Verex integrates with GitLab CI/CD to help you automatically run test suites as part of your CI/CD workflows. This integration makes it easy to trigger tests, wait for completion, and surface results directly in your pipeline.

View GitLab Repository

Features

  • Run Verex test suites from any GitLab CI/CD pipeline
  • Automatic polling and real-time test monitoring
  • Output test result summaries and metadata
  • Pass dynamic URLs to target specific environments
  • Debug mode for troubleshooting

Quick Start

1. Add to Your GitLab CI/CD Pipeline

include:
  - project: 'verex-ai/gitlab-test-runner'
    ref: main
    file: '/verex-test-runner.yml'
 
verex-test-job:
  extends: .verex-test-runner
  variables:
    VEREX_API_KEY: $VEREX_API_KEY
    VEREX_TEST_SUITE: 'suite_abc123456'

2. Set Up Your API Key

  • Create your API Key in the Verex Dashboard under Settings > API Keys
  • Add it to your GitLab project's CI/CD variables as VEREX_API_KEY

Complete Example

stages:
  - deploy
  - test
  - report
 
include:
  - project: 'verex-ai/gitlab-test-runner'
    ref: main
    file: '/verex-test-runner.yml'
 
deploy-staging:
  stage: deploy
  script:
    - echo "Deploying to staging environment..."
  environment:
    name: staging
    url: https://staging.yourdomain.com
 
verex-test-job:
  extends: .verex-test-runner
  stage: test
  variables:
    VEREX_API_KEY: $VEREX_API_KEY
    VEREX_TEST_SUITE: 'suite_abc123456'
    VEREX_TEST_BASE_URL: 'https://staging.yourdomain.com'
    VEREX_DEBUG: 'true'
  needs:
    - deploy-staging
 
report-results:
  stage: report
  script:
    - echo "Test Suite Run Status: $VEREX_TEST_SUITE_RUN_STATUS"
    - echo "Total Tests: $VEREX_TOTAL_TESTS"
    - echo "Passed Tests: $VEREX_PASSED_TESTS"
    - echo "Failed Tests: $VEREX_FAILED_TESTS"
  needs:
    - verex-test-job

Dynamic Base URL

To run tests against a dynamic environment (e.g. your current deploy preview), you can pass a custom base URL:

VEREX_TEST_BASE_URL: $CI_ENVIRONMENT_URL

This value replaces any {{base_url}} placeholder used in your Verex test suite.

Variables

NameDescriptionRequiredDefault
VEREX_API_KEYAPI key for authenticationYes
VEREX_TEST_SUITETest suite ID to executeYes
VEREX_TEST_BASE_URLBase URL for the tests (e.g. https://staging.yourdomain.com)No
VEREX_API_BASE_URLBase URL for the APINohttps://verex.ai/api
VEREX_MAX_POLL_ATTEMPTSMaximum number of polling attemptsNo60
VEREX_POLL_INTERVAL_SECONDSSeconds to wait between polling attemptsNo10
VEREX_DEBUGEnable debug modeNofalse

Output Variables

NameDescription
VEREX_TEST_SUITE_RUN_IDID of the test suite run
VEREX_TEST_SUITE_RUN_STATUSStatus of the test suite run
VEREX_TEST_SUITE_LINKLink to the test suite
VEREX_TEST_SUITE_RUN_LINKLink to the test suite run
VEREX_TOTAL_TESTSTotal number of tests executed
VEREX_PASSED_TESTSNumber of tests that passed
VEREX_FAILED_TESTSNumber of tests that failed
VEREX_TEST_DURATIONTotal duration of the test run in seconds

Requirements

  • A Verex account
  • A valid API Key with permissions to run test suites
  • GitLab CI/CD runner with Node.js support

Troubleshooting

Enable VEREX_DEBUG: 'true' to view detailed logs in case of:

  • Invalid API keys
  • Test suite not found
  • Timeout issues
  • Connectivity problems

Resources

Need help? Contact Support

On this page