Skip to main content

dochia test

The test command is Dochia's primary feature for automatically generating and executing negative and boundary tests from OpenAPI specifications using 100+ fuzzing playbooks.

Basic Usage​

dochia test -c <contract> -s <server> [OPTIONS]

Required Parameters​

  • -c, --contract=<contract> - Path to your OpenAPI specification file
  • -s, --server=<server> - Base URL of the API service to test

Common Options​

  • -h, --help - Show help message
  • -V, --version - Show version information
  • -o, --output=<output> - Output directory for test results
  • --blackbox - Only report 5XX server errors (blackbox mode)

Quick Examples​

# Basic test run
dochia test -c openapi.yml -s http://localhost:8080

# Blackbox mode (only report 5XX errors)
dochia test -c openapi.yml -s http://localhost:8080 --blackbox

# With authentication
dochia test -c openapi.yml -s http://localhost:8080 --header "Authorization=Bearer $TOKEN"

# Test specific paths only
dochia test -c openapi.yml -s http://localhost:8080 --path "/users" --path "/orders"

API Configuration Options​

Connection Settings​

OptionDescriptionDefault
--connection-timeout=<timeout>Connection establishment timeout (seconds)10
--read-timeout=<timeout>Response read timeout (seconds)10
--write-timeout=<timeout>Request write timeout (seconds)10
--max-requests-per-minute=<max>Rate limiting for API calls10000
--user-agent=<user-agent>Custom User-Agent headerdochia/1.0.2

HTTP/2 Support​

OptionDescriptionDefault
--http2-prior-knowledgeForce HTTP/2 connection without fallbackfalse

Authentication Options​

Basic Authentication​

# Username/password authentication
dochia test -c api.yml -s https://api.example.com --user "username:password"

Header-based Authentication​

# Single header for all requests
dochia test -c api.yml -s https://api.example.com --header "Authorization=Bearer token123"

# Multiple headers
dochia test -c api.yml -s https://api.example.com --header "API-Key=key123" --header "X-Client-ID=client456"

File-based Headers​

# YAML file with per-path headers
dochia test -c api.yml -s https://api.example.com --headers headers.yml

headers.yml example:

/users:
  Authorization: "Bearer user-token"
  X-User-Role: "admin"
/orders:
  Authorization: "Bearer order-token"
  X-Service: "orders"

Dynamic Authentication​

# Refresh authentication periodically
dochia test -c api.yml -s https://api.example.com \
  --auth-refresh=3600 \
  --auth-refresh-script=./get-token.sh

SSL/TLS Configuration​

OptionDescription
--ssl-keystore=<keystore>Path to SSL keystore
--ssl-keystore-password=<password>Keystore password
--ssl-key-password=<password>Private key password

Proxy Settings​

# Full proxy URL
dochia test -c api.yml -s https://api.example.com --proxy http://proxy.company.com:8080

# Separate host and port
dochia test -c api.yml -s https://api.example.com --proxy-host proxy.company.com --proxy-port 8080

Test Control Options​

Playbook Categories​

OptionDescription
--headers-onlyRun only Header Playbooks
--body-onlyRun only Body Playbooks
--fields-onlyRun only Fields Playbooks

Playbook Selection​

# Run specific playbooks
dochia test -c api.yml -s http://localhost:8080 --playbook "EmptyStrings" --playbook "NullValues"

# Skip specific playbooks
dochia test -c api.yml -s http://localhost:8080 --skip-playbook "VeryLargeStrings"

# List available playbooks
dochia list --playbooks -c api.yml

Filtering and Selection​

Path Selection​

# Test specific paths
dochia test -c api.yml -s http://localhost:8080 --path "/users" --path "/orders" --path "/products"

# Skip certain paths
dochia test -c api.yml -s http://localhost:8080 --skip-path "/admin" --skip-path "/internal"

# List available paths
dochia list --paths -c api.yml

HTTP Method Filtering​

# Test only specific HTTP methods
dochia test -c api.yml -s http://localhost:8080 --http-method "POST" --http-method "PUT" --http-method "PATCH"

# Skip certain HTTP methods
dochia test -c api.yml -s http://localhost:8080 --skip-http-method "DELETE" --skip-http-method "TRACE"

Tag-based Filtering​

# Test endpoints with specific tags
dochia test -c api.yml -s http://localhost:8080 --tag "user-management" --tag "billing"

