Guides

YAML Workflow Reference

A workflow is a plain YAML file that describes a sequence of browser actions. Run it with mr-browser run <file.yaml>. The engine resolves every target string by searching the page's Accessibility Tree for the best match.

# Complete schema

Every available step type with all options documented inline:

full-demo.yaml

yaml

name: full-demo
description: "Demonstrates every available step type"
config:
  timeout_seconds: 30   # per-step timeout (default: 30)
  stop_on_error: true   # halt on first failure (default: true)

steps:
  # Navigate to a URL
  - open:
      url: "https://example.com/login"

  # Type text into an element
  - type:
      target: "Email"          # plain-English element description
      value: "$EMAIL"          # $ENV_VAR references are resolved at runtime
      clear: true              # clear field first (default: true)
      enter: false             # press Enter after typing (default: false)

  - type:
      target: "Password"
      value: "$PASSWORD"
      enter: true              # submit the form

  # Wait for navigation or content
  - wait:
      seconds: 2               # fixed pause

  - wait:
      url: "/dashboard"        # wait until URL contains this substring

  - wait:
      selector: "#main-content" # wait until CSS selector is visible

  # Click an element
  - click:
      target: "Download Report"

  # Hover over an element
  - hover:
      target: "the user avatar menu"

  # Scroll the page
  - scroll:
      direction: down          # up / down / left / right / top / bottom
      pixels: 800              # ignored for top/bottom

  # Take a screenshot
  - screenshot:
      output: "reports/dashboard.png"   # defaults to screenshot_<timestamp>.png

  # Extract text and save to session memory
  - extract:
      target: "the account balance"
      save_as: "balance"       # available as $balance in later steps

  # Assert conditions
  - assert:
      text_visible: "Welcome"       # text must appear on page

  - assert:
      url_contains: "/dashboard"    # URL must contain substring

  - assert:
      element_exists: "Sign Out"    # element matching intent must exist

  # Upload a file
  - upload:
      target: "the file upload input"
      file: "/tmp/report.csv"

  # Reload the page
  - reload: {}

# Environment variables

Any value field supports $VAR_NAME references. They are resolved from the shell environment at runtime and are never logged or stored.

terminal

bash

# .env (never commit this)
EMAIL=admin@corp.com
PASSWORD=supersecret

# Run with env vars from shell
EMAIL=admin@corp.com PASSWORD=supersecret mr-browser run login.yaml

# Or export and run
export MRBROWSER_LOG_LEVEL=debug
mr-browser run login.yaml

Warning

Using $ENV_VAR syntax is the only safe way to pass credentials. Never hardcode passwords in YAML files — they will appear in git history.

# Selector fallback

Both click and type accept an optional selector field. When provided, the engine skips intent resolution and uses the CSS selector directly — useful for machine-generated IDs that are stable.

selector-override.yaml

yaml

steps:
  # Long form (with optional selector override)
  - click:
      target: "Submit button"
      selector: "#submit-btn"   # optional: bypass resolver

  # Type long form
  - type:
      target: "Search box"
      value: "hello world"

# All step types

Step	Required fields	Optional fields
open:	url	—
click:	target	selector
type:	target, value	clear, enter, selector
hover:	target	selector
scroll:	direction	pixels
wait:	seconds \| selector \| url	—
screenshot:	—	output
extract:	target, save_as	—
assert:	text_visible \| url_contains \| element_exists	—
upload:	target, file	selector
reload:	—	—