YAML Test Format Reference

Define a group of tests in YAML for version control, review and migration — the full schema, every step type, and how to import and export through the API.

Define a group of tests in YAML for version control, sharing, and migration. YAML files are imported and exported through the API; the dashboard has no YAML buttons. The API calls a group a suite.

Quick Start

Write a .yaml file in the format below.
Upload it with POST /api/v1/tests/suites/import-yaml (see Importing YAML).
The group and its tests appear on the Tests page.

VibeView YAML Schema

A VibeView YAML file defines one group with one or more tests:

name: Checkout Flow
description: End-to-end checkout with payment
appId: com.example.shop
platform: ios
resetStrategy: clear_data
context: The user is logged in and has items in the cart
variables:
  username: testuser@example.com
  promo_code: SAVE20

cases:
  - name: Standard Checkout
    steps:
      - Tap on the Cart tab
      - Tap "Proceed to Checkout"
      - Enter shipping address
      - Select "Credit Card" payment method
      - Tap "Place Order"
      - Verify the order confirmation screen is visible
      - Verify the order number is displayed
    context: Use the default shipping address

  - name: Checkout with Promo Code
    steps:
      - Tap on the Cart tab
      - Tap "Proceed to Checkout"
      - Tap "Add Promo Code"
      - Type the promo code
      - Tap "Apply"
      - Tap "Place Order"
      - Verify the discount is applied to the total
      - Verify the order confirmation screen is visible

Field Reference

Field	Required	Description
`name`	Yes	Group name. Used as the display name in the dashboard.
`description`	No	A brief description of what the group tests.
`appId`	No	App bundle ID (iOS) or package name (Android). If it matches an app in your organization, the group is automatically linked.
`platform`	No	`"ios"` or `"android"`.
`resetStrategy`	No	The group’s start state: `"clear_data"` (Clean app data, default), `"reinstall"` (Fresh install), `"relaunch"` (Restart the app), or `"none"` (Where the last test stopped). Any other value is refused when the file is imported.
`context`	No	Instructions for the AI agent that apply to all tests in the group.
`variables`	No	Key-value pairs available during test execution.
`cases`	Yes	Array of test case definitions (see below).

Test Case Fields

Field	Required	Description
`name`	Yes	Test case name.
`steps`	Yes	Array of step strings. Each step is a plain-text instruction for the AI agent.
`assertions`	No	Deprecated. Array of strings, each imported as a `Verify ...` step at the end of the case. Write checks as `Verify ...` steps instead (see Checking results with Verify steps); export never writes this field.
`context`	No	Per-case instructions for the AI agent (supplements the group’s context).
`startState`	No	This test’s own start state, overriding the group’s `resetStrategy`: `"clear_data"`, `"reinstall"`, `"relaunch"`, or `"none"`. Any other value is refused when the file is imported.

Importing YAML

From the API

POST /api/v1/tests/suites/import-yaml
Content-Type: multipart/form-data

file (required) — the YAML file upload.
app_id (optional) — app public ID to link the group to. If omitted, VibeView tries to match via the appId field in the YAML.

Response:

{
  "public_id": "checkout-flow-a1b2c3",
  "name": "Checkout Flow",
  "case_count": 2
}

If the YAML’s appId matches more than one app in your organization (for example, an iOS and a tvOS app sharing a bundle ID), the import does not create the group. Instead it returns an ambiguity response listing the matching apps so you can re-import with an explicit app_id:

{
  "ambiguous": true,
  "app_bundle_id": "com.example.shop",
  "matching_apps": [
    { "public_id": "shop-app-d4e5f6", "name": "Shop App", "platform": "ios" },
    { "public_id": "shop-tv-g7h8i9", "name": "Shop TV", "platform": "tvos" }
  ],
  "suite_name": "Checkout Flow"
}

Exporting YAML

From the API

GET /api/v1/tests/suites/{suite_id}/export-yaml

Returns the group as a YAML file download. The export includes all test cases with their steps, context, and recorded gesture data (used by Smart and No AI runs).

Example Files

name: Login Test
appId: com.example.myapp
platform: ios

cases:
  - name: Successful Login
    steps:
      - Tap on the "Email" field
      - Type "user@example.com"
      - Tap on the "Password" field
      - Type "password123"
      - Tap "Sign In"
      - Verify the home screen is visible
      - Verify the welcome message shows the user's name

Several tests with test data

name: Search and Filter
description: Tests the product search and filtering functionality
appId: com.example.shop
platform: android
resetStrategy: relaunch
context: Start from the home screen. The app has sample product data loaded.
variables:
  search_term: wireless headphones
  max_price: "50"

cases:
  - name: Basic Search
    steps:
      - Tap on the search bar
      - Type the search term
      - Tap the search button
      - Verify search results are displayed
      - Verify the results contain items matching the search term

  - name: Filter by Price
    steps:
      - Tap on the search bar
      - Type the search term
      - Tap the search button
      - Tap "Filters"
      - Set maximum price to the max price value
      - Tap "Apply"
      - Verify all displayed products are under the max price
      - Verify the filter badge shows active filter count
    context: After search results load, the filter button appears in the top right

YAML Test Format

Quick Start

VibeView YAML Schema

Field Reference

Test Case Fields

Importing YAML

From the API

Exporting YAML

From the API

Example Files

Simple Login Test

Several tests with test data