Skip to main content

Getting Started

Welcome to Dochia CLI! This section will guide you through everything you need to know to start testing your APIs effectively. Whether you're new to API testing or experienced with other tools, these guides will help you get up and running quickly.

Learning Path​

Follow this recommended sequence to master Dochia fundamentals:

1. Installation​

Get Dochia CLI installed and ready to use on your system.

What you'll learn:

  • How to install Dochia via Homebrew
  • System requirements and compatibility
  • Verification of successful installation
  • Basic troubleshooting for installation issues

Prerequisites: None - start here!

2. Basic Concepts​

Understand the core concepts that make Dochia powerful and unique.

What you'll learn:

  • How Dochia approaches API testing differently
  • Understanding playbooks vs traditional testing
  • The role of OpenAPI specifications
  • Negative testing and boundary testing concepts
  • Security-first testing methodology

Prerequisites: Dochia installed

3. First Test​

Run your first API test and understand the results.

What you'll learn:

  • Execute your first comprehensive test
  • Understand test output and reports
  • Interpret results and findings
  • Basic command-line usage patterns
  • Common troubleshooting scenarios

Prerequisites: Basic concepts understood

Quick Start Guide​

For the Impatient​

If you want to jump straight in:

# Install Dochia
brew install dochia-dev/tap/dochia-cli

# Run your first test
dochia test --contract your-api.yml --server https://your-api.com

# View report
open ./dochia-report/index.html

For the Thorough​

Follow the complete learning path above for comprehensive understanding.

What Makes Dochia Different?​

Traditional API Testing​

  • Manual test case creation
  • Limited negative testing
  • Time-intensive maintenance
  • Reactive security testing

Dochia's Approach​

  • Automatic test generation from OpenAPI specs
  • 100+ built-in playbooks for comprehensive coverage
  • Security-first methodology with negative testing
  • Minimal maintenance - tests evolve with your API

Key Concepts Overview​

Playbooks​

Pre-defined testing strategies that systematically explore different aspects of your API:

  • Body Playbooks - Test request structure and format
  • Fields Playbooks - Validate individual field handling
  • Headers Playbooks - Examine HTTP header processing
  • Security Playbooks - Focus on authentication and authorization

OpenAPI Integration​

Dochia leverages your existing OpenAPI specifications to:

  • Understand your API structure automatically
  • Generate relevant test scenarios
  • Provide context-aware testing
  • Minimize configuration overhead

Negative Testing​

Unlike traditional "happy path" testing, Dochia focuses on:

  • Boundary conditions and edge cases
  • Invalid input handling
  • Error response validation
  • Security vulnerability discovery

Common First Steps​

1. Prepare Your API Specification​

# Ensure you have a valid OpenAPI spec
# Dochia supports OpenAPI 3.0+ specifications

2. Identify Your Target Environment​

# Development environment (recommended for first tests)
dochia test --contract api.yml --server https://dev-api.example.com

# Staging environment (for comprehensive testing)
dochia test --contract api.yml --server https://staging-api.example.com

3. Start with Basic Testing​

# Simple test execution
dochia test --contract api.yml --server https://api.example.com

# With authentication
dochia test --contract api.yml --server https://api.example.com \
  --header "Authorization=Bearer your-token"

What to Expect​

Your First Test Run​

  • Duration: Typically 1-5 minutes depending on API size
  • Output: Detailed HTML reports and JSON data
  • Findings: Comprehensive analysis of API behavior
  • Next Steps: Clear recommendations for improvements

Learning Curve​

  • Day 1: Basic test execution and result interpretation
  • Week 1: Understanding playbook selection and customization
  • Month 1: Advanced configuration and CI/CD integration

Success Metrics​

After completing the Getting Started section, you should be able to:

✅ Install and verify Dochia CLI on your system
✅ Execute basic tests against your API
✅ Interpret test results and identify issues
✅ Understand core concepts like playbooks and negative testing
✅ Navigate documentation to find advanced topics

Next Steps​

Once you've completed the Getting Started section:

  1. User Guide - Deep dive into all Dochia features
  2. Examples - See real-world usage scenarios
  3. Playbooks - Understand different testing strategies
  4. CLI Reference - Complete command documentation
  5. Advanced Topics - Expert-level configurations

Common Questions​

"Do I need to write test cases?"​

No! Dochia automatically generates comprehensive test cases from your OpenAPI specification.

"How long does testing take?"​

Most APIs complete testing in 1-5 minutes. Large APIs with hundreds of endpoints may take longer.

"Is it safe to test production APIs?"​

Dochia is designed for safe testing, but we recommend starting with development or staging environments.

"What if I don't have an OpenAPI spec?"​

You'll need an OpenAPI specification to use Dochia effectively. Consider generating one from your existing API.

Need Help?​

If you encounter issues during setup:

Resources​