Skip to main content

dochia list

The list command displays various types of information about Dochia's capabilities and your OpenAPI specifications. Use it to explore available playbooks, API paths, mutators, and supported formats.

Basic Usage​

dochia list [OPTIONS]

Available Listing Options​

The list command can display different types of information:

OptionDescription
-p, --pathsList OpenAPI contract paths
-f, --playbooksList available playbooks
-m, --mutatorsList available mutators
--cmt, --customMutatorTypesList custom mutator types
-s, --fieldsPlaybookStrategiesList field fuzzing strategies
--formatsList supported OpenAPI formats

Listing OpenAPI Paths​

Basic Path Listing​

# List all paths from an OpenAPI spec
dochia list --paths -c openapi.yml

# List paths in JSON format
dochia list --paths -c openapi.yml --json

Filtered Path Listing​

# Filter paths by tag
dochia list --paths -c openapi.yml --tag "user-management"

# Get detailed info about a specific path
dochia list --paths -c openapi.yml --path "/api/users"

Example Output​

When listing paths in JSON format, you'll get a structure like:

{
  "numberOfPaths": 2,
  "numberOfOperations": 2,
  "pathDetailsList": [
    {
      "methods": ["POST"],
      "path": "/party/identities"
    },
    {
      "methods": ["POST"],
      "path": "/users"
    }
  ]
}

This provides:

  • Total count of API paths and operations
  • Each path with its supported HTTP methods

Listing Playbooks​

Available Playbooks​

# List all registered playbooks
dochia list --playbooks

# List playbooks in JSON format
dochia list --playbooks --json

Playbooks are the core testing strategies that Dochia uses. Common playbooks include:

  • EmptyStringsInFieldsPlaybook - Tests with empty string values
  • NullValuesInFieldsPlaybook - Tests with null values
  • VeryLargeStringsPlaybook - Tests with oversized strings
  • InvalidValuesInEnumsFieldsPlaybook - Tests enum fields with invalid values

Using Playbook Information​

The playbook list helps you:

  • Select specific playbooks for targeted testing with -P option
  • Skip unwanted playbooks with --skip-playbooks option
  • Understand test coverage by seeing all available test strategies
# Use specific playbooks from the list
dochia test -c api.yml -s http://localhost:8080 -P "EmptyStringsInFields,NullValuesInFields"

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

Listing Mutators​

Available Mutators​

# List all registered mutators
dochia list --mutators

# List mutators in JSON format
dochia list --mutators --json

Mutators are used by the dochia fuzz command for random input generation. They define different strategies for modifying request data.

Custom Mutator Types​

# List supported custom mutator types
dochia list --custom-mutator-types

# List in JSON format
dochia list --custom-mutator-types --json

This shows the types of custom mutators you can create for advanced fuzzing scenarios.

Listing Field Strategies​

Field Fuzzing Strategies​

# List all field fuzzing strategies
dochia list --fields-playbook-strategies

# List in JSON format
dochia list --fields-playbook-strategies --json

Field strategies determine how playbooks select and modify fields in requests:

  • ONEBYONE - Test one field at a time
  • SIZE - Test based on field size/count
  • ALL - Test all fields simultaneously

Listing Supported Formats​

OpenAPI Format Support​

# List all supported OpenAPI formats
dochia list --formats

# List in JSON format
dochia list --formats --json

This shows which OpenAPI data formats Dochia can generate test data for, such as:

  • email - Email address format
  • uuid - UUID format
  • date - Date format
  • date-time - DateTime format
  • uri - URI format

Output Formats​

Human-Readable Output​

By default, dochia list provides human-readable output:

dochia list --playbooks

JSON Output​

Use --json for machine-readable output:

dochia list --playbooks --json

JSON output is useful for:

  • Scripting - Parse results in automation scripts
  • Integration - Feed data into other tools
  • Analysis - Process large amounts of data programmatically

Practical Examples​

API Discovery​

# Explore a new API specification
dochia list --paths -c new-api.yml

# Focus on specific functionality
dochia list --paths -c new-api.yml --tag "authentication"

Test Planning​

# See all available playbooks for test planning
dochia list --playbooks

# Check field strategies for complex schemas
dochia list --fields-playbook-strategies

# Verify format support for your API
dochia list --formats

Automation Scripts​

#!/bin/bash
# Script to validate API coverage

echo "=== API Endpoints ==="
dochia list --paths -c api.yml --json | jq -r '.pathDetailsList[].path'

echo "=== Available Playbooks ==="
dochia list --playbooks --json | jq -r '.[].name'

echo "=== Supported Formats ==="
dochia list --formats --json | jq -r '.[]'

CI/CD Integration​

# Validate OpenAPI spec has expected paths
EXPECTED_PATHS="/users,/orders,/products"
ACTUAL_PATHS=$(dochia list --paths -c api.yml --json | jq -r '.pathDetailsList[].path' | tr '\n' ',' | sed 's/,$//')

if [[ "$ACTUAL_PATHS" == *"$EXPECTED_PATHS"* ]]; then
    echo "✓ All expected paths found"
else
    echo "✗ Missing expected paths"
    exit 1
fi

Advanced Usage​

Combining with Other Commands​

# List paths, then test specific ones
PATHS=$(dochia list --paths -c api.yml --json | jq -r '.pathDetailsList[].path' | head -5 | tr '\n' ',')
dochia test -c api.yml -s http://localhost:8080 --paths "$PATHS"

# List playbooks, then run specific subset
dochia list --playbooks --json | jq -r '.[].name' | grep -i "string" | head -3
dochia test -c api.yml -s http://localhost:8080 -P "EmptyStringsInFields,VeryLargeStrings"

Filtering and Processing​

# Find playbooks related to specific functionality
dochia list --playbooks --json | jq -r '.[] | select(.name | contains("String")) | .name'

# Get paths with specific HTTP methods
dochia list --paths -c api.yml --json | jq -r '.pathDetailsList[] | select(.methods[] == "POST") | .path'

# Count available resources
echo "Total playbooks: $(dochia list --playbooks --json | jq '. | length')"
echo "Total paths: $(dochia list --paths -c api.yml --json | jq '.numberOfPaths')"

Integration Examples​

Test Configuration Generation​

#!/bin/bash
# Generate test configuration based on available resources

echo "# Auto-generated test configuration" > test-config.yml
echo "playbooks:" >> test-config.yml
dochia list --playbooks --json | jq -r '.[].name' | sed 's/^/  - /' >> test-config.yml

echo "paths:" >> test-config.yml
dochia list --paths -c api.yml --json | jq -r '.pathDetailsList[].path' | sed 's/^/  - /' >> test-config.yml

Documentation Generation​

# Generate API documentation from OpenAPI spec
dochia list --paths -c api.yml --json | jq -r '.pathDetailsList[] | "- **\(.path)** (\(.methods | join(", ")))"' > api-endpoints.md

Troubleshooting​

Common Issues​

No paths found:

# Check if contract file exists and is valid
dochia list --paths -c api.yml
# Error: Contract file not found or invalid

Empty playbook list:

# This shouldn't happen - indicates installation issue
dochia list --playbooks
# If empty, reinstall Dochia

Permission errors:

# Ensure you have read access to the contract file
ls -la api.yml
chmod 644 api.yml

Exit Codes​

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

See Also​