dochia explain

The explain command provides detailed information about playbooks, mutators, response codes, and error reasons. Use it to understand what specific components do and why certain behaviors occur during testing.

Basic Usage

dochia explain --type <type> <info>

Required Parameters

• -t, --type=<type> - The type of information to explain
• <info> - The specific item you want explained

Available Types

The --type parameter accepts one of these values:

Type	Description	Example Info
playbook	Explain how a specific playbook works	EmptyStringsInFieldsPlaybook
mutator	Explain what a mutator does	RandomLargeDecimalsMutator
response_code	Explain custom response codes (9XX)	953
error_reason	Explain error reasons from test results	"Error details leak"

Explaining Playbooks

Basic Playbook Information

# Get details about a specific playbook
dochia explain --type playbook EmptyStringsInFieldsPlaybook

# Explain field-related playbooks
dochia explain --type playbook NullValuesInFieldsPlaybook
dochia explain --type playbook VeryLargeStringsPlaybook

# Explain header playbooks
dochia explain --type playbook LargeNumberOfRandomHeadersPlaybook

Common Playbooks to Explain

Use dochia list --playbooks first to see available playbooks, then explain specific ones:

# List all playbooks
dochia list --playbooks

# Explain specific playbooks based on the list
dochia explain --type playbook InvalidValuesInEnumsFieldsPlaybook

Understanding Playbook Behavior

The explanation typically includes:

• Purpose - What the playbook tests for
• Strategy - How it modifies requests
• Expected Results - What responses indicate success/failure
• Use Cases - When this playbook is most valuable

Explaining Mutators

Basic Mutator Information

# Get details about specific mutators
dochia explain --type mutator NullStringMutator
dochia explain --type mutator RandomLargeDecimalsMutator
dochia explain --type mutator RemoveFieldMutator

Finding Mutators to Explain

# List available mutators first
dochia list --mutators

# Then explain specific ones
dochia explain --type mutator RemoveFieldMutator
dochia explain --type mutator NullStringMutator

Mutator Explanations Include

• Input Types - What data types the mutator works with
• Mutation Strategies - How it modifies values
• Randomization - What kind of random changes it makes
• Usage Context - When it's used in fuzzing

Explaining Response Codes

Custom Response Codes (9XX)

Dochia uses custom 9XX response codes to indicate specific test conditions:

# Explain custom response codes
dochia explain --type response_code 953
dochia explain --type response_code 954
dochia explain --type response_code 957

Available Custom Response Codes

# Connection and protocol-related codes
dochia explain --type response_code 952  # Empty body - unexpected end of stream
dochia explain --type response_code 953  # Connection refused
dochia explain --type response_code 954  # Read timeout
dochia explain --type response_code 955  # Write timeout
dochia explain --type response_code 956  # Connection timeout
dochia explain --type response_code 957  # Protocol exception
dochia explain --type response_code 958  # Connection reset

Understanding Response Code Meanings

Response code explanations help you:

• Identify Issues - Understand what the code indicates
• Prioritize Fixes - Know the severity of different codes
• Debug Tests - Understand why certain tests failed
• Report Findings - Communicate issues to development teams

Explaining Error Reasons

Available Error Reasons

# Schema and contract validation errors
dochia explain --type error_reason "Not matching response schema"
dochia explain --type error_reason "Response content type not matching the contract"
dochia explain --type error_reason "Undocumented response code"
dochia explain --type error_reason "Unexpected response code"

# Implementation and functionality errors
dochia explain --type error_reason "Not implemented"
dochia explain --type error_reason "Not found"
dochia explain --type error_reason "Unexpected behaviour"

# Performance and system errors
dochia explain --type error_reason "Response time exceeds max"
dochia explain --type error_reason "Unexpected exception"

# Security and information disclosure
dochia explain --type error_reason "Error details leak"

Common Error Reason Categories

Contract Validation Errors:

• "Not matching response schema" - Response doesn't match OpenAPI schema
• "Response content type not matching the contract" - Wrong content type
• "Undocumented response code" - Response code not in OpenAPI spec
• "Unexpected response code" - Code documented but not expected for this test

Implementation Issues:

• "Not implemented" - Functionality not yet implemented
• "Not found" - Missing business context (may need --refData or --urlParams)
• "Unexpected behaviour" - Response doesn't match any known patterns

Performance Issues:

• "Response time exceeds max" - Exceeds --maxResponseTimeInMs limit