# Skip endpoints with certain tags
dochia test -c api.yml -s http://localhost:8080 --skip-tag "deprecated" --skip-tag "internal"

# List available tags
dochia list --tags -c api.yml

Field Type and Format Filtering​

# Test only specific field types
dochia test -c api.yml -s http://localhost:8080 --field-types "string,integer"

# Test only specific formats
dochia test -c api.yml -s http://localhost:8080 --field-formats "email,uuid"

# Skip certain field types
dochia test -c api.yml -s http://localhost:8080 --skip-field-types "array,object"

# Skip specific fields
dochia test -c api.yml -s http://localhost:8080 --skip-fields "id,createdAt,!password"

Note: Fields prefixed with ! (like !password) are skipped by ALL playbooks.

Other Filters​

# Skip deprecated operations
dochia test -c api.yml -s http://localhost:8080 --skip-deprecated-operations

# Skip specific headers from testing
dochia test -c api.yml -s http://localhost:8080 --skip-headers "User-Agent,Accept"

Data Configuration​

URL Parameters​

# Single parameter replacement
dochia test -c api.yml -s http://localhost:8080 -U "userId=123"

# Multiple parameters
dochia test -c api.yml -s http://localhost:8080 --url-params "userId:123,orderId:456"

Query Parameters​

# Global query parameters
dochia test -c api.yml -s http://localhost:8080 -Q "api_key=secret123"

# File-based query parameters
dochia test -c api.yml -s http://localhost:8080 --query-params query-params.yml

Reference Data​

# Required field values for successful requests
dochia test -c api.yml -s http://localhost:8080 -R "tenantId=company123"

# File-based reference data
dochia test -c api.yml -s http://localhost:8080 --reference-data reference.yml

reference.yml example:

/users:
  tenantId: "company123"
  apiVersion: "v1"
/orders:
  customerId: "customer456"

Response Handling​

Blackbox Mode​

# Ignore all response codes except 5XX
dochia test -c api.yml -s http://localhost:8080 -b

Response Code Handling​

# Filter out specific codes (don't report them)
dochia test -c api.yml -s http://localhost:8080 --filter-codes "200,201,400"

# Ignore specific codes (still report but treat as success)
dochia test -c api.yml -s http://localhost:8080 --ignore-codes "429,503"

Response Content Filtering​

# Filter by response size
dochia test -c api.yml -s http://localhost:8080 --filter-size "0,1024"

# Filter by word count
dochia test -c api.yml -s http://localhost:8080 --filter-words "0,10"

# Filter by line count
dochia test -c api.yml -s http://localhost:8080 --filter-lines "1,5"

# Filter by regex pattern
dochia test -c api.yml -s http://localhost:8080 --filter-regex "success|ok"

Validation Controls​

# Disable various validation checks
dochia test -c api.yml -s http://localhost:8080 \
  --ignore-body-validation \
  --ignore-content-type-check \
  --ignore-error-leak-check \
  --ignore-undocumented-codes

Result Display​

# Hide successful results
dochia test -c api.yml -s http://localhost:8080 --hide-success

# Hide warnings
dochia test -c api.yml -s http://localhost:8080 --hide-warnings

Processing and Generation​

Payload Generation​

# Use schema examples from OpenAPI spec
dochia test -c api.yml -s http://localhost:8080 --use-schema-examples

# Use request body examples from OpenAPI spec
dochia test -c api.yml -s http://localhost:8080 --use-request-body-examples

Schema Handling​

# Control oneOf/anyOf combinations
dochia test -c api.yml -s http://localhost:8080 --max-schema-combinations 10

# Handle cyclic dependencies
dochia test -c api.yml -s http://localhost:8080 --self-reference-depth 3

# Use discriminators for filtering
dochia test -c api.yml -s http://localhost:8080 --schema-discriminator "type=user"

Field Testing Limits​

# Limit number of fields tested
dochia test -c api.yml -s http://localhost:8080 --max-tested-fields 50

# Control field removal strategy
dochia test -c api.yml -s http://localhost:8080 --max-fields-to-remove 5

String and Content Settings​

# Custom large string size
dochia test -c api.yml -s http://localhost:8080 --large-strings-size 50000

# Custom content type
dochia test -c api.yml -s http://localhost:8080 --content-type "application/vnd.api+json"

# RFC 7396 PATCH support
dochia test -c api.yml -s http://localhost:8080 --rfc7396

