Skip to main content

Configuration

This guide covers how to configure Dochia for your testing environment. Learn about properties files, individual configuration files, environment variables, and command-line options to optimize your API testing workflow.

Overview​

Dochia supports multiple configuration methods:

  • Command-line arguments - Direct parameter specification for individual runs
  • Properties files - Main configuration using --config option
  • Individual configuration files - YAML files for headers, query params, reference data, etc.
  • Default properties file - .dochia.properties in user home directory
  • Environment variables - Integration with CI/CD pipelines

Properties Configuration Files​

Main Configuration File​

Dochia uses properties files (.properties format) for main configuration via the --config option:

# dochia.properties
contract=./openapi.yml
server=https://api.example.com
connection-timeout=30
read-timeout=30
write-timeout=30
max-requests-per-minute=1000
user-agent=dochia/custom-1.0

# Authentication
user=api-user:secret-password

# Test control
blackbox=false
include-emojis=true

# Output
output=./reports
output-format=HTML_JS,JSON
hide-success=false
hide-warnings=false

# Response handling
ignore-codes=404,429
filter-codes=2xx
max-response-time=5000

Default Configuration File​

Create a .dochia.properties file in your user home directory (~/.dochia.properties) for default settings:

# ~/.dochia.properties - Default configuration
connection-timeout=10
read-timeout=10
write-timeout=10
max-requests-per-minute=600
user-agent=dochia/1.0.2-SNAPSHOT
output-format=HTML_JS
color=true
check-update=false

Environment-Specific Properties​

Development Environment:

# dochia-dev.properties
contract=./openapi.yml
server=http://localhost:8080
connection-timeout=5
read-timeout=5
user=dev-user:dev-password
output=./dev-reports
hide-success=true

# To run only specific playbooks for focused testing during development
playbooks=EmptyStringsInFields,NullValuesInFields

# Note: You cannot use skip-playbooks at the same time as playbooks.
# skip-playbooks=VeryLargeStrings,LargeNumberOfRandomHeaders

Production Environment:

# dochia-prod.properties
contract=./openapi.yml
server=https://api.production.com
connection-timeout=60
read-timeout=60
max-requests-per-minute=100
output=./prod-reports
blackbox=true
filter-codes=2xx,4xx

Usage:

# Use specific properties file
dochia test --config dochia-dev.properties
dochia test --config dochia-prod.properties

Authentication Configuration​

Basic Authentication​

Use the --user or -u option for basic authentication:

# In properties file
user=username:password
# Command line
dochia test -c openapi.yml -s https://api.example.com -u username:password

Header-Based Authentication​

Use headers for API keys, bearer tokens, and custom authentication:

# Bearer token
dochia test -c openapi.yml -s https://api.example.com -H "Authorization=Bearer $TOKEN"

# API key
dochia test -c openapi.yml -s https://api.example.com -H "X-API-Key=$API_KEY"

# Custom authentication
dochia test -c openapi.yml -s https://api.example.com -H "X-Auth-Token=$AUTH_TOKEN"

Authentication with Refresh​

For dynamic authentication that requires periodic refresh:

# Properties file
auth-refresh=3600
auth-refresh-script=./get-auth-token.sh
# Command line
dochia test -c openapi.yml -s https://api.example.com \
  --auth-refresh=3600 \
  --auth-refresh-script=./get-auth-token.sh \
  -H "Authorization=auth_script"

The script should output the new token value, and Dochia will replace auth_script in headers with the script output.

Individual Configuration Files​

Headers Configuration​

Create a YAML file for custom headers that apply to specific paths:

# headers.yml
/api/v1/users:
  Authorization: "Bearer ${USER_TOKEN}"
  X-Client-ID: "web-client"

/api/v1/orders:
  Authorization: "Bearer ${ORDER_TOKEN}"
  X-API-Version: "2024-01-15"

# Global headers (applied to all paths)
all:
  User-Agent: "Dochia-Test/1.0"
  Accept: "application/json"
# Usage
dochia test -c openapi.yml -s https://api.example.com --headers headers.yml

Query Parameters Configuration​

Define additional query parameters for specific paths:

# query-params.yml
/api/v1/search:
  debug: "true"
  version: "v2"

