Back to docs

Flow Authoring

Flows are Playwright tests that capture step screenshots + DOM snapshots through `createOcchio(page)`.

Where flows live

Dashboard paths: /dashboard/[repo]/flows for list, /dashboard/[repo]/flows/newfor creation, and /dashboard/[repo]/flows/[flow] for editing/testing.

Input modes in the editor

Auto-detect mode: parses either natural language steps or full Playwright code.

Natural language mode: accepts commands like Open /login, Fill email with test@example.com, Click [data-testid='submit'], Wait for [data-testid='dashboard'], Press Enter.

Code mode: raw TypeScript Playwright test content.

Minimum valid flow contract

import { test, expect } from '@playwright/test';
import { createOcchio } from '@occhio/playwright';

test('Example flow', async ({ page }) => {
  const occhio = createOcchio(page);
  occhio.startFlow('Example flow');

  await page.goto('/');
  await occhio.captureStep('Home page loaded');

  const result = await occhio.endFlow();
  expect(result.steps.length).toBeGreaterThan(0);
});

Run Test behavior

“Run Test” executes Playwright in a temporary workspace via POST /api/flows/test, with OCCHIO_RESULTS_DIR injected so JSON flow artifacts are captured.

If no result files are produced, the API returns a 400 with:"No flow results were captured. Ensure the test calls occhio.startFlow(), captureStep(), and endFlow()."

Flow auto-detection wizard (Pro)

Setup wizard at /dashboard/[repo]/setup crawls your staging URL, detects flows with AI, lets you review/edit enabled flows, configures optional test data overrides, and saves generated code.

Auth walls are handled via pasted Playwright storageState JSON.