Environment Variables

Configure curl-runner behavior using environment variables for consistent settings across different environments.

Copy Markdown

Overview

Environment variables provide a way to configure curl-runner without modifying YAML files or using command-line options. This is particularly useful for CI/CD pipelines, containerized environments, and maintaining consistent settings across teams.

Configuration Precedence

Settings are applied in the following order (later overrides earlier):

  1. Default values
  2. Configuration file (curl-runner.yaml)
  3. Environment variables
  4. Command-line options

Basic Usage

Set environment variables in your shell or include them inline when running commands.

Environment Variable Examples
# Set verbose output
export CURL_RUNNER_VERBOSE=true
curl-runner tests/

# Set parallel execution
export CURL_RUNNER_EXECUTION=parallel
curl-runner api-tests.yaml

# Set multiple variables
export CURL_RUNNER_VERBOSE=true
export CURL_RUNNER_EXECUTION=parallel
export CURL_RUNNER_CONTINUE_ON_ERROR=true
curl-runner tests/

# Inline environment variables (one-time use)
CURL_RUNNER_VERBOSE=true curl-runner tests/

Available Variables

All curl-runner environment variables follow the CURL_RUNNER_* naming convention.

CURL_RUNNER_VERBOSE
booleandefault: false

Enable verbose output with detailed request/response information

export CURL_RUNNER_VERBOSE=true
CURL_RUNNER_EXECUTION
stringdefault: sequential

Set execution mode: sequential or parallel

export CURL_RUNNER_EXECUTION=parallel
CURL_RUNNER_CONTINUE_ON_ERROR
booleandefault: false

Continue execution when individual requests fail

export CURL_RUNNER_CONTINUE_ON_ERROR=true
CURL_RUNNER_OUTPUT_FORMAT
stringdefault: pretty

Set output format: json, pretty, or raw

export CURL_RUNNER_OUTPUT_FORMAT=json
CURL_RUNNER_PRETTY_LEVEL
stringdefault: minimal

Set pretty format detail level: minimal, standard, or detailed

export CURL_RUNNER_PRETTY_LEVEL=detailed
CURL_RUNNER_OUTPUT_FILE
stringdefault: undefined

Save execution results to specified file

export CURL_RUNNER_OUTPUT_FILE=results.json
CURL_RUNNER_TIMEOUT
numberdefault: undefined

Set global timeout for all requests in milliseconds

export CURL_RUNNER_TIMEOUT=10000
CURL_RUNNER_RETRIES
numberdefault: 0

Set maximum number of retries for failed requests

export CURL_RUNNER_RETRIES=3
CURL_RUNNER_RETRY_DELAY
numberdefault: 1000

Set delay between retry attempts in milliseconds

export CURL_RUNNER_RETRY_DELAY=2000

Output Configuration

Control how results are displayed and saved using output-related environment variables.

Output Configuration
# Set output format
export CURL_RUNNER_OUTPUT_FORMAT=json
curl-runner tests/

# Set pretty level for detailed output
export CURL_RUNNER_OUTPUT_FORMAT=pretty
export CURL_RUNNER_PRETTY_LEVEL=detailed
curl-runner tests/

# Save output to file
export CURL_RUNNER_OUTPUT_FILE=results.json
curl-runner tests/

# Enable verbose logging
export CURL_RUNNER_VERBOSE=true
curl-runner tests/

Request Configuration

Configure default request behavior including timeouts and retry logic.

Request Configuration
# Set global timeout (milliseconds)
export CURL_RUNNER_TIMEOUT=10000
curl-runner tests/

# Configure retry behavior
export CURL_RUNNER_RETRIES=3
export CURL_RUNNER_RETRY_DELAY=2000
curl-runner tests/

# Disable retries
export CURL_RUNNER_RETRIES=0
curl-runner tests/

Execution Configuration

Control how requests are executed and how errors are handled.

Execution Configuration
# Set execution mode
export CURL_RUNNER_EXECUTION=parallel
curl-runner tests/

# Continue on errors
export CURL_RUNNER_CONTINUE_ON_ERROR=true
curl-runner tests/

# Combine execution settings
export CURL_RUNNER_EXECUTION=parallel
export CURL_RUNNER_CONTINUE_ON_ERROR=true
curl-runner tests/

Docker & Containers

Environment variables are ideal for containerized deployments where configuration should be injected at runtime.

Docker Example
# Dockerfile example
FROM node:20-alpine
ENV CURL_RUNNER_VERBOSE=false
ENV CURL_RUNNER_OUTPUT_FORMAT=json
ENV CURL_RUNNER_EXECUTION=sequential
WORKDIR /app
RUN npm install -g curl-runner
CMD ["curl-runner", "/tests"]

CI/CD Integration

Examples of using environment variables in popular CI/CD platforms.

CI/CD Examples
# GitHub Actions
- name: Run API Tests
  env:
    CURL_RUNNER_VERBOSE: true
    CURL_RUNNER_OUTPUT_FORMAT: json
    CURL_RUNNER_CONTINUE_ON_ERROR: true
  run: curl-runner tests/

# GitLab CI
test:
  variables:
    CURL_RUNNER_EXECUTION: parallel
    CURL_RUNNER_TIMEOUT: "30000"
  script:
    - curl-runner api-tests.yaml

# Jenkins Pipeline
pipeline {
  environment {
    CURL_RUNNER_VERBOSE = 'true'
    CURL_RUNNER_OUTPUT_FILE = 'test-results.json'
  }
  stages {
    stage('Test') {
      steps {
        sh 'curl-runner tests/'
      }
    }
  }
}

Best Practices

Use for Environment-Specific Settings

Environment variables are perfect for settings that change between development, staging, and production environments.

Keep Secrets Secure

While curl-runner doesn't directly handle secrets, avoid logging verbose output in production when sensitive data might be exposed.

Document Your Variables

Create a .env.example file in your project to document required environment variables for your team.

Prefer Explicit Over Implicit

For critical settings like timeouts and retries, consider using explicit command-line options for clarity in scripts and CI pipelines.