/api/v1/users:
  include: "profile,settings"
  format: "json"
# Usage
dochia test -c openapi.yml -s https://api.example.com --query-params query-params.yml

Reference Data Configuration​

Specify fields that must have fixed values for requests to succeed:

# reference-data.yml
/api/v1/users:
  tenantId: "12345"
  organizationId: "org-abc"

/api/v1/orders:
  customerId: "customer-123"
  currency: "USD"
# Usage
dochia test -c openapi.yml -s https://api.example.com --reference-data reference-data.yml

Network and Proxy Configuration​

Proxy Settings​

# Properties file
proxy=http://proxy.company.com:8080
proxy-host=proxy.company.com
proxy-port=8080
# Command line
dochia test -c openapi.yml -s https://api.example.com \
  --proxy=http://proxy.company.com:8080

SSL/TLS Configuration​

# Properties file
ssl-keystore=./certs/keystore.jks
ssl-keystore-password=keystorepass
ssl-key-password=keypass
# Command line
dochia test -c openapi.yml -s https://api.example.com \
  --ssl-keystore=./certs/keystore.jks \
  --ssl-keystore-password=keystorepass

Timeout Configuration​

# Properties file
connection-timeout=30
read-timeout=30
write-timeout=30
max-response-time=5000
# Command line
dochia test -c openapi.yml -s https://api.example.com \
  --connection-timeout=30 \
  --read-timeout=30 \
  --write-timeout=30 \
  --max-response-time=5000

Test Configuration​

Playbook Selection​

You can either include specific playbooks or exclude them, but you cannot use both options at the same time.

Include Playbooks:

# Properties file - To run only specific playbooks
playbooks=EmptyStringsInFields,NullValuesInFields,VeryLargeStrings
# Command line
dochia test -c openapi.yml -s https://api.example.com \
  --playbooks=EmptyStringsInFields,NullValuesInFields

Exclude Playbooks:

# Properties file - To run all playbooks except a few
skip-playbooks=LargeNumberOfRandomHeaders,VeryLargeIntegers
# Command line
dochia test -c openapi.yml -s https://api.example.com \
  --skip-playbooks=LargeNumberOfRandomHeaders

Test Scope Configuration​

For each filter type (paths, HTTP methods, tags), you can either specify which ones to include or which ones to exclude. You cannot use both inclusion and exclusion for the same filter type in a single run.

Path Filtering:

To test only specific paths:

# Include specific paths
paths=/api/v1/users,/api/v1/orders

To test all paths except a few:

# Exclude specific paths
skip-paths=/api/v1/admin,/api/v1/internal

HTTP Method Filtering:

To test only specific HTTP methods:

# Include specific HTTP methods
http-methods=GET,POST,PUT

To test all HTTP methods except a few:

# Exclude specific HTTP methods
skip-http-methods=PATCH,HEAD,OPTIONS

Tag Filtering:

To test only specific tags:

# Include specific tags
tags=user-management,order-processing

To test all tags except a few:

# Exclude specific tags
skip-tags=admin,internal

Command Line Example:

# Include specific paths and exclude certain HTTP methods
dochia test -c openapi.yml -s https://api.example.com \
  --paths=/api/v1/users,/api/v1/orders \
  --skip-http-methods=PATCH,HEAD

Field and Type Filtering​

You can filter by field types and formats using either inclusion or exclusion, but not both for the same category.

Field Type Filtering:

To test only fields of specific types:

# Include specific field types
field-types=string,integer,boolean

To test all fields except for specific types:

# Exclude specific field types
skip-field-types=array,object

Field Format Filtering:

To test only fields of specific formats:

# Include specific field formats
field-formats=email,uri,date-time

To test all fields except for specific formats:

# Exclude specific field formats
skip-field-formats=binary,password

Skipping Specific Fields and Headers:

These options are for exclusion only. You can use them in combination with inclusion filters from other categories (e.g., include field-types=string and skip-fields=password).

# Skip specific fields and headers by name
skip-fields=id,createdAt,updatedAt
skip-headers=Authorization,X-Internal-Token

Output Configuration​

Report Settings​

# Properties file
output=./reports
output-format=HTML_JS,HTML_ONLY
timestamp-reports=true
# Command line
dochia test -c openapi.yml -s https://api.example.com \
  --output=./reports \
  --output-format=HTML_JS \
  --timestamp-reports

