Skip to main content

Limitations

While Dochia is a powerful API testing tool, there are some limitations to be aware of when using it in your testing workflows.

Native Binary Architecture​

Dochia is distributed exclusively as native binaries compiled with GraalVM, which provides excellent performance and eliminates the need for a Java runtime. However, this architecture introduces some constraints:

Dynamic Configuration Support​

When using dynamic values in configuration files (such as headers, reference data, or custom scripts), there might be limitations due to GraalVM's compile-time bundling approach. The following Java classes are currently supported for dynamic operations:

java.util.Base64.Encoder.class
java.util.Base64.Decoder.class
java.util.Base64.class
org.apache.commons.lang3.RandomUtils.class
org.apache.commons.lang3.RandomStringUtils.class
org.apache.commons.lang3.DateFormatUtils.class
org.apache.commons.lang3.DateUtils.class
org.apache.commons.lang3.DurationUtils.class
java.time.LocalDate.class
java.time.LocalDateTime.class
java.time.OffsetDateTime.class

Runtime Reflection​

Due to native compilation constraints, runtime reflection capabilities are limited to what can be determined at compile time. This may affect:

  • Custom authentication scripts that use reflection
  • Dynamic payload generation with complex object hierarchies
  • Runtime class loading for custom extensions

API Specification Support​

Dochia currently supports:

OpenAPI Specifications Only​

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

Specification Features​

  • Full Support: Standard OpenAPI features (paths, parameters, schemas, responses)
  • Partial Support: Complex oneOf/anyOf combinations (limited by --max-schema-combinations)
  • Limited Support: Custom extensions and vendor-specific OpenAPI features

Media Types and HTTP Methods​

Dochia's playbooks and mutators have specific support limitations:

Supported Media Types​

  • application/json - Full support for all playbooks and mutators
  • application/x-www-form-urlencoded - Limited support for form-based APIs

Supported HTTP Methods​

  • GET - Full support for query parameter and header testing
  • POST - Full support for all body, field, and header playbooks
  • PUT - Full support for all body, field, and header playbooks
  • PATCH - Full support including RFC 7396 merge-patch support
  • DELETE - Full support for parameter and header testing
  • HEAD - Limited support for header testing only
  • OPTIONS - Limited support for CORS testing
  • TRACE - Basic support for security testing

Unsupported Features​

  • Custom HTTP methods beyond standard REST verbs
  • WebDAV methods (except through specific playbooks)
  • HTTP/2 server push
  • WebSocket connections
  • Server-sent events (SSE)

Schema Validation Limitations​

Additional Properties​

When a response schema contains additionalProperties: true or free-form maps, Dochia will:

  • Issue warning messages in logs
  • Skip strict schema validation for those properties
  • Continue testing other defined properties normally

Complex Patterns​

Dochia uses regex-based generators for string pattern validation, which has limitations:

  • Supported: Basic regex patterns (character classes, quantifiers, anchors)
  • Limited: Complex lookahead/lookbehind assertions
  • Not Supported: Recursive patterns, complex backreferences
  • Workaround: Simplify patterns

Performance and Scale Limitations​

Request Volume​

  • Rate Limiting: Respects --max-requests-per-minute setting (default: 10,000)
  • Memory Usage: Native binaries have lower memory overhead but may hit limits with very large APIs
  • Concurrent Connections: Limited by system resources and target server capacity

API Size Constraints​

  • Large APIs: APIs with 1000+ endpoints may experience longer startup times
  • Deep Nesting: Schemas with deep object nesting (>10 levels) may cause performance issues
  • Large Payloads: Very large request/response examples may impact memory usage

Authentication and Security​

Supported Authentication​

  • Basic Auth: Full support via --user parameter
  • Bearer Tokens: Full support via --header parameter
  • API Keys: Full support via custom headers
  • Custom Headers: Full support for any header-based authentication

Limited Authentication Support​

  • OAuth Flows: Requires external token management, using --auth-refresh-script
  • Client Certificates: Basic support via --ssl-keystore parameters
  • Dynamic Token Refresh: Using --auth-refresh

Not Supported​

  • SAML: No built-in SAML support
  • Kerberos: No built-in Kerberos support
  • Complex OAuth: Multi-step OAuth flows require external handling

Workarounds and Alternatives​

For Complex Authentication​

# Use external token management and refresh every 60 seconds
dochia test -c api.yaml -s http://localhost:8080 \
  --header "Authorization=auth_script" --auth-refresh-script "get-auth-token.sh" --auth-refresh 60

For Large APIs​

# Test specific paths to reduce load
dochia test -c api.yaml -s http://localhost:8080 \
  --paths "/users,/orders" \
  --max-requests-per-minute 1000

Getting Help​

If you encounter limitations not covered here:

  1. Check Documentation: Review Advanced Configuration for workarounds
  2. GitHub Issues: Report limitations at dochia-cli issues
  3. Feature Requests: Request new features via GitHub issues
  4. Community: Join discussions for community solutions

Future Improvements​

The Dochia team is actively working on addressing these limitations:

  • Expanded media type support
  • Enhanced authentication methods
  • Improved pattern matching

Check the changelog for updates on limitation improvements.