Processing Strategies​

# Edge spaces handling
dochia test -c api.yml -s http://localhost:8080 --edge-spaces-strategy VALIDATE_AND_TRIM

# Sanitization strategy
dochia test -c api.yml -s http://localhost:8080 --sanitization-strategy SANITIZE_AND_VALIDATE

# Fields selection strategy
dochia test -c api.yml -s http://localhost:8080 --fields-selection-strategy ONEBYONE

Configuration Files​

Main Configuration​

# Use configuration file
dochia test --config dochia-config.yml

Execution Order​

# Control path execution order
dochia test -c api.yml -s http://localhost:8080 --execution-order execution-order.txt

execution-order.txt example:

/health
/users
/orders
/products

Error Detection​

# Custom error keywords
dochia test -c api.yml -s http://localhost:8080 --error-keywords error-keywords.txt

error-keywords.txt example:

Database connection failed
Authentication failed
Validation error

Playbook Configuration​

# Custom playbook settings
dochia test -c api.yml -s http://localhost:8080 --playbooks-config playbooks.properties

playbooks.properties example:

EmptyStringsInFieldsPlaybook.expectedResponseCode=400
NullValuesInFieldsPlaybook.expectedResponseCode=422

Reporting and Output​

Output Location​

# Custom output directory
dochia test -c api.yml -s http://localhost:8080 -o ./test-results

# Timestamped reports
dochia test -c api.yml -s http://localhost:8080 --timestamp-reports

Report Formats​

# Change report format
dochia test -c api.yml -s http://localhost:8080 --output-format "HTML_ONLY"

Available formats:

  • HTML_JS - Interactive HTML with JavaScript (default)
  • HTML_ONLY - Static HTML without JavaScript

Performance Reporting​

# Basic execution statistics
dochia test -c api.yml -s http://localhost:8080 --execution-stats

# Detailed performance metrics
dochia test -c api.yml -s http://localhost:8080 --detailed-execution-stats

# Response time limits
dochia test -c api.yml -s http://localhost:8080 --max-response-time 5000

Console Output​

# Verbose logging
dochia test -c api.yml -s http://localhost:8080 -vvv

# Disable colors
dochia test -c api.yml -s http://localhost:8080 --no-color

# Show progress
dochia test -c api.yml -s http://localhost:8080 --print-progress

# Mask sensitive headers in logs
dochia test -c api.yml -s http://localhost:8080 --mask-headers "Authorization,X-API-Key"

Dry Run Mode​

# Preview what will be tested
dochia test -c api.yml -s http://localhost:8080 --dry-run

# JSON output for dry run
dochia test -c api.yml -s http://localhost:8080 --dry-run --json

Dry run shows:

  • Number of tests that will be executed
  • Paths and methods to be tested

Advanced Examples​

Complete E-commerce API Test​

dochia test \
  -c ecommerce-api.yml \
  -s https://api.ecommerce.com \
  -H "Authorization=Bearer $API_TOKEN" \
  -H "X-Client-Version=1.2.3" \
  --reference-data ./reference-data.yml \
  --headers ./auth-headers.yml \
  --skip-paths "/admin,/internal" \
  --skip-playbooks "VeryLargeStrings" \
  --max-requests-per-minute 100 \
  --execution-stats \
  -o ./test-results

Microservice Testing with Custom Configuration​

dochia test \
  -c user-service.yml \
  -s http://localhost:8080 \
  --config ./dochia-config.yml \
  --playbooks-config ./playbook-settings.properties \
  --error-keywords ./error-patterns.properties \
  -t "user-management" \
  -X "POST,PUT,PATCH" \
  --max-tested-fields 20 \
  --hide-success \
  --timestamp-reports

High-Security API Testing​

dochia test \
  -c secure-api.yml \
  -s https://secure.api.com \
  --ssl-keystore ./client-cert.p12 \
  --ssl-keystore-password "$KEYSTORE_PASS" \
  --proxy https://corporate-proxy:8080 \
  --auth-refresh 1800 \
  --auth-refresh-script ./refresh-token.sh \
  --mask-headers "Authorization,X-API-Secret" \
  --ignore-error-leak-check \
  -b

Exit Codes​

CodeMeaning
0Successful execution
191Usage error (incorrect command arguments)
192Internal execution error
ERRNumber of errors found (e.g., exit code 5 means 5 errors)

See Also​