Available output formats:

  • HTML_JS - HTML report with JavaScript (default)
  • HTML_ONLY - HTML report without JavaScript (faster rendering)

Console Output Control​

# Properties file
color=true
print-progress=true
execution-stats=true
detailed-execution-stats=false
hide-success=false
hide-warnings=false
# Verbosity levels
dochia test -c openapi.yml -s https://api.example.com -v      # Basic verbose
dochia test -c openapi.yml -s https://api.example.com -vv     # More verbose
dochia test -c openapi.yml -s https://api.example.com -vvv    # Most verbose

# Control colors and progress
dochia test -c openapi.yml -s https://api.example.com --no-color
dochia test -c openapi.yml -s https://api.example.com --print-progress

# Hide certain results
dochia test -c openapi.yml -s https://api.example.com --hide-success --hide-warnings

# Execution statistics
dochia test -c openapi.yml -s https://api.example.com --execution-stats --detailed-execution-stats

Specialized Configuration Files​

Error Keywords Configuration​

Create a properties file to define error leak detection keywords (one keyword per line):

# error-keywords.properties
SELECT
INSERT
UPDATE
DELETE
DROP
Exception
Error
Traceback
at java
password
token
key
secret
debug
trace
verbose
dump
# Usage
dochia test -c openapi.yml -s https://api.example.com \
  --error-keywords=error-keywords.properties

Playbooks Configuration​

Customize expected response codes for specific playbooks:

# playbooks-config.properties
EmptyStringsInFields.expectedResponseCode=400
NullValuesInFields.expectedResponseCode=422
VeryLargeStrings.expectedResponseCode=413
InvalidValuesInEnums.expectedResponseCode=400
# Usage
dochia test -c openapi.yml -s https://api.example.com \
  --playbooks-config=playbooks-config.properties

Execution Order Configuration​

Define the order in which API paths should be tested:

# execution-order.txt
/api/v1/auth/login
/api/v1/users
/api/v1/users/{id}
/api/v1/orders
/api/v1/orders/{id}
/api/v1/auth/logout
# Usage
dochia test -c openapi.yml -s https://api.example.com \
  --execution-order=execution-order.txt

Advanced Configuration​

Rate Limiting​

# Properties file
max-requests-per-minute=1000
# Command line
dochia test -c openapi.yml -s https://api.example.com \
  --max-requests-per-minute=600

HTTP/2 Configuration​

# Properties file
http2-prior-knowledge=true
# Command line
dochia test -c openapi.yml -s https://api.example.com \
  --http2-prior-knowledge

Schema Processing​

# Properties file
max-schema-combinations=50
self-reference-depth=3
use-defaults=true
use-examples=true
use-property-examples=true
use-request-body-examples=false
use-response-body-examples=true
use-schema-examples=false
cache-payloads=true
resolve-response-combinations=false

Field Processing​

# Properties file
fields-selection-strategy=ONEBYONE
max-tested-fields=100
max-fields-to-remove=5
large-strings-size=40000
random-headers-count=10000
edge-spaces-strategy=TRIM_AND_VALIDATE
sanitization-strategy=SANITIZE_AND_VALIDATE

Content Type and Versioning​

# Properties file
content-type=application/vnd.api+json;version=2
rfc7396=true
allow-invalid-enum-values=false

Configuration Validation and Testing​

Dry Run Mode​

Validate your configuration without making actual API calls:

# Test configuration with dry run
dochia test -c openapi.yml -s https://api.example.com --dry-run

# Get JSON output for automation
dochia test -c openapi.yml -s https://api.example.com --dry-run --json

Common Configuration Issues​

Missing Required Parameters:

# ❌ Missing contract or server
dochia test

# ✅ Include required parameters
dochia test -c openapi.yml -s https://api.example.com

Invalid Properties Format:

# ❌ Invalid properties syntax
connection-timeout = 30 seconds

# ✅ Correct properties format
connection-timeout=30

Conflicting Filters: It is invalid to use an inclusion and exclusion filter for the same category in the same run.

# ❌ Conflicting path filters
dochia test -c openapi.yml -s https://api.example.com \
  --paths=/api/v1/users \
  --skip-paths=/api/v1/admin

