Basic Concepts

Understanding Dochia's core concepts will help you effectively test your APIs and interpret the results. This guide covers the fundamental principles behind Dochia's testing approach.

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 (which you likely already do), Dochia focuses on finding edge cases, security vulnerabilities, and robustness issues in your API.

Core Testing Philosophy

Negative Testing

Dochia sends intentionally malformed, invalid, or unexpected requests to your API to verify:

• Input validation is working correctly
• Error handling is robust
• Security boundaries are enforced
• The API fails gracefully under stress

Boundary Testing

Dochia tests the limits and edge cases of your API by:

• Sending values at the exact boundaries of constraints
• Testing with extreme values (very large, very small)
• Exploring format edge cases
• Validating constraint enforcement

Two Testing Modes

Dochia offers two distinct testing approaches:

1. Deterministic Testing (dochia test)

Uses predefined playbooks - systematic, repeatable test cases that target specific vulnerability patterns.

Characteristics:

• Predictable - Same results every time
• Comprehensive - Covers 100+ known vulnerability patterns
• Systematic - Methodically tests each field, header, and endpoint
• Reproducible - Perfect for CI/CD pipelines

When to use:

• Regular regression testing
• CI/CD integration
• Compliance and security audits
• Systematic API validation

2. Random Testing (dochia fuzz)

Uses random mutators - unpredictable test cases that generate random invalid data.

Characteristics:

• Unpredictable - Different results each run
• Exploratory - May discover unexpected edge cases
• Continuous - Can run indefinitely
• Serendipitous - Might find issues playbooks miss

When to use:

• Continuous testing during development
• Discovering unknown edge cases
• Stress testing
• Exploratory security testing

Playbooks: Deterministic Test Cases

Playbooks are predefined test scenarios that systematically test specific vulnerability patterns. Dochia includes 100+ playbooks organized into three categories:

Field Playbooks (72 playbooks)

Test individual request fields and their validation. Examples include:

Boundary Testing:

• IntegerFieldsLeftBoundaryPlaybook - Tests minimum value boundaries
• StringFieldsRightBoundaryPlaybook - Tests maximum length boundaries
• DecimalFieldsLeftBoundaryPlaybook - Tests floating-point boundaries
• MaximumExactNumbersInNumericFieldsPlaybook - Tests exact maximum values
• MinLengthExactValuesInStringFieldsPlaybook - Tests exact minimum lengths

Type Confusion:

• StringsInNumericFieldsPlaybook - Sends strings to numeric fields
• DecimalNumbersInIntegerFieldsPlaybook - Sends decimals to integer fields
• RandomStringsInBooleanFieldsPlaybook - Sends strings to boolean fields
• ReplaceObjectsWithPrimitivesFieldsPlaybook - Replaces objects with primitives

Unicode and Encoding:

• AbugidasInStringFieldsSanitizeValidatePlaybook - Tests Unicode script handling
• ZalgoTextInFieldsSanitizeValidatePlaybook - Tests with corrupted text
• OnlyMultiCodePointEmojisInFieldsTrimValidatePlaybook - Tests emoji handling
• BidirectionalOverrideFieldsPlaybook - Tests bidirectional text attacks
• ZeroWidthCharsInValuesFieldsSanitizeValidatePlaybook - Tests invisible characters

Injection and Security:

• NullValuesInFieldsPlaybook - Tests null value handling
• VeryLargeStringsInFieldsPlaybook - Tests buffer overflow protection
• DuplicateKeysFieldsPlaybook - Tests JSON parsing ambiguities
• AdditionalPropertiesMassAssignmentFieldsPlaybook - Tests mass assignment vulnerabilities
• InvalidValuesInEnumsFieldsPlaybook - Tests enum validation bypass

...and 50+ more field playbooks covering edge cases, validation bypass, and security vulnerabilities.

Header Playbooks (34 playbooks)

Test HTTP header handling and validation. Examples include:

Content Negotiation:

• DummyAcceptHeadersPlaybook - Tests unsupported Accept headers
• DummyContentTypeHeadersPlaybook - Tests invalid Content-Type headers
• UnsupportedAcceptHeadersPlaybook - Tests content negotiation
• UnsupportedContentTypesHeadersPlaybook - Tests unsupported media types

Security Headers:

• CheckSecurityHeadersPlaybook - Validates security header presence
• ResponseHeadersMatchContractHeadersPlaybook - Validates response headers

Header Manipulation:

• LargeNumberOfRandomHeadersPlaybook - Tests with 10,000 random headers
• DuplicateHeadersPlaybook - Tests duplicate header handling
• RemoveHeadersPlaybook - Tests missing required headers
• ExtraHeadersPlaybook - Tests unexpected extra headers
• EmptyStringsInHeadersPlaybook - Tests empty header values
• VeryLargeStringsInHeadersPlaybook - Tests oversized header values

...and 20+ more header playbooks covering encoding issues, injection attacks, and protocol violations.

Body Playbooks (28 playbooks)

