Skip to main content

Frequently Asked Questions

Common questions about Dochia and API testing with answers to help you get started quickly.

General Questions​

What is Dochia?​

Dochia is an API testing tool that automatically generates and executes negative and boundary tests from your OpenAPI specification. Instead of testing happy paths, Dochia focuses on finding edge cases, security vulnerabilities, and robustness issues in your API.

How is Dochia different from other API testing tools?​

  • Automatic test generation - No manual test writing required
  • Negative testing focus - Tests what happens when things go wrong
  • 100+ playbooks - Systematic coverage of known vulnerability patterns
  • Native binary - No Java runtime required, fast startup
  • OpenAPI-first - Works directly with your API specifications

Is Dochia free to use?​

Yes! Dochia has a free open source version that includes all core testing functionality. The free version provides comprehensive API testing capabilities for most use cases.

What's the difference between dochia test and dochia fuzz?​

  • dochia test - Uses deterministic playbooks for systematic, repeatable testing
  • dochia fuzz - Uses random mutators for exploratory, unpredictable testing

Both approaches complement each other for comprehensive API testing.

Installation and Setup​

What platforms does Dochia support?​

  • Full support: macOS (Intel/Apple Silicon), Linux (x86_64/ARM64)
  • Limited support: Windows (via WSL recommended)
  • Container support: Docker on all platforms

How do I install Dochia?​

Homebrew (recommended):

brew install dochia-dev/tap/dochia-cli

Direct download: Download binaries from GitHub releases

Docker:

docker pull dochiadev/dochia-cli:latest

See our Installation Guide for detailed instructions.

Do I need Java installed?​

No! Dochia is distributed as native binaries compiled with GraalVM. No Java runtime is required.

Can I run Dochia in CI/CD?​

Absolutely! Dochia is designed for CI/CD integration:

# Example CI command
dochia test -c api.yaml -s http://localhost:8080 --hide-success

Exit codes indicate test results (0 = success, >0 = number of errors).

Usage and Configuration​

What do I need to get started?​

Just two things:

  1. OpenAPI specification (YAML or JSON)
  2. Running API server to test against

Then run:

dochia test -c your-api.yaml -s http://your-server:8080

What OpenAPI versions are supported?​

  • Supported: OpenAPI 3.0, 3.1, and Swagger 2.0
  • Format: YAML or JSON
  • Not supported: RAML, API Blueprint, other specification formats

How do I test APIs that require authentication?​

Use headers for authentication:

# Bearer token
dochia test -c api.yaml -s http://localhost:8080 \
  --header "Authorization=Bearer your-token"

# API key
dochia test -c api.yaml -s http://localhost:8080 \
  --header "X-API-Key=your-key"

# Basic auth
dochia test -c api.yaml -s http://localhost:8080 \
  --user "username:password"

For token refresh, use:

dochia test -c api.yaml -s http://localhost:8080 \
  --header "Authorization=auth_script" \
  --auth-refresh-script "get-token.sh" \
  --auth-refresh 300

How do I test only specific endpoints?​

Use the --paths parameter:

# Test specific paths
dochia test -c api.yaml -s http://localhost:8080 \
  --paths "/users,/orders"

# Test specific HTTP methods
dochia test -c api.yaml -s http://localhost:8080 \
  --http-methods "POST,PUT"

How do I limit the number of tests?​

Several options:

# Limit fields tested per playbook
dochia test -c api.yaml -s http://localhost:8080 \
  --max-tested-fields 50

# Test specific playbooks only
dochia test -c api.yaml -s http://localhost:8080 \
  --playbooks "NullValuesInFields,EmptyStringsInFields"

# Skip heavy playbooks
dochia test -c api.yaml -s http://localhost:8080 \
  --skip-playbooks "VeryLargeStrings,LargeNumberOfRandomHeaders"

Testing and Results​

What types of tests does Dochia run?​

Dochia runs 100+ playbooks in three categories:

Field Playbooks (72):

  • Boundary testing (min/max values)
  • Type confusion (strings in numeric fields)
  • Unicode and encoding issues
  • Injection and security tests

Header Playbooks (34):

  • Content negotiation
  • Security headers validation
  • Header manipulation attacks

Body Playbooks (28):

  • JSON structure validation
  • HTTP method testing
  • Authentication bypass attempts

How do I interpret test results?​

  • ✔ Success - API handled invalid input correctly
  • ⚠ Warning - Unexpected but not necessarily wrong response
  • ⨯ Error - API failed to handle invalid input (2XX instead of 4XXX, 5XX error, security issue, etc.)

Where are the test reports?​

Reports are generated in the dochia-report/ folder:

  • HTML report: dochia-report/index.html
  • Detailed results: Individual test case details in html and json formats
  • Summary: Overall test execution statistics

How do I reduce report size?​

# Hide successful tests
dochia test -c api.yaml -s http://localhost:8080 --hide-success

# Use lightweight HTML format
dochia test -c api.yaml -s http://localhost:8080 \
  --output-format HTML_ONLY

Can I preview tests without running them?​

