Configuration Reference

Complete guide for configuring socialseed-e2e framework.

Overview

socialseed-e2e uses a YAML-based configuration file (e2e.conf) to define test environments, services, and execution parameters. The configuration supports environment variable substitution, multiple profiles, and flexible service definitions.

Configuration File Location

The framework searches for configuration files in the following order:

Environment variable: E2E_CONFIG_PATH
Current directory: ./e2e.conf
Config subdirectory: ./config/e2e.conf
Tests subdirectory: ./tests/e2e.conf
Global config: ~/.config/socialseed-e2e/default.conf

Creating a Configuration File

# Initialize with default configuration
e2e init

# Or create manually in a specific location
e2e init /path/to/project

Configuration Structure

general:
  # General settings

services:
  # Service definitions

api_gateway:
  # API Gateway configuration

databases:
  # Database connections

test_data:
  # Test data generation settings

security:
  # Security and SSL configuration

reporting:
  # Test reporting options

General Section

The general section defines global settings for the test execution.

Options

Option	Type	Default	Description
`environment`	string	`dev`	Execution environment (dev, staging, production)
`timeout`	integer	`30000`	Global timeout for HTTP requests in milliseconds
`user_agent`	string	`SocialSeed-E2E-Agent/2.0`	User agent string for HTTP requests
`verbose`	boolean	`true`	Enable verbose logging
`project.name`	string	`SocialSeed`	Project name
`project.version`	string	`0.0.0`	Project version
`verification_level`	string	`strict`	Validation strictness (strict, lenient)

Example

general:
  environment: staging
  timeout: 45000
  user_agent: "MyApp-E2E-Tests/1.0"
  verbose: true
  project:
    name: "MyApplication"
    version: "1.2.0"

Services Configuration

The services section defines all microservices to be tested. Each service has its own configuration block.

Service Options

Option	Type	Default	Description
`base_url`	string	(required)	Base URL for the service
`health_endpoint`	string	`/actuator/health`	Health check endpoint
`port`	integer	`8080`	Service port
`maven_module`	string	`services/{name}`	Maven module path
`timeout`	integer	`30000`	Request timeout (overrides global)
`headers`	dictionary	`{}`	Default headers for requests
`auto_start`	boolean	`true`	Auto-start service before tests
`required`	boolean	`true`	Service is required for tests
`endpoints`	dictionary	`{}`	Named endpoint definitions

Example: Single Service

services:
  users-api:
    base_url: "http://localhost:8080"
    health_endpoint: "/health"
    port: 8080
    timeout: 30000
    headers:
      Content-Type: "application/json"
    auto_start: true
    required: true
    endpoints:
      login: "/api/v1/auth/login"
      register: "/api/v1/auth/register"
      profile: "/api/v1/users/profile"

Example: Multiple Services

services:
  auth-service:
    base_url: "http://localhost:8081"
    health_endpoint: "/health"
    port: 8081
    required: true
    endpoints:
      login: "/auth/login"
      logout: "/auth/logout"
      refresh: "/auth/refresh"

  users-service:
    base_url: "http://localhost:8082"
    health_endpoint: "/health"
    port: 8082
    required: true
    endpoints:
      list: "/users"
      detail: "/users/{id}"
      create: "/users"
      update: "/users/{id}"

  posts-service:
    base_url: "http://localhost:8083"
    port: 8083
    required: false
    auto_start: false
    endpoints:
      feed: "/posts/feed"
      create: "/posts"

Environment Variables

socialseed-e2e supports environment variable substitution using the syntax ${VAR_NAME} or ${VAR_NAME:-default_value}.

Basic Substitution

general:
  environment: ${ENVIRONMENT}
  timeout: ${TIMEOUT}

services:
  api:
    base_url: ${API_BASE_URL}

Default Values

general:
  environment: ${ENVIRONMENT:-dev}
  timeout: ${TIMEOUT:-30000}
  verbose: ${VERBOSE:-true}

