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. Fail on Errors:

    • Dochia exits with the number of errors, which will fail your CI job.
    • Use --blackbox (blackbox mode) 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. Run Targeted Tests:

    • Run a quick smoke test on every commit.
    • Run a full regression suite on a nightly or scheduled basis.

  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 Dynamic Data for Unique Resources:

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

  4. Version Control Your Configurations:

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

See Also​