Skip to main content

Customizing Dochia

Dochia offers a wide range of options to customize its behavior, from filtering which tests to run to controlling how data is generated and how reports are formatted. This guide covers the key customization features based on the available CLI flags.

Filtering Tests​

You can precisely control the scope of a test run using various filtering flags.

  • By Paths: Include or exclude specific API paths.
# Only test endpoints under /users
dochia test ... --path "/users" --path "/users/{id}"

# Exclude the /health endpoint
dochia test ... --skip-path "/health"
  • By HTTP Methods: Target specific HTTP verbs.
dochia test ... --http-method "GET" --http-method "POST"
  • By Tags: Use OpenAPI tags to run tests on logical groups of endpoints.
# Only test endpoints tagged as 'public'
dochia test ... --tag "public"

# Exclude endpoints tagged as 'internal'
dochia test ... --skip-tag "internal"
  • By Playbooks: Run or skip specific testing playbooks.
# Only run the SQL and NoSQL injection playbooks
dochia test ... --playbook "SQL_INJECTION" --playbook "NO_SQL_INJECTION"

# Skip stateful and performance playbooks
dochia test ... --skip-playbook "stateful" --skip-playbook "performance"
  • By Operation ID: Target or exclude specific operations using their OpenAPI operationId.
# Only test specific operations
dochia test ... --operation-id "getUser" --operation-id "createOrder"

# Exclude specific operations
dochia test ... --skip-operation-id "deleteUser" --skip-operation-id "adminReset"
  • By Mode: Run only positive (valid input) or negative (invalid input) playbooks. The set is computed dynamically per contract.
# Run only negative playbooks
dochia test ... --mode negative

# Run only positive playbooks
dochia test ... --mode positive
  • By Profile: Use a named profile to select a curated group of playbooks without listing them individually.
# Built-in profiles: health-check, quick, ci, security, compliance, type-coercion, full
dochia test ... --profile security
dochia test ... --profile ci

# Custom profile from a YAML file
dochia test ... --profile-file ./profiles.yml --profile my-custom-profile

# Health-check shorthand (runs HappyPath only)
dochia test ... --health-check

# List all available profiles (including custom)
dochia list --profiles
dochia list --profiles --profile-file ./profiles.yml
  • By OpenAPI Extension: Skip specific playbooks for endpoints that carry a given OpenAPI extension value.
# Skip BypassAuthentication for endpoints with x-public-endpoint=true
dochia test ... --skip-playbooks-for-extension "x-public-endpoint=true:BypassAuthentication"

# Multiple playbooks and multiple rules
dochia test ... \
  --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

  • By Schema Discriminator: Filter payloads when oneOf/anyOf is used.
dochia test ... --schema-discriminator "type=Cat"

Controlling Data Generation​

Customize the data Dochia sends in its requests.

  • Deterministic Generation: Fix the random seed for a fully reproducible run.
# Same payload sequence on every run
dochia test ... --seed 42
  • Dynamic Values in Config Files: Use #(function) shorthand in headers, query parameters, and reference data YAML files to generate fresh values per request.
# reference-data.yml
all:
  requestId: "#(uuid)"
  token: "#(alphanumeric(32))"
  today: "#(today)"
  expiry: "#(todayPlus(7))"

See Dynamic Value Functions for the full function reference.

  • Fuzzing Strategies: Control how fields are fuzzed.
# Fuzz all fields at once instead of one by one
dochia test ... --fields-fuzzing-strategy ALL
  • Use OpenAPI Examples: Control whether Dochia uses examples from your spec.
# Disable all examples
dochia test ... --no-use-examples

# Enable only request body examples
dochia test ... --use-request-body-examples
  • String and Header Sizes: Adjust the size of generated data.
# Set the size for very large strings
dochia test ... --large-strings-size 50000

# Set the number of random headers to send
dochia test ... --random-headers-count 5000
  • Recursion Depth: Set the max depth for objects with cyclic dependencies.
dochia test ... --self-reference-depth 3

Adjusting Validation and Behavior​

Fine-tune how Dochia validates responses and handles requests.

  • Timeouts: Configure connection, read, and write timeouts (in ms).
dochia test ... --read-timeout 5000 --connection-timeout 2000
  • Blackbox Mode: Report only 5xx server errors, ignoring other non-2xx responses.
dochia test ... -b
  • Allow Header Validation: Assert that HTTP method playbooks receive an Allow header listing the permitted methods.
dochia test ... --check-allow-header
  • Content-Types: Specify which content types to test.
dochia test ... --content-types application/json,application/xml
  • Validation Strategies: Control how Dochia handles edge cases like extra spaces or special characters.
# Expect trailing/leading spaces to be rejected
dochia test ... --edge-boundary-strategy VALIDATE_ONLY

# Expect unicode control characters to be rejected
dochia test ... --sanitization-strategy VALIDATE_ONLY

Quality Gates​

Control what causes Dochia to exit with code 1, independently of the raw error count.

  • --fail-on: Specify which result types trigger a failure.
# Default: fail on errors only
dochia test ... --fail-on error

# Fail on warnings too
dochia test ... --fail-on error,warn
  • --quality-gate: Set numeric thresholds. The run fails if a threshold is breached.
# Fail if errors >= 5 or warnings >= 20
dochia test ... --quality-gate "errors<5,warns<20"

# Combine with --fail-on
dochia test ... --fail-on warn --quality-gate "errors<5"

Customizing Reporting and Output​

Tailor the console output and generated reports to your needs.

  • Report Formats: Generate reports in different formats.

    # Generate a JS-free HTML report
    dochia test ... --output-format HTML_ONLY

  • Mask Headers: Hide sensitive data in logs and reports.

    dochia test ... --mask-headers "Authorization,X-Api-Key"

  • Execution Statistics: Get detailed performance metrics.

    # Print detailed stats for each request
    dochia test ... --detailed-execution-stats

  • Verbosity: Increase the level of logging detail.

    # Enable verbose logging (can be stacked: -v, -vv, -vvv)
    dochia test ... -vv

  • Timestamped Reports: Save reports in a timestamped sub-folder.

    dochia test ... --timestamp-reports

See Also​