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
--profilesList available run profiles (built-in and custom)
-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 Profiles​

Available Profiles​

# List all built-in and custom profiles
dochia list --profiles

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

Profiles group playbooks into named, reusable test suites. The output shows each profile's name, description, and the playbooks it includes.

Example Output​

◼ health-check
 (Minimal health check to verify API endpoints are reachable and responding): [HappyPath]

◼ quick
 (Fast smoke test covering critical test scenarios): [HappyPath, RemoveFields, NullValuesInFields, ...]

◼ ci
 (Balanced test suite optimized for CI/CD pipelines): [HappyPath, DefaultValuesInFields, ...]

◼ security
 (Security-focused playbooks targeting OWASP vulnerabilities and attack vectors): [SqlInjectionInStringFields, ...]

◼ compliance
 (OWASP API Security Top 10 compliance testing): [InsecureDirectObjectReferences, ...]

◼ type-coercion
 (Type coercion-focused playbooks): [CoercionBooleanStringInBooleanFields, ...]

◼ full
 (Complete test suite - all playbooks enabled (default behavior)): []

Built-in Profiles Reference​

ProfileDescriptionPlaybook count
health-checkMinimal check — HappyPath only1
quickFast smoke test for critical scenarios~20
ciBalanced suite for CI/CD~44
securityOWASP-focused security testing~31
complianceOWASP API Top 10 compliance~43
type-coercionType coercion edge cases11
fullAll playbooks (default)all

Using Profile Information​

# Run a specific profile
dochia test -c api.yml -s http://localhost:8080 --profile security

# Use the health-check shorthand
dochia test -c api.yml -s http://localhost:8080 --health-check

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
  • Build custom profiles by choosing playbooks from this list
# 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
2Usage error or internal error (invalid arguments, missing files, internal fault)

See Also​