Security Concerns:

• "Error details leak" - Response exposes sensitive error information

System Issues:

• "Unexpected exception" - Internal Dochia error

Practical Examples

Debugging Test Results

# After running tests, explain unexpected results
dochia test -c api.yml -s http://localhost:8080

# If you see custom response codes in results, explain them
dochia explain --type response_code 953
dochia explain --type response_code 954

# If you see specific error reasons, get more details
dochia explain --type error_reason "Error details leak"
dochia explain --type error_reason "Not matching response schema"

Understanding Playbook Behavior

# Before running specific playbooks, understand what they do
dochia explain --type playbook EmptyStringsInFieldsPlaybook
dochia explain --type playbook NullValuesInFieldsPlaybook

# Then run them with better understanding
dochia test -c api.yml -s http://localhost:8080 -P "EmptyStringsInFields,NullValuesInFields"

Learning About Fuzzing

# Understand mutators before using fuzz command
dochia list --mutators
dochia explain --type mutator StringMutator
dochia explain --type mutator NumberMutator

# Then use fuzzing with better understanding
dochia fuzz -c api.yml -s http://localhost:8080 -p /users

Security Analysis

# Explain common test findings
dochia explain --type error_reason "Not implemented"
dochia explain --type error_reason "Not found"
dochia explain --type response_code 953

# Understand contract validation issues
dochia explain --type error_reason "Undocumented response code"
dochia explain --type error_reason "Not matching response schema"

Integration with Other Commands

Workflow Integration

#!/bin/bash
# Complete testing workflow with explanations

echo "=== Running Tests ==="
dochia test -c api.yml -s http://localhost:8080 -o ./results

echo "=== Analyzing Results ==="
# Extract unique response codes from results
CODES=$(grep -r '"responseCode"' results/ | grep -o '9[0-9][0-9]' | sort -u)

for code in $CODES; do
    echo "Explaining response code $code:"
    dochia explain --type response_code $code
    echo "---"
done

# Extract unique error reasons
ERROR_REASONS=$(grep -r '"errorReason"' results/ | cut -d'"' -f4 | sort -u)

for reason in $ERROR_REASONS; do
    echo "Explaining error reason: $reason"
    dochia explain --type error_reason "$reason"
    echo "---"
done

Learning and Documentation

#!/bin/bash
# Generate documentation for all playbooks

echo "# Playbook Documentation" > playbook-docs.md
echo "" >> playbook-docs.md

dochia list --playbooks --json | jq -r '.[].name' | while read playbook; do
    echo "## $playbook" >> playbook-docs.md
    echo "" >> playbook-docs.md
    dochia explain --type playbook "$playbook" >> playbook-docs.md
    echo "" >> playbook-docs.md
done

CI/CD Integration

# GitHub Actions example
- name: Analyze Test Results
  run: |
    # Run tests
    dochia test -c api.yml -s ${{ env.API_URL }} -o ./test-results
    
    # Explain any custom response codes found
    if grep -q '"responseCode": 9' test-results/*.json; then
      echo "Custom response codes found, generating explanations..."
      grep -h '"responseCode": 9[0-9][0-9]' test-results/*.json | \
        grep -o '9[0-9][0-9]' | sort -u | \
        while read code; do
          echo "## Response Code $code" >> explanations.md
          dochia explain --type response_code $code >> explanations.md
        done
    fi

Best Practices

When to Use Explain

1. Before Testing - Understand playbooks before running them
2. After Failures - Explain error reasons and response codes
3. Learning - Understand how different components work
4. Documentation - Generate explanations for team knowledge

Effective Usage Patterns

1. Start with Lists - Use dochia list to see available items
2. Explain Systematically - Work through related items together
3. Document Findings - Save explanations for future reference
4. Share Knowledge - Use explanations to educate team members

Integration Tips

1. Automate Explanations - Script explanations for common findings
2. Build Documentation - Generate team documentation from explanations
3. CI/CD Integration - Automatically explain test results
4. Learning Workflows - Create learning paths using explanations

Exit Codes

Code	Meaning
0	Successful execution
191	Usage error (incorrect arguments)
192	Internal execution error

Related Commands

• dochia list - List available playbooks, mutators, and other items
• dochia test - Run tests that generate results to explain
• dochia fuzz - Use mutators that can be explained
• dochia info - System information

See Also

• Playbooks Reference
• Understanding Test Results
• Troubleshooting
• Basic Concepts