Skip to main content

Best Practices for Using Dochia

This guide provides best practices for using Dochia effectively, from preparing your OpenAPI specification to integrating with CI/CD and managing test data.

OpenAPI Specification Quality​

A high-quality OpenAPI spec is the foundation of effective testing with Dochia.

  1. Be Specific with Data Types and Formats:

    • Define format for strings (e.g., date-time, email, uuid).
    • Use enum for fields with a limited set of values.
    • Specify minLength, maxLength, minimum, and maximum constraints.

  2. Provide Examples:

    • Include example values for complex objects and required fields.
    • Use realistic examples to guide Dochia's test generation.

  3. Define Security Schemes:

    • Clearly define securitySchemes (e.g., OAuth 2.0, API Key, Basic Auth).
    • Apply security requirements to endpoints using the security keyword.

  4. Use Tags for Organization:

    • Group related endpoints with tags (e.g., users, products, orders).
    • Use tags to run tests on specific parts of your API.

Test Configuration​

Optimize your test runs with these configuration best practices.

  1. Start with a Dry Run:

    • Use --dry-run to preview tests without making requests.
    • Verify that Dochia is targeting the correct endpoints and generating valid payloads.

  2. Scope Your Tests:

    • Use --paths, --http-methods, and --tags to focus on specific areas.
    • Run targeted tests for faster feedback and easier debugging.

  3. Use External Configuration Files:

    • Manage headers, query parameters, and reference data in YAML files.
    • Keep your test commands clean and your configurations reusable.

  4. Leverage Reference Data:

    • Use --reference-data to provide required field values.
    • Use per-path overrides for context-specific data.
    • Use SpringEL for dynamic values (e.g., timestamps, UUIDs).

  5. Manage Authentication Securely:

    • Use environment variables for secrets ($$API_KEY).
    • Use --auth-refresh-script for dynamic token generation.
    • Use --mask-headers to hide sensitive data in reports.

CI/CD Integration​

Integrate Dochia into your CI/CD pipeline for automated testing.

  1. Control What Fails Your Pipeline:

    • Dochia exits with code 1 when errors are found (default) — your CI job fails automatically.
    • Use --fail-on error,warn to also fail on warnings, or --quality-gate "errors<5" to allow a small tolerance.
    • Use --blackbox to fail only on 5xx errors in non-production environments.

  2. Automate Installation:

    • Use a script to download and install the correct Dochia version.
    • Cache the binary to speed up subsequent runs.

  3. Use Profiles for Each Pipeline Stage:

    • Use --health-check as a post-deployment smoke test.
    • Use --profile quick or --profile ci on every commit for fast feedback.
    • Use --profile security or --profile compliance on nightly or scheduled runs.
    • Run dochia list --profiles to see all available built-in and custom profiles.

  4. Publish Reports:

    • Use --output to save reports to a specific directory.
    • Archive reports as build artifacts for later analysis.

Performance and Tuning​

Optimize Dochia's performance for your environment.

  1. Adjust Rate Limiting:

    • Use --max-requests-per-minute to avoid overwhelming your API.
    • Start with a conservative value and increase as needed.

  2. Configure Timeouts:

    • Use --connection-timeout, --read-timeout, and --write-timeout to handle slow responses.
    • Increase timeouts for long-running operations.

  3. Use Blackbox Mode:

    • Use --blackbox to ignore non-5xx errors when testing unstable environments.
    • Focus on critical server errors rather than expected validation failures.

  4. Monitor Performance:

    • Use --execution-stats to get performance metrics.
    • Identify slow endpoints and performance bottlenecks.

Test Data Management​

Manage your test data effectively for reliable and repeatable tests.

  1. Use a Test Data Seeding Script:

    • Run a script to populate your database with known test data before running Dochia.
    • Ensure your tests run against a consistent and predictable state.

  2. Clean Up After Tests:

    • Run a script to clean up created resources after tests complete.
    • Avoid polluting your test environment with leftover data.

  3. Use --seed for Reproducible Failures:

    • When a test run uncovers an issue, record the seed value from the run.
    • Re-run with --seed <value> to reproduce the exact same payload sequence for debugging.

  4. Use Dynamic Data for Unique Resources:

    • Use SpringEL expressions (${...}) to generate unique identifiers.
    • Avoid collisions and ensure tests are independent.

  5. Version Control Your Configurations:

    • Commit your reference data, headers, and query parameter files.
    • Keep your test configurations in sync with your codebase.

See Also​