Getting started with Dokkimi: your first test in 5 minutes

Prerequisites

You need three things:

• Node.js 20+
• Docker + Kubernetes — Docker Desktop with Kubernetes enabled is the easiest path. Rancher Desktop and minikube also work.
• kubectl — configured to talk to your local cluster.

Install and verify

npm install -g dokkimi
dokkimi doctor

dokkimi doctor checks that Docker is running, Kubernetes is reachable, and your cluster has enough resources. Fix anything it flags before continuing.

Scaffold example definitions

mkdir my-project && cd my-project
dokkimi init

This creates a .dokkimi/ folder with an example topology — a simple API gateway, a backend service, and a Postgres database.

.dokkimi/
  example/
    definitions/
      example-test.yaml
    shared/
      api-gateway.yaml
      backend-service.yaml
      postgres.yaml

Anatomy of a test definition

Open example-test.yaml. A test definition has three sections:

Items — the services, databases, and mocks that make up your test environment:

name: example-flow
items:
  - $ref: ../shared/api-gateway.yaml
  - $ref: ../shared/backend-service.yaml
  - $ref: ../shared/postgres.yaml

$ref lets you reuse service definitions across tests. You can also inline them.

Variables — values you can reference with {{variableName}} in actions and assertions:

variables:
  testEmail: "test@example.com"

Tests — the actual test cases, each with a sequence of steps:

tests:
  - name: Create and fetch a user
    steps:
      - - name: Create user
          action:
            type: httpRequest
            method: POST
            service: api-gateway
            path: /api/users
            body:
              email: "{{testEmail}}"
          assertions:
            - target: self
              assertions:
                - type: statusCode
                  operator: eq
                  value: 201

Steps are grouped in arrays — steps in the same inner array run in parallel, outer arrays run sequentially.

Run it

dokkimi run

Dokkimi will:

1. Create an isolated Kubernetes namespace.
2. Deploy your services with interceptor sidecars.
3. Seed any databases.
4. Wait for readiness checks to pass.
5. Execute your test steps.
6. Report results and tear everything down.

You’ll see real-time output as each step executes and assertions pass or fail.

Inspect traffic after a run

dokkimi inspect

This shows every HTTP call the interceptor captured during the last run — which service called which, what the request and response bodies were, and how long each call took. This is invaluable for debugging failures.

Next steps

• Read the full CLI reference for all available commands.
• Look at the $ref pattern for sharing service definitions across test files.
• Try adding a MOCK item to intercept calls to an external API.

Once you’re comfortable with the basics, check out how traffic interception works for a deeper look at what’s happening under the hood.