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

{
  "action": {
    "type": "ui",
    "url": "http://web-app:3000/posts/new",
    "subSteps": [
      { "action": "waitForSelector", "selector": "[data-testid=\"post-form\"]" },
      { "action": "fill", "selector": "#title", "value": "My new post" },
      { "action": "fill", "selector": "#body", "value": "Post content here." },
      { "action": "click", "selector": "[data-testid=\"publish-btn\"]" },
      { "action": "waitForSelector", "selector": "[data-testid=\"success-toast\"]" },
      { "action": "screenshot", "name": "post-published" }
    ]
  }
}

Field	Type	Required	Description
`type`	`"ui"`	Yes	Action type
`url`	string	Yes	The URL to navigate to. Use `http://service-name:port/path` format.
`subSteps`	array	Yes	Ordered list of browser interactions to perform.

Available sub-steps

Sub-step	Fields	Description
`click`	`selector`	Click an element.
`fill`	`selector`, `value`	Clear a field and type a value.
`type`	`selector`, `value`	Type text without clearing first.
`select`	`selector`, `value`	Select an option from a dropdown.
`hover`	`selector`	Hover over an element.
`waitForSelector`	`selector`	Wait until an element appears in the DOM.
`screenshot`	`name`	Capture a screenshot. Used for visual regression testing.
`scroll`	`x`, `y`	Scroll the page by the given offset.
`key`	`key`	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`	`selector`, `attribute`, `variable`	Extract a value from the page into a variable.
`viewport`	`width`, `height`	Set browser viewport dimensions (pixels). Persists across subsequent UI actions until changed.

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:

{ "action": "screenshot", "name": "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 Variables →