Yes! Use dry-run mode:

dochia test -c api.yaml -s http://localhost:8080 --dry-run

This shows how many tests will be executed without making actual requests.

Performance and Troubleshooting​

Dochia seems slow or stuck. What should I do?​

Common causes and solutions:

Too many fields:

dochia test -c api.yaml -s http://localhost:8080 \
  --max-tested-fields 50

Complex schema combinations:

dochia test -c api.yaml -s http://localhost:8080 \
  --max-schema-combinations 10

Self-referencing schemas:

dochia test -c api.yaml -s http://localhost:8080 \
  --self-reference-depth 3

How do I debug issues?​

  1. Increase verbosity:

    dochia test -c api.yaml -s http://localhost:8080 -vvv

  2. Check environment:

    dochia info

  3. Validate your API spec:

    dochia list --paths -c api.yaml

Dochia generates too many tests. How do I reduce them?​

Use filtering options:

# Combine multiple filters
dochia test -c api.yaml -s http://localhost:8080 \
  --paths "/users" \
  --http-methods "POST,PUT" \
  --max-tested-fields 20 \
  --skip-playbooks "VeryLargeStrings"

My API returns many 4XX errors. Is this normal?​

Yes! This is expected behavior. Dochia sends intentionally invalid requests to test your API's validation. 4XX responses indicate your API is correctly rejecting bad input.

Concerning responses:

  • 5XX errors from invalid input (should be 4XX)
  • 200 responses to clearly invalid data
  • Information leakage in error messages

Advanced Usage​

How do I provide custom data for testing?​

Use reference data files:

# reference-data.yaml
/users:
  tenantId: "test-tenant"
  organizationId: "org-123"
dochia test -c api.yaml -s http://localhost:8080 \
  --reference-data reference-data.yaml

How do I add custom headers for specific paths?​

Create a headers file:

# headers.yaml
/users:
  Authorization: Bearer token123
  X-Tenant-ID: tenant-123
/orders:
  X-API-Key: order-api-key
dochia test -c api.yaml -s http://localhost:8080 \
  --headers headers.yaml

Can I test APIs with custom formats?​

Yes! Dochia supports custom OpenAPI formats:

# In your OpenAPI spec
properties:
  currency:
    type: string
    format: currencyCode  # Generates USD, EUR, etc.
  country:
    type: string
    format: countryCode   # Generates US, GB, etc.

Use dochia list --field-formats to see all supported formats.

How do I handle rate limiting?​

# Limit requests per minute
dochia test -c api.yaml -s http://localhost:8080 \
  --max-requests-per-minute 100

# Increase timeouts
dochia test -c api.yaml -s http://localhost:8080 \
  --connection-timeout 30 \
  --read-timeout 30

Integration and Deployment​

How do I integrate Dochia with my CI/CD pipeline?​

Example GitHub Actions:

- name: Run API Tests
  run: |
    dochia test -c api.yaml -s http://localhost:8080 \
      --hide-success \
      --max-requests-per-minute 1000

Dochia's exit codes make CI integration easy:

  • 0 - All tests passed
  • >0 - Number of errors found

Can I run Dochia in Docker?​

Yes:

# Run with Docker
docker run --rm -v $(pwd):/workspace dochiadev/dochia-cli:latest \
  test -c /workspace/api.yaml -s http://localhost:8080

# Create alias for easier use
alias dochia='docker run --rm -v $(pwd):/workspace dochiadev/dochia-cli:latest'

How do I test APIs behind a proxy?​

dochia test -c api.yaml -s http://localhost:8080 \
  --proxy http://proxy.company.com:8080

Getting Help​

Where can I get help?​

  1. Documentation: docs.dochia.dev
  2. Troubleshooting: Troubleshooting Guide
  3. GitHub Issues: Report bugs
  4. GitHub Discussions: Ask questions

How do I report a bug?​

  1. Check existing issues
  2. Gather information:
    • dochia --version
    • dochia info
    • Command used and error output
  3. Create a new issue with details

How do I request a feature?​

Open a feature request with:

  • Problem description
  • Proposed solution
  • Use cases and examples
  • Alternative approaches considered

Can I contribute to Dochia?​

Absolutely! See our Community Guide for:

  • Code contributions
  • Documentation improvements
  • Bug reports
  • Feature requests
  • Community support

Quick Command Reference​

# Basic test
dochia test -c api.yaml -s http://localhost:8080

# With authentication
dochia test -c api.yaml -s http://localhost:8080 \
  -H "Authorization=Bearer token"

# Limit scope
dochia test -c api.yaml -s http://localhost:8080 \
  --paths "/users" --max-tested-fields 20

# Dry run
dochia test -c api.yaml -s http://localhost:8080 --dry-run

# Random fuzzing
dochia fuzz -c api.yaml -s http://localhost:8080

# List available options
dochia list --paths -c api.yaml
dochia list --playbooks
dochia list --field-formats

# Get help
dochia --help
dochia test --help
dochia info

Still have questions? Check our documentation or ask in GitHub Discussions!