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

Option	Description	Default
`--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 calls	10000
`--user-agent=<user-agent>`	Custom User-Agent header	dochia/1.0.2

HTTP/2 Support

Option	Description	Default
`--http2-prior-knowledge`	Force HTTP/2 connection without fallback	false

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

Option	Description
`--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

Run Profiles

Profiles group playbooks into named, reusable test suites. Use --profile to run a built-in profile, or --profile-file to load your own custom profiles.

# Run a built-in profile
dochia test -c api.yml -s http://localhost:8080 --profile quick
dochia test -c api.yml -s http://localhost:8080 --profile security
dochia test -c api.yml -s http://localhost:8080 --profile ci

# Run a custom profile from a file
dochia test -c api.yml -s http://localhost:8080 \
  --profile-file ./profiles.yml \
  --profile my-custom-profile

# List all available profiles (built-in + custom)
dochia list --profiles

Built-in Profiles

Profile	Description
`health-check`	Minimal check — runs only `HappyPath` to verify endpoints are reachable
`quick`	Fast smoke test covering the most critical scenarios
`ci`	Balanced suite optimised for CI/CD pipelines
`security`	Security-focused playbooks targeting OWASP vulnerabilities and attack vectors
`compliance`	OWASP API Security Top 10 compliance testing
`type-coercion`	Playbooks targeting issues where types are coerced by frameworks/libraries
`full`	Complete suite — all playbooks enabled (default behaviour when no profile is set)

Custom Profiles

Define your own profiles in a YAML file and load them with --profile-file:

dochia test -c api.yml -s http://localhost:8080 \
  --profile-file ./profiles.yml \
  --profile my-custom-profile

profiles.yml example:

my-custom-profile:
  description: "My team's critical path tests"
  playbooks:
    - NullValuesInFields
    - EmptyStringsInFields
    - BypassAuthentication
    - SqlInjectionInStringFields

Custom profiles are available alongside built-in ones. Pass --profile-file together with dochia list --profiles to see them listed:

dochia list --profiles --profile-file ./profiles.yml

Health Check Shorthand

The health-check profile has a dedicated shorthand flag for convenience:

# These two commands are equivalent
dochia test -c api.yml -s http://localhost:8080 --health-check
dochia test -c api.yml -s http://localhost:8080 --profile health-check

The health-check runs only the HappyPath playbook — it confirms that all API endpoints are reachable and responding, without performing any negative or fuzzing tests. Ideal for deployment smoke tests.

Test Control Options

Playbook Categories

Option	Description
`--headers-only`	Run only Header Playbooks
`--body-only`	Run only Body Playbooks
`--fields-only`	Run only Fields Playbooks

Positive and Negative Mode

Control whether Dochia runs only positive or only negative playbooks. The set of positive/negative playbooks is not a fixed list — it is computed dynamically for each contract and run based on the structure of the API under test.

# Run only positive playbooks (valid inputs that should succeed)
dochia test -c api.yml -s http://localhost:8080 --mode positive

# Run only negative playbooks (invalid inputs that should be rejected)
dochia test -c api.yml -s http://localhost:8080 --mode negative

Value	Description
`positive`	Execute only playbooks that send valid/well-formed inputs
`negative`	Execute only playbooks that send invalid/malformed inputs (default behaviour)

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

Skip Playbooks for OpenAPI Extension

Skip specific playbooks for endpoints that carry a given OpenAPI extension value. Useful for annotating endpoints in your spec and suppressing irrelevant tests automatically.

# Skip BypassAuthentication for all endpoints marked as public
dochia test -c api.yml -s http://localhost:8080 \
  --skip-playbooks-for-extension "x-public-endpoint=true:BypassAuthentication"

# Skip multiple playbooks for the same extension
dochia test -c api.yml -s http://localhost:8080 \
  --skip-playbooks-for-extension "x-internal=true:BypassAuthentication,MassAssignment"

# Combine multiple extension rules
dochia test -c api.yml -s http://localhost:8080 \
  --skip-playbooks-for-extension "x-public-endpoint=true:BypassAuthentication" \
  --skip-playbooks-for-extension "x-read-only=true:MassAssignment,NewFields"

Format: x-extension-name=value:Playbook1,Playbook2

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"

Operation ID Filtering

# Test only specific operations by their OpenAPI operationId
dochia test -c api.yml -s http://localhost:8080 --operation-id "getUser" --operation-id "createOrder"

# Skip specific operations by operationId
dochia test -c api.yml -s http://localhost:8080 --skip-operation-id "deleteUser" --skip-operation-id "adminReset"

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

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

Deterministic Generation

# Fix the random seed for reproducible test generation
dochia test -c api.yml -s http://localhost:8080 --seed 42

# Combine with other options for a fully reproducible run
dochia test -c api.yml -s http://localhost:8080 --seed 1234 --output ./deterministic-results

Using --seed ensures that Dochia generates the same sequence of payloads across runs, making it easy to reproduce failures and share exact test scenarios with teammates.

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"

# Specify default discriminator casing when no mapping exists
dochia test -c api.yml -s http://localhost:8080 --discriminator-casing camelCase

Discriminator Casing

When your OpenAPI spec uses discriminator objects and no explicit mapping is provided for a particular value, Dochia needs to know which casing convention to apply when selecting the discriminator. Use --discriminator-casing to set this default:

