Workflows

Record, parameterize, and replay deterministic browser workflows as YAML

BAP workflows are YAML files that define a sequence of browser steps. Record them interactively, edit the YAML to add parameters and assertions, then replay them deterministically.

Recording a Workflow

1. Start recording

   bap workflow record checkout-flow
   

   Recording state is persisted to ~/.bap/recording.json so it survives across CLI invocations.

2. Execute your browser commands as normal

   bap goto https://store.example.com bap act click:text:"Add to cart" bap act

   click:text:"Checkout" bap fill label:"Email" "[e-mail]" bap act click:role:button:"Place
   Order" bap screenshot ``` Each command is automatically captured as a workflow step.
   </Step>
   
   <Step title="Stop recording and save">
     ```bash
     bap workflow stop
     # Saved to ~/.bap/workflows/checkout-flow.yaml
   

YAML Format

A recorded workflow produces YAML like this:

name: checkout-flow
description: Recorded on 2026-03-21T10:30:00.000Z
steps:
  - type: goto
    args: https://store.example.com
  - type: act
    args: click:text:"Add to cart"
  - type: act
    args: click:text:"Checkout"
  - type: fill
    args: label:"Email"="[e-mail]"
  - type: act
    args: click:role:button:"Place Order"
  - type: screenshot
    args: ""

Parameters

Add parameterized values so workflows can be reused with different inputs:

name: checkout-flow
description: Parameterized checkout workflow
params:
  email: [e-mail]
  product: "Widget Pro"
steps:
  - type: goto
    args: https://store.example.com
  - type: act
    args: click:text:"{{product}}"
  - type: fill
    args: label:"Email"="{{email}}"
  - type: act
    args: click:role:button:"Place Order"

Run with parameter overrides:

bap workflow run checkout-flow --param email=[e-mail] --param product="Gadget X"

Assertions

Add post-step assertions to validate workflow correctness:

steps:
  - type: goto
    args: https://store.example.com
    assert:
      url: store.example.com
      text: "Welcome to our store"

  - type: act
    args: click:role:button:"Place Order"
    assert:
      url: /confirmation
      text: "Order confirmed"
      element: role:heading:"Thank you"

Three assertion types are available:

Assertion	What it checks
url	URL contains the given string
text	Text is visible on the page
element	Element matching the BAP selector exists

Step Labels

Add human-readable labels for clearer output:

steps:
  - type: goto
    args: https://store.example.com
    label: Open store homepage

  - type: act
    args: click:text:"Add to cart"
    label: Add product to cart

Repeat and Conditionals

Repeat a step N times

steps:
  - type: scroll
    args: "300"
    repeat: 5
    label: Scroll down 5 times

Repeat until a condition is met

steps:
  - type: act
    args: click:text:"Load more"
    repeat:
      until: "text:No more items"
    label: Load all items

Conditional execution

steps:
  - type: act
    args: click:text:"Accept cookies"
    if: "element:text:Accept cookies"
    label: Dismiss cookie banner if present

Macros

Define reusable step sequences:

name: multi-product-checkout
macros:
  add-product:
    params:
      product: ""
    steps:
      - type: act
        args: click:text:"{{product}}"
      - type: act
        args: click:role:button:"Add to cart"

steps:
  - type: goto
    args: https://store.example.com

  - type: macro
    macro: add-product
    macroParams:
      product: "Widget Pro"

  - type: macro
    macro: add-product
    macroParams:
      product: "Gadget X"

  - type: act
    args: click:text:"Checkout"

Error Handling

Control what happens when a step fails:

name: resilient-workflow
onError: continue # stop (default), continue, or retry
steps:
  - type: act
    args: click:text:"Optional banner"
  - type: goto
    args: https://example.com

Per-Step Timeout

steps:
  - type: goto
    args: https://slow-site.example.com
    timeout: 60000
    label: Wait up to 60s for slow page

Fused Observation

Add observe: true to any step to get a page observation after it executes:

steps:
  - type: goto
    args: https://example.com
    observe: true
    label: Navigate and observe

Managing Workflows

# List saved workflows
bap workflow list

# Run a workflow
bap workflow run checkout-flow

# Run with parameter overrides
bap workflow run checkout-flow --param email=[e-mail]

# Record a reusable macro
bap workflow macro login-steps
# ... execute login commands ...
bap workflow macro stop

# List available macros
bap workflow macros

Workflows are saved to ~/.bap/workflows/ as YAML files.

Step Types

Type	What it does	Example args
goto	Navigate to URL	https://example.com
act	Composite action	click:text:"Submit"
click	Click element	role:button:"OK"
fill	Fill input	label:"Email"="[e-mail]"
observe	Observe page	(empty)
extract	Extract data	--fields="title,price"
screenshot	Take screenshot	(empty)
scroll	Scroll page	300
wait	Wait for condition	text:"Loaded"
macro	Invoke a macro	(uses macro field)