14.4Implementing Self-Healing in Your Framework

Wrapper Function (Scripted Tier-1 Healing)

For scripted (non-agent) runs, a thin healing wrapper can resolve an element by accessible name from a fresh snapshot:

# smart_click: click by expected accessible name, resolving the ref at runtime
smart_click() {
  local expected_name="$1"     # e.g. "Submit"

  # Take a fresh snapshot; the CLI returns the YAML file path
  local snap
  snap=$(playwright-cli snapshot)

  # Find a button/link whose accessible name matches, extract its ref
  local ref
  ref=$(grep -iE "(button|link) \"[^\"]*${expected_name}[^\"]*\"" "$snap" \
        | grep -oE 'ref=e[0-9]+' | head -1 | cut -d= -f2)

  if [ -n "$ref" ] && playwright-cli click "$ref"; then
    echo "[heal] clicked ${expected_name} via ref ${ref}"
    return 0
  fi

  # Evidence for the humans (and the healer)
  playwright-cli screenshot
  echo "[heal] could not resolve an element named: $expected_name"
  return 1
}

# Usage:
smart_click "Submit"
smart_click "Log in"

Notice what this is: a five-line, grep-based rediscovery of the element by its accessible name — because the snapshot is plain YAML on disk, tier-1 healing doesn't even need an LLM.

Agent-Native Approach

Rather than scripting recovery logic, let the agent handle it naturally:

# Test definition with recovery hints
test: Submit contact form
steps:
  - Fill in the contact form
  - Click the submit button
recovery_hints:
  submit_button:
    accessible_name: "Submit"
    fallback_names: ["Send", "Send message"]
    semantic: "The button that submits the form"

The agent resolves refs from the live snapshot using the hints — and because hints are expressed as accessible names rather than CSS selectors, they survive markup refactors.