Test request body structure and content. Examples include:

JSON Structure:

• MalformedJsonPlaybook - Tests malformed JSON handling
• EmptyJsonBodyPlaybook - Tests empty JSON objects
• DummyRequestPlaybook - Tests unexpected JSON structure
• EmptyJsonArrayBodyPlaybook - Tests empty JSON arrays
• NullBodyPlaybook - Tests null request bodies
• RandomDummyInvalidJsonBodyPlaybook - Tests invalid JSON structures

HTTP Methods:

• HttpMethodsPlaybook - Tests undocumented HTTP methods
• CustomHttpMethodsPlaybook - Tests non-standard HTTP methods
• NonRestHttpMethodsPlaybook - Tests WebDAV methods

Authentication and Authorization:

• BypassAuthenticationPlaybook - Tests authentication bypass
• DeletedResourcesNotAvailablePlaybook - Tests resource lifecycle
• RandomResourcesPlaybook - Tests with random resource identifiers

...and 13+ more body playbooks covering various payload types, encoding issues, and protocol testing.

Mutators: Random Test Cases

Mutators are random data generators that create unpredictable test inputs. Dochia includes 25+ mutators. Examples include:

String Mutators

• BigListOfNaughtyStringsMutator - Uses known problematic strings
• RandomStringMutator - Generates random Unicode strings
• RandomAlphanumericStringMutator - Generates alphanumeric strings
• RandomZalgoTextMutator - Generates corrupted text
• RandomLanguageIdentifiersMutator - Uses programming language keywords
• NullStringMutator - Replaces fields with null values

Numeric Mutators

• RandomLargeIntegersMutator - Generates very large integers
• RandomLargeDecimalsMutator - Generates very large decimals
• RandomMaxValuesMutator - Uses maximum type values
• RandomMinValuesMutator - Uses minimum type values
• RandomNumberMutator - Generates random long numbers

Header Mutators

• RandomAcceptHeaderMutator - Random Accept headers
• RandomContentTypeHeaderMutator - Random Content-Type headers
• RandomTransferEncodingHeaderMutator - Random Transfer-Encoding headers

Special Character Mutators

• RandomControlCharsMutator - Injects control characters
• RandomMultiCodepointEmojisMutator - Injects complex emojis
• RandomWhitespaceCharsMutator - Injects whitespace characters
• RandomAbugidasMutator - Injects abugida script characters
• RandomControlCharsInFieldKeysMutator - Injects control chars in field names

...and 10+ more mutators covering case transformation, payload manipulation, and field removal.

Test Execution Flow

1. Contract Analysis

Dochia parses your OpenAPI specification to understand:

• Available endpoints and HTTP methods
• Request/response schemas
• Field types and constraints
• Required vs optional parameters

2. Test Generation

For dochia test:

• Selects applicable playbooks based on your API structure
• Generates test cases for each endpoint/field combination
• Creates systematic test matrix

For dochia fuzz:

• Applies random mutators to valid requests
• Generates unpredictable test variations
• Continues until stopped or time limit reached

3. Test Execution

• Sends generated requests to your API server
• Captures responses (status codes, headers, body)
• Measures response times
• Records any errors or timeouts

4. Result Analysis

• Compares actual responses to expected responses
• Identifies potential security issues
• Flags unexpected behaviors
• Generates detailed reports

Understanding Test Results

Success ✔

The API handled the invalid input correctly:

• Returned appropriate error codes (4XX)
• Provided meaningful error messages
• Maintained security boundaries

Warning ⚠

The API's response was unexpected but not necessarily wrong:

• Undocumented response codes
• Missing security headers
• Unusual response patterns

Error ⨯

The API failed to handle invalid input properly:

• Server errors (5XX) from bad input
• Information leakage in error messages
• Security vulnerabilities
• Crashes or timeouts

Key Benefits

Comprehensive Coverage

• 100+ playbooks cover known vulnerability patterns
• 25+ mutators generate unlimited test variations
• Systematic testing of every field, header, and endpoint

Security Focus

• Validates input sanitization
• Checks authentication bypass
• Identifies information leakage

Developer Friendly

• No test writing required - works directly from OpenAPI specs
• Detailed reports with reproduction steps
• CI/CD integration ready
• Configurable for different testing needs

Next Steps

Now that you understand Dochia's concepts:

1. Run Your First Test - Get hands-on experience
2. Explore CLI Commands - Learn all available options
3. View Examples - See real-world scenarios
4. Advanced Configuration - Customize for complex APIs

Quick Comparison

Aspect	dochia test (Playbooks)	dochia fuzz (Mutators)
Predictability	Deterministic, repeatable	Random, varies each run
Coverage	Systematic, comprehensive	Exploratory, serendipitous
Use Case	CI/CD, regression testing	Development, discovery
Duration	Fixed (based on API size)	Continuous (until stopped)
Results	Consistent, comparable	Variable, surprising

Both approaches complement each other - use playbooks for systematic validation and mutators for continuous exploration.