Actions

Each test step executes one action: an HTTP request, a database query, a UI interaction, or a wait.

HTTP Request

{
  "action": {
    "type": "httpRequest",
    "method": "POST",
    "url": "api-gateway/api/users",
    "headers": {
      "Authorization": "Bearer {{token}}",
      "Content-Type": "application/json"
    },
    "body": {
      "name": "{{userName}}",
      "email": "{{email}}"
    }
  }
}

Field	Type	Required	Description
`type`	`"httpRequest"`	Yes	Action type
`method`	enum	Yes	`GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`
`url`	string	Yes	`service-name/path` format — service name resolves to internal DNS
`headers`	object	No	Request headers (values support `{{variables}}`)
`body`	any JSON	No	Request body (string values support `{{variables}}`)

Use service names, not ports. The url field uses the format service-name/path — just the item name and the route. Dokkimi handles DNS and port resolution internally. Don't include ports, protocols, or hostnames.

For example, if your service item is named api-gateway and listens on port 3000:

// Correct
"url": "api-gateway/api/users"

// Wrong — don't include ports or protocols
"url": "http://api-gateway:3000/api/users"

Parallel actions

Use the parallel action type to execute multiple actions simultaneously within a single step:

{
  "name": "Create both orders",
  "action": {
    "type": "parallel",
    "actions": [
      { "type": "httpRequest", "method": "POST", "url": "api-gateway/api/orders", "body": { "item": "widget" } },
      { "type": "httpRequest", "method": "POST", "url": "api-gateway/api/orders", "body": { "item": "gadget" } }
    ]
  }
}

All actions within parallel fire at the same time. Use this to test concurrent access patterns or to speed up independent setup steps. See Tests & Steps for more on parallel vs sequential execution.

Database Query

SQL databases (Postgres, MySQL)

{
  "action": {
    "type": "dbQuery",
    "database": "postgres-db",
    "query": "SELECT * FROM users WHERE email = '{{email}}'"
  }
}

MongoDB

For MongoDB, the query field must be a JSON string with a specific structure:

{
  "action": {
    "type": "dbQuery",
    "database": "mongo-db",
    "query": "{\"operation\":\"findOne\",\"collection\":\"orders\",\"filter\":{\"orderId\":\"ORD-001\"}}"
  }
}

Supported MongoDB operations:

Operation	Required fields
`find`, `findOne`	`collection`, `filter`
`insertOne`	`collection`, `document`
`insertMany`	`collection`, `documents`
`updateOne`, `updateMany`	`collection`, `filter`, `update`
`deleteOne`, `deleteMany`	`collection`, `filter`

Field	Type	Required	Description
`type`	`"dbQuery"`	Yes	Action type
`database`	string	Yes	Name of a DATABASE item in the definition
`query`	string	Yes	SQL query or MongoDB command JSON (supports `{{variables}}`)

UI Action

Drive a real Chromium browser to test user-facing flows. When a definition contains UI actions, Dokkimi automatically attaches a headless Chromium sidecar to the test environment.

{
  "action": {
    "type": "ui",
    "target": "web-app",
    "steps": [
      { "visit": "/posts/new" },
      { "waitFor": "[data-testid='post-form']" },
      { "type": { "selector": "#title", "text": "My new post" } },
      { "type": { "selector": "#body", "text": "Post content here." } },
      { "click": "[data-testid='publish-btn']" },
      { "waitFor": "[data-testid='success-toast']" },
      { "screenshot": "post-published" }
    ]
  }
}

Field	Type	Required	Description
`type`	`"ui"`	Yes	Action type
`target`	string	Yes	Name of a SERVICE item with a `uiPath` field.
`steps`	array	Yes	Ordered list of browser interactions to perform.

Available sub-steps

Each sub-step is an object with a single discriminator key. The key determines the sub-step type.

Key	Value	Description
`visit`	string (URL path)	Navigate to a path on the target service.
`click`	string (selector)	Click an element.
`type`	`{ selector, text }`	Type text into a field (clears first).
`select`	`{ selector, value }`	Select an option from a dropdown.
`hover`	string (selector)	Hover over an element.
`waitFor`	string or `{ selector, text? }`	Wait until an element appears. Optionally check for text content.
`screenshot`	string (name)	Capture a screenshot.
`scroll`	`{ x?, y? }`	Scroll the page by the given offset.
`key`	string (key name)	Press a keyboard key (e.g. `Enter`, `Escape`).
`upload`	`{ selector, files }`	Upload files to a file input.
`drag`	`{ source, target }`	Drag from one element to another.
`extract`	object	Extract values from the page into variables. Keys are variable names, values are source objects with `from`, `selector`, etc.
`viewport`	`{ width, height }`	Set browser viewport dimensions (pixels).

Visual regression with screenshots

Screenshots captured during a test run are saved as artifacts. To enable visual regression testing, add match: true to the screenshot sub-step:

{ "screenshot": "checkout-page", "match": true }

When match: true is set, Dokkimi compares the capture against a baseline stored in .dokkimi/<project>/baselines/. If no baseline exists yet (first run), or if the diff exceeds the threshold, it appears as a pending baseline. Review and approve pending baselines with dokkimi baselines.

Use data-testid selectors. CSS class selectors break when you restyle. Test IDs are stable and make your intent clear.

Wait

Pause execution for a specified duration. Useful for waiting for async operations to complete.

{
  "action": {
    "type": "wait",
    "durationMs": 2000
  }
}

Field	Type	Required	Description
`type`	`"wait"`	Yes	Action type
`durationMs`	integer	Yes	Duration to wait in milliseconds

← Tests & Steps Loops →