Value	Discriminator Casing
`camelCase`	`myDiscriminator`
`PascalCase`	`MyDiscriminator`
`snake_case`	`my_discriminator`
`kebab-case`	`my-discriminator`
`UPPER_SNAKE_CASE`	`MY_DISCRIMINATOR`
`lowercase`	`mydiscriminator`

dochia test -c api.yml -s http://localhost:8080 --discriminator-casing PascalCase

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

HTTP Method Playbook Behaviour

`--check-allow-header`

When enabled, the HTTP method playbooks (HttpMethodsPlaybook, CustomHttpMethodsPlaybook, NonRestHttpMethodsPlaybook) additionally assert that the response includes an Allow header listing the permitted methods. Disabled by default.

# Also assert that the Allow header is present and correct in HTTP method playbook responses
dochia test -c api.yml -s http://localhost:8080 --check-allow-header

Quality Gates

Quality gates let you enforce pass/fail thresholds on a run, making it easy to integrate Dochia into CI/CD pipelines with fine-grained control over what constitutes a failure.

`--fail-on`

Control which result types cause Dochia to exit with code 1. By default only errors trigger a failure.

# Default: exit 1 if any errors are found (equivalent to --fail-on error)
dochia test -c api.yml -s http://localhost:8080

# Exit 1 on any error or warning
dochia test -c api.yml -s http://localhost:8080 --fail-on error,warn

# Exit 1 on warnings only (errors are still reported but don't fail the run)
dochia test -c api.yml -s http://localhost:8080 --fail-on warn

Value	Behaviour
`error`	Exit `1` if one or more errors are found (default)
`warn`	Exit `1` if one or more warnings are found
`error,warn`	Exit `1` if either errors or warnings are found

`--quality-gate`

Set numeric thresholds for errors and/or warnings. Dochia exits with code 1 if a threshold is breached.

# Fail if errors >= 5 or warnings >= 20
dochia test -c api.yml -s http://localhost:8080 --quality-gate "errors<5,warns<20"

# Tolerate up to 2 errors before failing
dochia test -c api.yml -s http://localhost:8080 --quality-gate "errors<3"

# Zero-tolerance: any single error fails the run
dochia test -c api.yml -s http://localhost:8080 --quality-gate "errors<1"

Format: metric<threshold or metric>threshold

Metric	Description
`errors`	Total number of error results
`warns`	Total number of warning results

Note: --fail-on and --quality-gate can be combined. The run fails if either condition is met.

# Fail on any warning, AND also fail if errors reach 5
dochia test -c api.yml -s http://localhost:8080 \
  --fail-on warn \
  --quality-gate "errors<5"

Top Failing Playbooks Summary

At the end of every run, Dochia prints a summary of the top 5 playbooks with the most failures. This gives you an at-a-glance view of which testing strategies are producing the most errors, allowing you to prioritize fixes or investigations.

Example console output:

─────────────────────────────────────────
 Top 5 failing playbooks
─────────────────────────────────────────
 1. NullValuesInFields          (23 errors)
 2. EmptyStringsInFields        (17 errors)
 3. VeryLargeStrings            (9 errors)
 4. InvalidEnumValues           (5 errors)
 5. MissingRequiredFields       (3 errors)
─────────────────────────────────────────

This summary is always printed regardless of --hide-success or --hide-warnings settings, so critical failure trends are never missed.

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

Code	Meaning
`0`	Successful execution — no errors found
`1`	Errors found during testing (one or more test failures)
`2`	Usage error or internal error (invalid arguments, missing files, internal fault)

dochia list - List available paths, playbooks, and tags
dochia info - Get information about OpenAPI specs
dochia explain - Understand playbook behavior
dochia replay - Replay specific test cases

Basic Usage​

Required Parameters​

Common Options​

Quick Examples​

API Configuration Options​

Connection Settings​

HTTP/2 Support​

Authentication Options​

Basic Authentication​

Header-based Authentication​

File-based Headers​

Dynamic Authentication​

SSL/TLS Configuration​

Proxy Settings​

Run Profiles​

Built-in Profiles​

Custom Profiles​

Health Check Shorthand​

Test Control Options​

Playbook Categories​

Positive and Negative Mode​

Playbook Selection​

Skip Playbooks for OpenAPI Extension​

Filtering and Selection​

Path Selection​

HTTP Method Filtering​

Operation ID Filtering​

Tag-based Filtering​

Field Type and Format Filtering​

Other Filters​

Data Configuration​

URL Parameters​

Query Parameters​

Reference Data​

Response Handling​

Blackbox Mode​

Response Code Handling​

Response Content Filtering​

Validation Controls​

Result Display​

Processing and Generation​

Payload Generation​

Deterministic Generation​

Schema Handling​

Discriminator Casing​

Field Testing Limits​

String and Content Settings​

Processing Strategies​

Configuration Files​

Main Configuration​

Execution Order​

Error Detection​

Playbook Configuration​

HTTP Method Playbook Behaviour​

--check-allow-header​

Quality Gates​

--fail-on​

--quality-gate​

Top Failing Playbooks Summary​

Reporting and Output​

Output Location​

Report Formats​

Performance Reporting​

Console Output​

Dry Run Mode​

Advanced Examples​

Complete E-commerce API Test​

Microservice Testing with Custom Configuration​

High-Security API Testing​

Exit Codes​

Related Commands​

See Also​