Dokkimi

Integration, E2E, and visual regression testing for microservices — without changing your code.

Dokkimi spins up isolated Kubernetes sandboxes from simple YAML/JSON definitions. It deploys your services, databases, and mocks into dedicated namespaces, drives a real browser through your UI, intercepts all inter-service HTTP traffic, and runs automated test suites that assert on responses, traffic patterns, database state, and screenshots — all 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:

• E2E UI testing — drive a real Chromium browser alongside your services. Click, type, navigate, and assert on what the user sees.
• Visual regression — screenshot any step and diff against baselines. Catch visual regressions before they ship.
• 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, Auth0, etc.) and return controlled responses. No test accounts needed.
• Database seeding & queries — initialize Postgres, MySQL, MongoDB, or Redis with SQL/JS scripts, then query directly in assertions to verify writes.
• Isolated environments — each test run gets its own Kubernetes namespace with dedicated services, databases, and browser. No shared state, no conflicts.
• Variable extraction — extract values from responses 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 with Homebrew
brew install dokkimi/tap/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

# Review pending visual baselines
dokkimi baselines

What a Definition Looks Like

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

name: author-publish-flow
items:
  - $ref: ../shared/web-app.yaml
  - $ref: ../shared/api-gateway.yaml
  - $ref: ../shared/post-service.yaml
  - $ref: ../shared/postgres-db.yaml
  - $ref: ../shared/mock-auth0-jwks.yaml

steps:
  # Drive the browser through the publish flow
  - action:
      type: ui
      url: http://web-app:3000/posts/new
      subSteps:
        - action: fill
          selector: '#title'
          value: 'My new post'
        - action: click
          selector: '[data-testid="publish-btn"]'
        - action: waitForSelector
          selector: '[data-testid="success-toast"]'
        - action: screenshot
          name: post-published
    assertions:
      # Verify the API call went through correctly
      - match:
          origin: web-app
          method: POST
          url: api-gateway/v1/posts
        assertions:
          - path: response.status
            operator: eq
            value: 201

  # Confirm it was persisted
  - action:
      type: dbQuery
      database: postgres-db
      query: "SELECT title FROM posts WHERE title = 'My new post'"
    assertions:
      - assertions:
          - path: data[0].title
            operator: eq
            value: My new post

This single definition spins up a web app, API gateway, post service, Postgres database, and an Auth0 mock — then drives a browser through the publish flow, asserts on the inter-service HTTP call, and verifies the data was written to the database.

Services are defined as shared fragments and referenced with $ref — write once, reuse across all your test definitions. Refs are recursive: a fragment can $ref another fragment, building up inheritance chains with overrides at each level.

# .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

| Command | Description | | --------------------------- | ---------------------------------------------------- | | dokkimi init | Scaffold a .dokkimi/ folder with examples | | dokkimi run [target] | Run definition(s) and stream results | | dokkimi validate [target] | Validate definitions without running | | dokkimi inspect | Inspect traffic logs from the last run | | dokkimi baselines | Review and approve pending visual baselines | | dokkimi dump | Export last run as JSON for AI-assisted debugging | | dokkimi doctor | Check prerequisites and system health | | dokkimi status | Show whether Dokkimi is running | | dokkimi clean | Stop all instances and clean up resources | | dokkimi config | View and edit Dokkimi settings | | dokkimi reboot | Restart Dokkimi services | | dokkimi uninstall | Remove Dokkimi from your cluster | | dokkimi version | Show installed version |

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 — including UI actions, visual regression, and all assertion types.

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

Documentation

• Website
• Docs
• Tutorials
• Community

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.