Skip to main content

Using Reference Data in Dochia

This guide explains how to use reference data in Dochia to provide required field values, test specific scenarios, and maintain test data consistency.

Overview​

Reference data helps you:

  • Provide required field values automatically
  • Test edge cases and specific scenarios
  • Maintain consistent test data across runs
  • Override values per endpoint or method

Prerequisites​

  • OpenAPI spec (-c, --contract)
  • Server URL (-s, --server)
  • Basic understanding of your API's required fields

Basic Usage​

Inline Reference Data​

# Single value
dochia test -c api.yml -s http://localhost:8080 \
  --reference-data "tenantId=test123"

# Multiple values (comma-separated)
dochia test -c api.yml -s http://localhost:8080 \
  --reference-data "tenantId=test123,currency=USD,environment=test"

From YAML File​

# reference.yml
all:
  tenantId: "test123"
  currency: "USD"
  environment: "test"
  timestamp: "$(date +%s)"  # Dynamic values work too
dochia test -c api.yml -s http://localhost:8080 \
  --reference-data reference.yml

Advanced Patterns​

Per-Path Overrides​

# reference.yml
all:
  tenantId: "default-tenant"
  currency: "USD"

/users:
  tenantId: "users-tenant"  # Overrides the default for /users
  role: "admin"

/orders:
  currency: "EUR"  # Overrides the default for /orders
  status: "pending"

Dynamic Values with SpringEL​

Dochia supports Spring Expression Language (SpringEL) for dynamic values in reference data. Use ${...} for expressions and T(...) for static method access:

# reference.yml
all:
  # Current timestamp in milliseconds
  timestamp: "${T(java.lang.System).currentTimeMillis()}"
  
  # Random UUID
  requestId: "${T(java.util.UUID).randomUUID().toString()}"
  
  # Static method with parameters
  randomNumber: "${T(java.util.concurrent.ThreadLocalRandom).current().nextInt(1000)}"
  
  # Date formatting
  currentDate: "${new java.text.SimpleDateFormat('yyyy-MM-dd').format(new java.util.Date())}"
  
  # String manipulation
  correlationId: "${corr-T(java.util.UUID).randomUUID().toString().substring(0, 8)}"

Environment Variables​

Access environment variables using $$ prefix:

# reference.yml
all:
  # Required environment variable (fails if not set)
  apiKey: "$$API_KEY"
# Set environment variables when running
API_KEY=abc123 ENV=staging dochia test -c api.yml -s http://localhost:8080 \
  --reference-data reference.yml

Field Removal​

Use the special value dochia_remove_field to remove a field from the request payload:

# reference.yml
all:
  # This field will be included with value "test"
  includeField: "test"
  
  # This field will be removed from the payload
  removeField: "dochia_remove_field"

Nested Fields with JSON Path​

Reference nested fields using # as a separator:

# reference.yml
all:
  # Simple field
  orderId: "ORD-123"
  
  # Nested field (address.street)
  "address#street": "123 Main St"
  
  # Deeply nested field (customer.address.postCode)
  "customer#address#postCode": "12345"
  
  # Combine with dynamic values
  "customer#email": "${user-T(java.util.UUID).randomUUID().toString().substring(0, 8)@example.com}"

This will generate JSON like:

{
  "orderId": "ORD-123",
  "address": {
    "street": "123 Main St"
  },
  "customer": {
    "email": "user-a1b2c3d4@example.com",
    "address": {
      "postCode": "12345"
    }
  }
}

Common Use Cases​

Required Authentication Fields​

# auth-fields.yml
all:
  userId: "test-user-123"
  clientId: "test-client"
  sessionToken: "$SESSION_TOKEN"

Test Data Variations​

# test-scenarios.yml
# Happy path
all:
  productId: "prod_123"
  quantity: 1
  price: 99.99

# Edge case: High quantity
/orders:
  quantity: 9999
  notes: "Bulk order test"

# Edge case: Free item
/products/special:
  price: 0
  discount: 100

Best Practices​

  1. Use environment variables for secrets:

    # reference.yml
    all:
      apiKey: "$$API_KEY"  # Set via environment

  2. Document your reference data:

    # reference.yml
    # Common fields used across all endpoints
    all:
      # Required tenant identifier
      tenantId: "test-tenant-1"
      
      # Test environment flag
      environment: "test"

  3. Organize by domain:

    /reference-data/
      ├── common.yml      # Shared fields
      ├── users.yml       # User-related test data
      ├── products.yml    # Product test data
      └── orders.yml      # Order processing scenarios

  4. Version control:

    • Commit reference data files
    • Use .gitignore for sensitive data
    • Document required environment variables

Troubleshooting​

  • Values not being applied:

    • Check YAML indentation (2 spaces per level)
    • Verify the path matches exactly (case-sensitive)
    • Use -vvv to see resolved reference data

  • Environment variables not expanding:

    • Ensure the variable is exported
    • Use direct env vars for sensitive data instead

  • Dynamic commands not working:

    • Commands are executed in a basic shell
    • Complex commands may need to be simplified

See Also​