services:
  api:
    base_url: ${API_BASE_URL:-http://localhost:8080}

Common Environment Variables

Variable	Description	Example
`E2E_CONFIG_PATH`	Path to configuration file	`/path/to/e2e.conf`
`ENVIRONMENT`	Execution environment	`staging`, `production`
`API_BASE_URL`	Base URL for services	`http://api.example.com`
`TIMEOUT`	Request timeout in ms	`30000`
`VERBOSE`	Enable verbose logging	`true`, `false`

Setting Environment Variables

Linux/Mac:

export ENVIRONMENT=staging
export API_BASE_URL=https://api.staging.example.com
export TIMEOUT=45000
e2e run

Windows (PowerShell):

$env:ENVIRONMENT = "staging"
$env:API_BASE_URL = "https://api.staging.example.com"
e2e run

Windows (CMD):

set ENVIRONMENT=staging
set API_BASE_URL=https://api.staging.example.com
e2e run

API Gateway Setup

Configure an API Gateway to route requests through a single entry point.

Configuration Options

Option	Type	Default	Description
`enabled`	boolean	`false`	Enable API Gateway
`url`	string	`""`	Gateway base URL
`prefix`	string	`""`	URL prefix for services
`auth.type`	string	`none`	Authentication type (none, bearer, api_key)
`auth.bearer_token`	string	`null`	Bearer token for authentication
`auth.api_key_header`	string	`null`	API key header name
`auth.api_key_value`	string	`null`	API key value

Example: Simple Gateway

api_gateway:
  enabled: true
  url: "http://gateway.example.com"
  prefix: "/api/v1"

Example: Gateway with Authentication

api_gateway:
  enabled: true
  url: "${GATEWAY_URL}"
  prefix: "/api"
  auth:
    type: bearer
    bearer_token: "${GATEWAY_TOKEN}"

services:
  users:
    base_url: "http://localhost:8080"  # Used as fallback if gateway fails
    required: true

Example: Gateway with API Key

api_gateway:
  enabled: true
  url: "https://api.example.com"
  prefix: "/v2"
  auth:
    type: api_key
    api_key_header: "X-API-Key"
    api_key_value: "${API_KEY}"

Service URL Resolution

When API Gateway is enabled, service URLs are resolved as:

{gateway_url}{prefix}/{service_name}

Example:

Gateway URL: http://gateway.example.com
Prefix: /api/v1
Service: users
Final URL: http://gateway.example.com/api/v1/users

Database Configuration

Configure database connections for test data validation and setup.

Configuration Options

Option	Type	Default	Description
`host`	string	`localhost`	Database host
`port`	integer	`5432`	Database port
`database`	string	`""`	Database name
`username`	string	`""`	Username
`password`	string	`""`	Password
`enabled`	boolean	`false`	Enable database connection

Example: PostgreSQL

databases:
  primary:
    host: "localhost"
    port: 5432
    database: "socialseed_test"
    username: "${DB_USER:-testuser}"
    password: "${DB_PASSWORD:-testpass}"
    enabled: true

  analytics:
    host: "${ANALYTICS_DB_HOST:-localhost}"
    port: 5432
    database: "analytics_test"
    username: "${ANALYTICS_DB_USER}"
    password: "${ANALYTICS_DB_PASSWORD}"
    enabled: ${ANALYTICS_ENABLED:-false}

Test Data Configuration

Configure default values for test data generation.

Configuration Options

Option	Type	Default	Description
`user.email_domain`	string	`test.socialseed.com`	Domain for test emails
`user.password`	string	`StrongPass123!`	Default test password
`user.username_prefix`	string	`testuser`	Prefix for test usernames
`timing.step_delay`	integer	`100`	Delay between test steps (ms)
`timing.async_timeout`	integer	`10000`	Timeout for async operations
`retries.max_attempts`	integer	`3`	Maximum retry attempts
`retries.backoff_ms`	integer	`1000`	Backoff time between retries

Example

test_data:
  user:
    email_domain: "test.myapp.com"
    password: "TestPass123!"
    username_prefix: "e2euser"

  timing:
    step_delay: 200
    async_timeout: 15000

  retries:
    max_attempts: 5
    backoff_ms: 2000

Security Configuration

Configure SSL/TLS and authentication settings.

Configuration Options

Option	Type	Default	Description
`verify_ssl`	boolean	`true`	Verify SSL certificates
`ssl_cert`	string	`null`	Path to SSL certificate
`ssl_key`	string	`null`	Path to SSL private key
`ssl_ca`	string	`null`	Path to CA certificate
`test_tokens`	dictionary	`{}`	Pre-defined test tokens

Example

security:
  verify_ssl: true
  ssl_cert: "/path/to/cert.pem"
  ssl_key: "/path/to/key.pem"
  ssl_ca: "/path/to/ca.pem"
  test_tokens:
    admin: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    user: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Disable SSL Verification (Development Only)

security:
  verify_ssl: false

⚠️ Warning: Only disable SSL verification in development environments.

Reporting Configuration

Configure test reporting and logging options.

Configuration Options

Option	Type	Default	Description
`format`	string	`console`	Report format (console, json, html, junit)
`save_logs`	boolean	`true`	Save logs to file
`log_dir`	string	`./logs`	Directory for log files
`include_payloads`	boolean	`false`	Include request/response payloads
`screenshot_on_failure`	boolean	`false`	Capture screenshots on failure

Example

reporting:
  format: "json"
  save_logs: true
  log_dir: "./test-logs"
  include_payloads: true
  screenshot_on_failure: true

Configuration Examples

Example 1: Development Environment

# e2e.conf - Development Configuration
general:
  environment: dev
  timeout: 30000
  user_agent: "MyApp-E2E/dev"
  verbose: true
  project:
    name: "MyApplication"
    version: "1.0.0"

services:
  api:
    base_url: "http://localhost:8080"
    health_endpoint: "/health"
    port: 8080
    auto_start: true
    required: true
    endpoints:
      health: "/health"
      users: "/api/users"
      posts: "/api/posts"

test_data:
  user:
    email_domain: "test.local"
    password: "devpassword123"

Example 2: Staging Environment

# e2e.conf - Staging Configuration
general:
  environment: staging
  timeout: 45000
  user_agent: "MyApp-E2E/staging"
  verbose: false
  project:
    name: "MyApplication"
    version: "1.2.0-staging"

api_gateway:
  enabled: true
  url: "${STAGING_GATEWAY_URL}"
  prefix: "/api/v1"
  auth:
    type: bearer
    bearer_token: "${STAGING_TOKEN}"

services:
  auth-service:
    base_url: "${AUTH_SERVICE_URL:-http://localhost:8081}"
    port: 8081
    required: true
    endpoints:
      login: "/auth/login"
      verify: "/auth/verify"

  users-service:
    base_url: "${USERS_SERVICE_URL:-http://localhost:8082}"
    port: 8082
    required: true
    endpoints:
      list: "/users"
      profile: "/users/me"

  posts-service:
    base_url: "${POSTS_SERVICE_URL:-http://localhost:8083}"
    port: 8083
    required: false
    auto_start: false

reporting:
  format: "json"
  save_logs: true
  log_dir: "./staging-logs"
  include_payloads: true

Example 3: Production Environment

# e2e.conf - Production (Smoke Tests)
general:
  environment: production
  timeout: 60000
  user_agent: "MyApp-E2E/prod"
  verbose: false
  verification_level: strict

api_gateway:
  enabled: true
  url: "${PROD_GATEWAY_URL}"
  prefix: "/api/v2"
  auth:
    type: api_key
    api_key_header: "X-API-Key"
    api_key_value: "${PROD_API_KEY}"

services:
  api:
    base_url: "${PROD_API_URL}"
    timeout: 60000
    required: true
    auto_start: false
    endpoints:
      health: "/health"
      readiness: "/ready"

security:
  verify_ssl: true
  ssl_ca: "/etc/ssl/certs/ca-bundle.crt"

reporting:
  format: "junit"
  save_logs: true
  log_dir: "/var/log/e2e-tests"
  include_payloads: false

Example 4: Multi-Database Setup

# e2e.conf - Multi-Database Configuration
general:
  environment: dev
  timeout: 30000

databases:
  primary:
    host: "localhost"
    port: 5432
    database: "app_test"
    username: "${DB_USER:-postgres}"
    password: "${DB_PASSWORD:-postgres}"
    enabled: true

  cache:
    host: "localhost"
    port: 6379
    database: "0"
    username: ""
    password: ""
    enabled: true

  analytics:
    host: "${ANALYTICS_HOST:-localhost}"
    port: 5432
    database: "analytics_test"
    username: "${ANALYTICS_USER}"
    password: "${ANALYTICS_PASSWORD}"
    enabled: ${ANALYTICS_ENABLED:-false}

Example 5: Microservices with Service Discovery

# e2e.conf - Microservices Architecture
general:
  environment: staging
  timeout: 30000

services:
  gateway:
    base_url: "${GATEWAY_URL:-http://localhost:8080}"
    port: 8080
    required: true
    endpoints:
      health: "/actuator/health"
      routes: "/actuator/gateway/routes"

  auth-service:
    base_url: "${AUTH_URL:-http://localhost:8081}"
    port: 8081
    required: true
    endpoints:
      login: "/api/auth/login"
      register: "/api/auth/register"
      oauth: "/api/auth/oauth"

  user-service:
    base_url: "${USER_URL:-http://localhost:8082}"
    port: 8082
    required: true
    endpoints:
      profile: "/api/users/profile"
      settings: "/api/users/settings"
      search: "/api/users/search"

  notification-service:
    base_url: "${NOTIFICATION_URL:-http://localhost:8083}"
    port: 8083
    required: false
    auto_start: false
    endpoints:
      send: "/api/notifications/send"
      history: "/api/notifications/history"

test_data:
  user:
    email_domain: "test.staging.example.com"
    password: "StagingPass123!"
    username_prefix: "staginguser"
  timing:
    step_delay: 150

Advanced Features

Configuration Validation

The framework validates configuration on load and provides helpful error messages:

from socialseed_e2e import ApiConfigLoader, ConfigError

try:
    config = ApiConfigLoader.load()
except ConfigError as e:
    print(f"Configuration error: {e}")
except FileNotFoundError as e:
    print(f"Configuration file not found: {e}")

Hot Reloading

Reload configuration without restarting:

from socialseed_e2e import ApiConfigLoader

# Initial load
config = ApiConfigLoader.load()

# ... modify e2e.conf file ...

# Reload configuration
config = ApiConfigLoader.reload()

Strict Validation

Enable strict validation for additional warnings:

from socialseed_e2e import ApiConfigLoader

# Load with strict validation
data = {"general": {"environment": "custom"}}
ApiConfigLoader.validate_config(data, strict=True)

Custom Configuration Path

Load configuration from a specific path:

from socialseed_e2e import ApiConfigLoader

# Load specific configuration file
config = ApiConfigLoader.load("/path/to/custom/e2e.conf")

Or using environment variable:

export E2E_CONFIG_PATH=/path/to/custom/e2e.conf
e2e run

Programmatic Configuration Access

from socialseed_e2e import get_config, get_service_config, get_service_url

# Get full configuration
config = get_config()

# Get specific service configuration
auth_config = get_service_config("auth-service")
print(f"Auth service URL: {auth_config.base_url}")

# Get effective URL (with API Gateway support)
url = get_service_url("users-service")
print(f"Users service URL: {url}")

# Check configuration values
if config.verbose:
    print(f"Environment: {config.environment}")
    print(f"Timeout: {config.timeout}ms")

Service Discovery Helpers

from socialseed_e2e import ApiConfigLoader

# Get all required services
required = ApiConfigLoader.get_all_required_services()
print(f"Required services: {required}")

# Get auto-start services
auto_start = ApiConfigLoader.get_auto_start_services()
print(f"Auto-start services: {auto_start}")

# Find service by Maven module
service = ApiConfigLoader.get_service_by_maven_module("services/auth")
if service:
    print(f"Found service: {service.name}")

Environment Variable Precedence

When using ${VAR:-default} syntax, the resolution order is:

Environment variable value
Default value from syntax
Framework default (if applicable)

Example:

general:
  timeout: ${TIMEOUT:-30000}  # Uses TIMEOUT env var, or 30000 if not set

Multiple Configuration Profiles

You can maintain multiple configuration files for different environments:

project/
├── e2e.conf              # Default (development)
├── e2e.staging.conf      # Staging
├── e2e.production.conf   # Production
└── config/
    └── e2e.ci.conf       # CI/CD

Switching profiles:

# Development (default)
e2e run

# Staging
export E2E_CONFIG_PATH=./e2e.staging.conf
e2e run

# Production
export E2E_CONFIG_PATH=./e2e.production.conf
e2e run

Configuration with Secrets

For sensitive data, use environment variables or external secret management:

# e2e.conf
api_gateway:
  auth:
    type: bearer
    bearer_token: "${GATEWAY_TOKEN}"  # Never hardcode tokens!

databases:
  production:
    password: "${DB_PASSWORD}"  # Use env var for passwords

Best practices:

Never commit secrets to version control
Use .env files with python-dotenv for local development
Use secret management in CI/CD (GitHub Secrets, etc.)
Rotate tokens regularly

Troubleshooting

Configuration Not Found

Error: FileNotFoundError: Could not find configuration file

Solutions:

Run e2e init to create default configuration
Check that e2e.conf exists in one of the search locations
Set E2E_CONFIG_PATH environment variable
Verify file permissions

Invalid Configuration

Error: ConfigError: Configuration validation failed

Common issues:

Missing required general section
Service missing base_url
Invalid port number (must be 1-65535)
Invalid timeout value (must be positive integer)

Environment Variables Not Substituting

Check:

Variable syntax: Use ${VAR} or ${VAR:-default}
Variable is set: echo $VAR_NAME
No spaces in syntax: ${VAR} not ${ VAR }
YAML syntax is valid

API Gateway Not Working

Check:

api_gateway.enabled: true
api_gateway.url is set
Service URLs are relative when using gateway
Authentication credentials are correct