Other CI systems

VisualQ works with any CI system through the REST API. Here are example configurations for popular platforms.

GitLab CI

visual-test:
  stage: test
  image: curlimages/curl:latest
  script:
    - |
      RUN_ID=$(curl -s -X POST https://visualq.ai/api/ci/run \
        -H "Content-Type: application/json" \
        -H "X-API-Key: $VISUALQ_API_KEY" \
        -d "{
          \"project\": \"my-website\",
          \"environment\": \"staging\",
          \"commitSha\": \"$CI_COMMIT_SHA\",
          \"branch\": \"$CI_COMMIT_REF_NAME\",
          \"ciProvider\": \"gitlab-ci\"
        }" | jq -r '.runId')
      
      echo "Run started: $RUN_ID"
      
      while true; do
        STATUS=$(curl -s "https://visualq.ai/api/ci/status/$RUN_ID" \
          -H "X-API-Key: $VISUALQ_API_KEY" | jq -r '.status')
        if [ "$STATUS" != "running" ]; then
          echo "Run finished: $STATUS"
          [ "$STATUS" = "completed" ] || exit 1
          break
        fi
        sleep 5
      done
  only:
    - merge_requests

Jenkins (Declarative Pipeline)

pipeline {
    agent any
    
    environment {
        VISUALQ_API_KEY = credentials('visualq-api-key')
    }
    
    stages {
        stage('Visual Test') {
            steps {
                script {
                    def response = httpRequest(
                        url: 'https://visualq.ai/api/ci/run',
                        httpMode: 'POST',
                        contentType: 'APPLICATION_JSON',
                        customHeaders: [[name: 'X-API-Key', value: env.VISUALQ_API_KEY]],
                        requestBody: """{
                            "project": "my-website",
                            "environment": "staging",
                            "commitSha": "${env.GIT_COMMIT}",
                            "branch": "${env.GIT_BRANCH}",
                            "ciProvider": "jenkins"
                        }"""
                    )
                    def result = readJSON text: response.content
                    echo "Run started: ${result.runId}"
                }
            }
        }
    }
}

CircleCI

version: 2.1

jobs:
  visual-test:
    docker:
      - image: cimg/base:current
    steps:
      - run:
          name: Run VisualQ tests
          command: |
            RUN_RESPONSE=$(curl -s -X POST https://visualq.ai/api/ci/run \
              -H "Content-Type: application/json" \
              -H "X-API-Key: $VISUALQ_API_KEY" \
              -d "{
                \"project\": \"my-website\",
                \"environment\": \"staging\",
                \"commitSha\": \"$CIRCLE_SHA1\",
                \"branch\": \"$CIRCLE_BRANCH\",
                \"prNumber\": \"$CIRCLE_PULL_REQUEST\",
                \"ciProvider\": \"circleci\"
              }")
            
            RUN_ID=$(echo $RUN_RESPONSE | jq -r '.runId')
            echo "Waiting for run $RUN_ID..."
            
            for i in $(seq 1 60); do
              STATUS=$(curl -s "https://visualq.ai/api/ci/status/$RUN_ID" \
                -H "X-API-Key: $VISUALQ_API_KEY" | jq -r '.status')
              [ "$STATUS" != "running" ] && break
              sleep 5
            done
            
            echo "Final status: $STATUS"
            [ "$STATUS" = "completed" ]

workflows:
  test:
    jobs:
      - visual-test

Targeting an environment

Add the environment field to run tests against a specific environment (e.g., staging):

curl -X POST https://visualq.ai/api/ci/run \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $VISUALQ_API_KEY" \
  -d '{
    "project": "my-website",
    "environment": "staging",
    "commitSha": "'$COMMIT_SHA'",
    "ciProvider": "custom"
  }'

The value can be the environment name or slug. See Environments for setup details.

VisualQ CLI

You can also use the VisualQ CLI directly in any CI environment:

npx @visualq/cli run \
  --api-key $VISUALQ_API_KEY \
  --project my-website \
  --environment staging

The CLI auto-detects CI metadata (commit SHA, branch, PR number) for GitHub Actions, GitLab CI, CircleCI, Jenkins, Travis CI, Bitbucket Pipelines, and Azure Pipelines.

General pattern

For any CI system, the integration follows the same pattern:

Store your API key as a secret/credential
POST /api/ci/run with your project slug, CI metadata, and optionally an environment
Poll GET /api/ci/status/[runId] until the status is not running
Fail the pipeline if the status is failed

See the REST API reference for all available parameters.