✅ Valid Filtering: Choose one type of filter for each category.

# Correct: Using only an inclusion filter for paths
dochia test -c openapi.yml -s https://api.example.com \
  --paths=/api/v1/users,/api/v1/orders

# Correct: Using only an exclusion filter for paths
dochia test -c openapi.yml -s https://api.example.com \
  --skip-paths=/api/v1/admin

Invalid YAML Files:

# ❌ Invalid YAML syntax in headers.yml
/api/v1/users
  Authorization: Bearer token  # Missing colon

# ✅ Correct YAML syntax
/api/v1/users:
  Authorization: "Bearer token"

Configuration Templates​

Minimal Configuration​

# Minimal command for quick testing
dochia test -c openapi.yml -s http://localhost:8080

Development Configuration​

# dochia-dev.properties
contract=./openapi.yml
server=http://localhost:8080
connection-timeout=5
read-timeout=5
user=dev-user:dev-password
output=./dev-reports
hide-success=true
playbooks=EmptyStringsInFields,NullValuesInFields
# Usage
dochia test --config dochia-dev.properties

Production Configuration​

# dochia-prod.properties
contract=./openapi.yml
server=https://api.production.com
connection-timeout=60
read-timeout=60
max-requests-per-minute=100
output=./prod-reports
output-format=HTML_JS
timestamp-reports=true
blackbox=true
filter-codes=2xx,4xx
max-response-time=10000
ssl-keystore=./certs/prod-keystore.jks
# Usage
dochia test --config dochia-prod.properties \
  -H "Authorization=Bearer $PROD_TOKEN"

CI/CD Configuration​

# dochia-ci.properties
contract=./openapi.yml
connection-timeout=45
read-timeout=45
max-requests-per-minute=300
output=./ci-reports
output-format=HTML_ONLY
timestamp-reports=false
no-color=true
hide-success=true
execution-stats=true
blackbox=true
# CI/CD usage
dochia test --config dochia-ci.properties \
  -s "$API_BASE_URL" \
  -H "Authorization=Bearer $CI_API_TOKEN" \
  --paths="$TEST_PATHS"

Best Practices​

Security Best Practices​

  • Never hardcode secrets in properties files or command lines
  • Use shell environment variables for sensitive data like tokens and passwords
  • Use the --mask-headers option to hide sensitive headers in reports
  • Rotate API tokens regularly and update your deployment scripts
  • Use SSL keystores for production environments with client certificates
  • Limit test scope to avoid testing admin or internal endpoints
# Mask sensitive headers in reports
dochia test -c openapi.yml -s https://api.example.com \
  -H "Authorization=Bearer $TOKEN" \
  --mask-headers=Authorization,X-API-Key

Performance Optimization​

  • Configure appropriate timeouts based on your API's performance characteristics
  • Use rate limiting with --max-requests-per-minute to avoid overwhelming servers
  • Limit test scope using --paths, --playbooks, and --tags for large APIs
  • Use blackbox mode (--blackbox) for faster testing in production environments
  • Enable HTTP/2 with --http2-prior-knowledge for better performance
  • Cache payloads with --cache-payloads to reduce memory usage

Configuration Management​

  • Version control all configuration files (properties files, YAML files)
  • Use separate configurations for different environments (dev, staging, prod)
  • Document environment-specific settings and requirements
  • Test configurations with --dry-run before actual execution
  • Use execution order files for APIs with dependencies between endpoints
  • Organize configuration files in a dedicated directory structure
config/
├── dochia-dev.properties
├── dochia-staging.properties
├── dochia-prod.properties
├── headers/
│   ├── dev-headers.yml
│   └── prod-headers.yml
├── reference-data/
│   ├── dev-data.yml
│   └── prod-data.yml
└── execution-orders/
    └── api-flow.txt

Troubleshooting Tips​

  • Use verbose output (-v, -vv, -vvv) to debug configuration issues
  • Test with dry run to validate settings without making API calls
  • Check execution statistics with --execution-stats to identify performance issues
  • Use JSON output (--dry-run --json) for automated parsing and validation
  • Validate YAML files syntax before using them with Dochia
  • Monitor response times with --max-response-time to catch performance regressions