Skip to main content

Your First Test

This guide will walk you through running your first API test with Dochia. You'll learn how to execute negative and boundary tests against your API using Dochia's 100+ playbooks.

Prerequisites​

Before running your first test, ensure you have:

  1. Dochia installed - See Installation Guide
  2. An OpenAPI specification - Your API contract in YAML or JSON format
  3. A running API server - The service you want to test

Basic Test Command​

The simplest way to run a test is with the basic command structure:

dochia test --contract <your-api-spec.yaml> --server <your-api-url>

Example: Testing a Local API​

# Test a local API running on port 8080
dochia test --contract openapi.yaml --server http://localhost:8080

Example: Testing a Remote API​

# Test a remote API
dochia test --contract api-spec.json --server https://api.example.com

Understanding the Output​

When you run a test, Dochia will:

  1. Parse your OpenAPI spec - Analyze endpoints, parameters, and schemas
  2. Generate test cases - Create negative and boundary tests using 100+ playbooks
  3. Execute tests - Send requests to your API server
  4. Generate reports - Create detailed HTML reports in the dochia-report/ folder

Sample Output​

Starting dochia-cli-1.0.1, build time 2025-08-12T14:34:53Z UTC

🧪 Running tests...
   /public/events ................................................... E 99, W 4, S 82 ✔

☑ 185 tests completed in 2.354s
   ✔ 82 passed, ⚠ 4 warnings, ⨯ 99 errors

☑ Full Report: file:///Users/dochia-fan/openapi-project/dochia-report/index.html

Dry Run - Preview Without Execution​

Before running actual tests, use --dry-run to see what Dochia will test:

# Preview test execution without making requests
dochia test --contract openapi.yaml --server http://localhost:8080 --dry-run

This will show how many tests will be executed per path.

Common Test Scenarios​

1. Testing with Authentication​

If your API requires authentication, use headers:

# Using API key authentication
dochia test --contract openapi.yaml --server http://localhost:8080 \
  --header "Authorization=Bearer your-jwt-token"

# Using environment variables
dochia test --contract openapi.yaml --server http://localhost:8080 \
  --header "API-Key=$API_TOKEN"

2. Testing Specific Endpoints​

Test only specific paths instead of all endpoints:

# Test only user-related endpoints
dochia test --contract openapi.yaml --server http://localhost:8080 \
  --paths "/users,/users/{id}"

3. Testing Specific HTTP Methods​

Focus on particular HTTP methods:

# Test only POST and PUT operations
dochia test --contract openapi.yaml --server http://localhost:8080 \
  --http-methods "POST,PUT"

4. Blackbox Testing​

Run in blackbox mode to only report server errors (5XX codes):

# Only report 500-level errors
dochia test --contract openapi.yaml --server http://localhost:8080 --blackbox

Playbook Categories​

Dochia organizes tests into different categories:

Body Playbooks​

Test request body validation and handling:

# Run only body-related tests
dochia test --contract openapi.yaml --server http://localhost:8080 --body-only

Header Playbooks​

Test HTTP header handling:

# Run only header-related tests
dochia test --contract openapi.yaml --server http://localhost:8080 --headers-only

Field Playbooks​

Test individual field validation:

# Run only field-related tests
dochia test --contract openapi.yaml --server http://localhost:8080 --fields-only

Configuration Files​

For complex scenarios, use configuration files:

Custom Headers File​

Create a headers.yaml file:

/users:
  Authorization: Bearer token123
  Content-Type: application/json
/orders:
  API-Key: your-api-key

Use it in your test:

dochia test --contract openapi.yaml --server http://localhost:8080 \
  --headers headers.yaml

Reference Data File​

Create a reference-data.yaml for required field values:

/users:
  tenantId: "test-tenant"
  organizationId: "org-123"

Use it in your test:

dochia test --contract openapi.yaml --server http://localhost:8080 \
  --reference-data reference-data.yaml

Rate Limiting and Timeouts​

Configure request timing to respect API limits:

# Limit to 100 requests per minute with custom timeouts
dochia test --contract openapi.yaml --server http://localhost:8080 \
  --max-requests-per-minute 100 \
  --connection-timeout 30 \
  --read-timeout 30

Viewing Results​

After test execution, Dochia generates comprehensive reports:

HTML Report​

Open dochia-report/index.html in your browser to see:

  • Test execution summary
  • Detailed results for each test case
  • Failed requests with full request/response details
  • Playbook coverage information

Console Output​

Use verbosity flags for more detailed console output:

# Increase verbosity for detailed logging
dochia test --contract openapi.yaml --server http://localhost:8080 -vvv

Exit Codes​

Dochia uses specific exit codes to indicate results:

  • 0 - All tests passed successfully
  • 191 - Usage error (incorrect command syntax)
  • 192 - Internal execution error
  • N - Number of errors found (e.g., exit code 5 means 5 errors)

Troubleshooting Common Issues​

Connection Refused​

Error: Connection refused to http://localhost:8080

Solution: Ensure your API server is running and accessible.

Invalid OpenAPI Spec​

Error: Unable to parse OpenAPI specification

Solution: Validate your OpenAPI spec using online validators.

Authentication Failures​

Warning: Many 401/403 responses detected

Solution: Check your authentication headers and credentials.

Rate Limiting​

Warning: Many 429 responses detected

Solution: Reduce request rate with --max-requests-per-minute.

Next Steps​

Now that you've run your first test:

  1. Explore CLI Commands - Learn about all available commands
  2. Understand Basic Concepts - Deep dive into how Dochia works
  3. View Examples - See real-world testing scenarios
  4. Advanced Configuration - Customize Dochia for complex APIs

Quick Reference​

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

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

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

# Blackbox mode
dochia test -c api.yaml -s http://localhost:8080 --blackbox

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

# Custom output location
dochia test -c api.yaml -s http://localhost:8080 --output my-reports/