Dokkimi

Test your microservices the way they actually run — in Kubernetes, with real traffic.

Dokkimi spins up isolated Kubernetes sandboxes from simple YAML/JSON definitions. It deploys your services, databases, and mocks into dedicated namespaces, intercepts all inter-service HTTP traffic, and runs automated test suites that assert on responses, traffic patterns, and console logs — without modifying your application code.

Why Dokkimi?

Testing microservices is hard. Unit tests mock away the interesting parts. Integration tests are flaky and slow to set up. Staging environments drift from reality.

Dokkimi gives you production-like test environments on demand:

• Isolated namespaces — each test run gets its own Kubernetes namespace with dedicated services and databases. No shared state, no conflicts.
• Traffic interception — an interceptor sidecar captures all HTTP traffic between services. Assert on exactly what service A sent to service B.
• Mock external APIs — intercept outbound requests to third-party services (Stripe, Twilio, etc.) and return controlled responses.
• Database seeding — initialize Postgres, MySQL, MongoDB, or Redis with SQL/JS scripts before tests run.
• Regex variable extraction — extract values from response fields using JSONPath + regex capture groups, then use them in subsequent steps.
• Parallel test execution — run steps in parallel within a test, and run multiple test definitions concurrently.
• No code changes required — your services run unmodified. Dokkimi handles the wiring.

Install

# Global install
npm install -g dokkimi

# Or as a project devDependency
yarn add -D dokkimi

Prerequisites

• Node.js 20+
• Docker Desktop with Kubernetes enabled
• kubectl

Run dokkimi doctor after installing to verify your setup.

Quick Start

# Scaffold a .dokkimi/ folder with example files
dokkimi init

# Validate your definitions
dokkimi validate

# Run tests
dokkimi run

# Inspect traffic from the last run
dokkimi inspect

What a Definition Looks Like

A .dokkimi/ folder contains YAML or JSON files that describe your test environment and assertions:

name: user-signup-flow
items:
  - $ref: ../shared/api-gateway.yaml
  - $ref: ../shared/user-service.yaml
  - $ref: ../shared/postgres-db.yaml
  - type: MOCK
    name: mock-stripe
    mockTarget: api.stripe.com
    mockPath: /v1/customers
    mockResponseStatus: 200
    mockResponseBody:
      id: cus_test_123
      email: test@example.com

tests:
  - name: Create user and verify Stripe customer created
    steps:
      - - name: POST /signup
          action:
            type: httpRequest
            method: POST
            url: api-gateway/signup
            body:
              email: test@example.com
              password: secret123
          assertions:
            - assertions:
                - path: response.status
                  operator: eq
                  value: 201
            - match:
                origin: user-service
                method: POST
                url: mock-stripe/v1/customers
              assertions:
                - path: request.body.email
                  operator: eq
                  value: test@example.com

Services are defined as shared fragments and referenced with $ref — write once, reuse across all your test definitions:

# .dokkimi/shared/api-gateway.yaml
type: SERVICE
name: api-gateway
image: ${{REGISTRY}}/api-gateway:${{IMAGE_TAG}}
port: 3000
healthCheck: /health
env:
  - name: DATABASE_URL
    value: postgresql://dokkimi:dokkimi@postgres-db:5432/dokkimi
  - name: USER_SERVICE_URL
    value: http://user-service:3000

Image tags and other values can be centralized in .dokkimi/config.yaml using ${{VAR}} syntax — change once, apply everywhere.

Commands

The [target] argument is flexible — pass a directory, a specific file, a glob pattern, or a substring to match definition names.

Built for AI-Assisted Development

Dokkimi is designed to work with AI coding agents out of the box:

• Auto-registers with your AI tools — on first run, Dokkimi installs context into Claude Code, Cursor, and GitHub Copilot so your AI assistant understands the .dokkimi/ definition format and can write definitions for you.
• AI-readable definition format — YAML/JSON definitions are structured data that LLMs can read, generate, and modify accurately. Ask your AI to "write a test definition for the checkout flow" and it just works.
• dokkimi dump — exports a complete JSON snapshot of your last run (traffic logs, test results, assertions, errors) formatted for LLM context. Paste it into your AI tool to debug failures without manually digging through logs.
• 1,000+ line reference spec — the full definition reference (dokkimi-instructions.md) is automatically available to your AI agent, covering every field, type, and pattern.

Your AI agent can write definitions, debug test failures, and iterate on your test suite — Dokkimi provides the context it needs.

Documentation

Full reference for writing .dokkimi/ definition files: ~/.dokkimi/dokkimi-instructions.md (installed automatically on first run).

License

Elastic License 2.0 — free to use, modify, and distribute. Cannot be offered as a managed service.