browserctl 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec75744264ce56f8c3f94ab95518a106c8225ec1dc11dd35a97f43186b590502
-  data.tar.gz: 973c3b270b5d1bba3dfa900623790e3c5cb9d5bd8ebe8faa50c28d09e48fbfff
+  metadata.gz: a2662c63f1ab585b29689e8e09ac2c8f7c3214539c440c51da82efc954fc0493
+  data.tar.gz: 3e8f6790cdb3a3a79382f68c3a1fb6235805e6acc96658270d06c4d91ee1098b
 SHA512:
-  metadata.gz: 16cd84c58a070de0b9d340ed2bb4e3a951216526dd77a9f18e0f9ea7292311eb51eddf1989c93c11d488cf4bf29163a60a13510f5949599d6027142cf808c1a0
-  data.tar.gz: 615213ac9ba1e694c9fb4597a348abebab9d8f2ba04801dd7d59c1dc00829111f0cce9f49391a7883e7502422ed0b246e86d8c553c62b9be406e0f1e23946e8c
+  metadata.gz: d729193bb86f061227588d46981d7fc5aaf98ef45956a4f4c5e59ca30c95f02f2a06d0d2e9227e671e0f6fb8a3ffcdd2ec4347cc20bd30bb40b2bef54f8b25c4
+  data.tar.gz: 48170f604f692e980da8956c41f74255e0f16c6a43a13f3ae090377550bc14967a632a8ac01ebe85c7cabde1ff4226638e92fd40329cde0bcb2539c0c4a5c69a

data/CHANGELOG.md

@@ -10,6 +10,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0](https://github.com/patrick204nqh/browserctl/compare/v0.6.0...v0.7.0) (2026-04-28)
+
+
+### Features
+
+* v0.7 interaction primitives (press/hover/upload/select/dialog/ask) + page_focus fix ([#47](https://github.com/patrick204nqh/browserctl/issues/47)) ([63daadc](https://github.com/patrick204nqh/browserctl/commit/63daadcfbd4e967fc539b714393d163fabfc86b2))
+
+## [0.6.0](https://github.com/patrick204nqh/browserctl/compare/v0.5.0...v0.6.0) (2026-04-28)
+
+
+### Features
+
+* add feedback capture guidelines and update .gitignore to include feedback directory ([03a436d](https://github.com/patrick204nqh/browserctl/commit/03a436d69d37826a6c24662b70d6852eac78aa54))
+* **v0.6:** CLI redesign — noun-verb commands, storage/session, daemon auto-index ([#41](https://github.com/patrick204nqh/browserctl/issues/41)) ([b40040f](https://github.com/patrick204nqh/browserctl/commit/b40040f6fba7b78791e845e55af156be46bde3c3))
+* **v0.6:** page_focus command, integration specs, and doc polish ([#42](https://github.com/patrick204nqh/browserctl/issues/42)) ([8cf006d](https://github.com/patrick204nqh/browserctl/commit/8cf006d0e3698bb0698c59d7af5b87f72a3cd154))
+
+
+### Bug Fixes
+
+* correct initial checkbox state assertion to [false, true, false] ([#33](https://github.com/patrick204nqh/browserctl/issues/33)) ([5ab0fe4](https://github.com/patrick204nqh/browserctl/commit/5ab0fe4fbe5d5f244c795235f0531e0c970d75c7))
+* dismiss on-load notifications before asserting counts ([#35](https://github.com/patrick204nqh/browserctl/issues/35)) ([b508ba6](https://github.com/patrick204nqh/browserctl/commit/b508ba6748d245526f6321a731e6a7bf4ad5cc86))
+* fill replaces existing input value instead of appending ([#29](https://github.com/patrick204nqh/browserctl/issues/29)) ([c7abb48](https://github.com/patrick204nqh/browserctl/commit/c7abb48153e1c64fcd73e22a5bf376a98555f68c))
+* notifications workflow — exclude container from counts, use evaluate for dismiss ([#34](https://github.com/patrick204nqh/browserctl/issues/34)) ([de43301](https://github.com/patrick204nqh/browserctl/commit/de43301942eb7a6335bc9fc7130c22ecf3dd8b38))
+* README & CONTRIBUTING polish + Rakefile v0.6 CI fix ([#43](https://github.com/patrick204nqh/browserctl/issues/43)) ([422c614](https://github.com/patrick204nqh/browserctl/commit/422c6141035d47bb3fd4bc86f732029b44e35206))
+* replace all remaining stale v0.5 CLI commands with v0.6 equivalents ([#45](https://github.com/patrick204nqh/browserctl/issues/45)) ([8d00923](https://github.com/patrick204nqh/browserctl/commit/8d0092380bbc7890761e6d8f5da7864358ce88f7))
+* update demo assets installation and improve login tape requirements ([cf02e3a](https://github.com/patrick204nqh/browserctl/commit/cf02e3ad11fc99f1483904e396160d4345363e17))
+* update login demo tape to use data-test selectors for input fields and buttons ([016fcda](https://github.com/patrick204nqh/browserctl/commit/016fcdaf77ce542d06efe898312063581fc3fffe))
+* update stale `browserctl run` references to `browserctl workflow run` ([#44](https://github.com/patrick204nqh/browserctl/issues/44)) ([7f7005a](https://github.com/patrick204nqh/browserctl/commit/7f7005ac6fd6517c8751cf808378233343e9ace8))
+* use baseline delta assertions instead of absolute notification counts ([#37](https://github.com/patrick204nqh/browserctl/issues/37)) ([33ac119](https://github.com/patrick204nqh/browserctl/commit/33ac119bbb43c0290fe03da06ca3f8545095f7a2))
+* wait for notification-container before dismissing on-load toasts ([#36](https://github.com/patrick204nqh/browserctl/issues/36)) ([883cdf8](https://github.com/patrick204nqh/browserctl/commit/883cdf839bcef2d57bcb4764ff89862aa1969486))
+
 ## [0.5.0](https://github.com/patrick204nqh/browserctl/compare/v0.4.0...v0.5.0) (2026-04-25)
 
 

data/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">browserctl</h1>
 
 <p align="center">
-  A persistent browser daemon for AI agents and iterative dev workflows — the session stays alive between commands.
+  A browser daemon that keeps sessions alive between commands — for AI agents and iterative dev workflows.
 </p>
 
 <p align="center">
@@ -20,11 +20,11 @@ Every browser automation tool restarts the browser when your script ends. That m
 
 ```bash
 browserd &                                               # start the daemon (headless)
-browserctl open login --url https://example.com/login
-browserctl snap login                                    # AI-friendly JSON snapshot with ref IDs
-browserctl fill login --ref e1 --value me@example.com   # interact by ref, no selectors needed
-browserctl click login --ref e2
-browserctl shutdown
+browserctl page open main --url https://example.com/login
+browserctl snapshot main                                 # AI-friendly JSON snapshot with ref IDs
+browserctl fill main --ref e1 --value me@example.com    # interact by ref, no selectors needed
+browserctl click main --ref e2
+browserctl daemon stop
 ```
 
 ---
@@ -37,7 +37,7 @@ browserctl shutdown
 **Terminal**<br/>
 <sub>CLI commands, live output, session persistence proof</sub>
 
-<img src="docs/assets/terminal.webp" alt="browserctl terminal demo"/>
+<img src="docs/assets/terminal.gif" alt="browserctl terminal demo"/>
 
 </td>
 <td align="center" width="50%">
@@ -50,15 +50,6 @@ browserctl shutdown
 </td>
 </tr></table>
 
-> Demo assets are regenerated automatically on every push to `main` that touches `demo/` or the login example. To regenerate locally:
->
-> ```bash
-> rake demo               # full pipeline: screenshots + browser GIF + terminal GIF
-> rake demo:screenshots   # smoke test screenshots only
-> rake demo:browser_gif   # browser animation only  (requires: ffmpeg)
-> rake demo:terminal      # terminal GIF only        (requires: vhs)
-> ```
-
 ---
 
 ## Quick Start
@@ -71,22 +62,23 @@ gem install browserctl
 browserd &
 
 # 3. Open a named page
-browserctl open main --url https://the-internet.herokuapp.com/login
+browserctl page open main --url https://moatazeldebsy.github.io/test-automation-practices/#/auth
 
-# 4. Snapshot the page — get AI-friendly JSON with ref IDs
-browserctl snap main
+# 4. Snapshot — returns JSON with a ref ID per interactable element
+browserctl snapshot main
+# → [{"ref":"e1","tag":"input","attrs":{"data-test":"username-input"}}, {"ref":"e2",...}, {"ref":"e3","tag":"button","text":"Login",...}]
 
-# 5. Interact using refs
-browserctl fill  main --ref e1 --value tomsmith
-browserctl fill  main --ref e2 --value SuperSecretPassword!
+# 5. Interact using the ref IDs from the snapshot
+browserctl fill main --ref e1 --value admin
+browserctl fill main --ref e2 --value admin
 browserctl click main --ref e3
 
 # 6. Observe
-browserctl url  main
-browserctl snap main --diff   # only what changed
+browserctl url main
+browserctl snapshot main --diff   # only what changed
 
 # 7. Done
-browserctl shutdown
+browserctl daemon stop
 ```
 
 → [Full Getting Started guide](docs/getting-started.md)
@@ -107,7 +99,7 @@ browserctl shutdown
 
 Most automation tools are stateless — every script spins up a fresh browser and tears it down. browserctl doesn't.
 
-| | browserctl | Playwright / Selenium |
+| Capability | browserctl | Playwright / Selenium |
 |---|---|---|
 | Session persists across commands | ✓ | ✗ (per-script lifecycle) |
 | Named page handles | ✓ | ✗ |
@@ -125,7 +117,7 @@ Most automation tools are stateless — every script spins up a fresh browser an
 
 ## Installation
 
-**Requirements:** Ruby >= 3.3 · Chrome or Chromium on your `PATH`
+**Requirements:** Ruby >= 3.3 · Chrome or Chromium installed
 
 ```bash
 gem install browserctl
@@ -165,7 +157,7 @@ browserctl ships as a Claude Code plugin. Install it once and Claude automatical
 }
 ```
 
-Once installed, Claude Code loads the `browserctl` skill automatically — no `/invoke` needed.
+Once installed, the `browserctl` skill loads automatically.
 
 ---
 
@@ -178,7 +170,7 @@ Start multiple named instances for agent isolation:
 ```bash
 browserd --name agent-a &
 browserd --name agent-b &
-browserctl --daemon agent-a open main --url https://app.example.com
+browserctl --daemon agent-a page open main --url https://app.example.com
 ```
 
 The daemon shuts itself down after 30 minutes of inactivity.
@@ -210,11 +202,14 @@ bin/setup              # brew bundle (macOS) + bundle install + Chrome check
 bundle exec rspec      # run tests
 bundle exec rubocop    # lint
 
-rake demo              # regenerate screenshots + terminal GIF
-rake demo:screenshots  # screenshots only (no VHS required)
-rake demo:terminal     # terminal GIF only
+rake demo               # full pipeline: screenshots + browser GIF + terminal GIF
+rake demo:screenshots   # smoke test screenshots only
+rake demo:browser_gif   # browser animation only  (requires: ffmpeg)
+rake demo:terminal      # terminal GIF only        (requires: vhs)
 ```
 
+> Demo assets are regenerated automatically on every push to `main` that touches `demo/` or the login example.
+
 ---
 
 ## Contributing

data/bin/browserctl

@@ -14,20 +14,21 @@ require "json"
 require "optimist"
 require "browserctl"
 require "browserctl/commands/cli_output"
-require "browserctl/commands/open_page"
 require "browserctl/commands/fill"
 require "browserctl/commands/click"
 require "browserctl/commands/snapshot"
 require "browserctl/commands/screenshot"
-require "browserctl/commands/watch"
 require "browserctl/commands/record"
-require "browserctl/commands/pause"
 require "browserctl/commands/resume"
 require "browserctl/commands/init"
-require "browserctl/commands/inspect"
-require "browserctl/commands/export_cookies"
-require "browserctl/commands/import_cookies"
-require "browserctl/commands/status"
+require "browserctl/commands/page"
+require "browserctl/commands/cookie"
+require "browserctl/commands/storage"
+require "browserctl/commands/session"
+require "browserctl/commands/daemon"
+require "browserctl/commands/workflow"
+require "browserctl/commands/dialog"
+require "browserctl/commands/ask"
 
 def print_result(res)
   if res.is_a?(Hash) && res[:error]
@@ -37,59 +38,86 @@ def print_result(res)
   puts res.to_json
 end
 
-# rubocop:disable Metrics/MethodLength
 def usage
   puts <<~USAGE
     Usage: browserctl <command> [args]
 
     Setup:
-      init                                         Scaffold .browserctl/ in this project
-
-    Browser commands (require browserd running):
-      open   <page> [--url URL]                   Open or focus a named page
-      close  <page>                                Close a named page
-      pages                                        List open pages
-      goto   <page> <url>                          Navigate a page
-      fill   <page> <selector> <value>             Fill an input
-             <page> --ref <ref> --value <value>    Fill via snapshot ref
-      click  <page> <selector>                     Click an element
-             <page> --ref <ref>                    Click via snapshot ref
-      shot   <page> [--out PATH] [--full]          Take a screenshot
-      snap   <page> [--format ai|html] [--diff]    Snapshot DOM (default: ai)
-      url    <page>                                Print current URL
-      eval   <page> <expression>                   Evaluate JS expression
-      watch  <page> <selector> [--timeout N]       Wait for a selector to appear
-      pause   <page>                               Pause automation — browser stays live
-      resume  <page>                               Resume automation after manual action
-      inspect <page>                               Open Chrome DevTools for a named page
-      cookies <page>                               List all cookies as JSON
-      set-cookie <page> <name> <value> <domain>    Set a cookie (path defaults to /)
-      clear-cookies <page>                         Clear all cookies for a page
-      export-cookies <page> <path>                 Export cookies to a JSON file
-      import-cookies <page> <path>                 Import cookies from a JSON file
-
-    Recording commands:
-      record start <name>            Start recording browser commands
-      record stop  [--out PATH]      Stop recording and save workflow
-      record status                  Show active recording name
-
-    Workflow commands:
-      run      <name|file> [--params file] [--key value ...]   Run a workflow
-      workflows                                List available workflows
-      describe <name>                          Describe a workflow
-
-    Daemon commands:
-      ping                   Check if browserd is alive
-      status                 Show daemon status, PID, and open pages
-      shutdown               Stop browserd
-
-    Options:
-      --daemon <name>    Connect to a named daemon instance
-      --version, -v      Print version and exit
+      init
+
+    Page:
+      page open <name> [--url URL]
+      page close <name>
+      page list
+      page focus <name>
+
+    Interaction (page is always first arg after verb):
+      navigate <page> <url>
+      fill     <page> <selector> <value>
+               <page> --ref <ref> --value <value>
+      click    <page> <selector>
+               <page> --ref <ref>
+      snapshot <page> [--format elements|html] [--diff]
+      screenshot <page> [--out PATH] [--full]
+      evaluate <page> <expression>
+      url      <page>
+      wait     <page> <selector> [--timeout N]
+      pause    <page> [--message MSG]
+      resume   <page>
+      ask      <prompt>
+      devtools <page>
+      press    <page> <key>
+      hover    <page> <selector>
+      upload   <page> <selector> <file>
+      select   <page> <selector> <value>
+      dialog accept  <page> [text]
+      dialog dismiss <page>
+
+    Cookie:
+      cookie list   <page>
+      cookie set    <page> <name> <value> --domain DOMAIN [--path /]
+      cookie delete <page>
+      cookie export <page> <path>
+      cookie import <page> <path>
+
+    Storage:
+      storage get    <page> <key> [--store local|session]
+      storage set    <page> <key> <value> [--store local|session]
+      storage export <page> <path> [--store local|session|all]
+      storage import <page> <path>
+      storage delete <page> [--store local|session|all]
+
+    Session:
+      session save   <name>
+      session load   <name>
+      session list
+      session delete <name>
+      session export <name> <path>
+      session import <path>
+
+    Recording:
+      record start <name>
+      record stop  [--out PATH]
+      record status
+
+    Workflow:
+      workflow run      <name|file> [--params file] [--key value ...]
+      workflow list
+      workflow describe <name>
+
+    Daemon:
+      daemon start  [--headed] [--name NAME]
+      daemon stop
+      daemon status
+      daemon ping
+      daemon list
+
+    Global options:
+      --daemon <name>    Connect to named or auto-indexed daemon (d1, d2, work, ...)
+      --version, -v
   USAGE
   exit 0
 end
-# rubocop:enable Metrics/MethodLength
 
 daemon_idx  = ARGV.index("--daemon")
 daemon_name = if daemon_idx
@@ -105,70 +133,80 @@ usage if cmd.nil? || %w[-h --help help].include?(cmd)
 runner = Browserctl::Runner.new
 
 case cmd
-when "run"
-  name = args.shift or abort "usage: browserctl run <workflow_name|file.rb> [--key value ...]"
-  if File.exist?(name)
-    before = Browserctl.registry_snapshot.keys
-    load File.expand_path(name)
-    name = (Browserctl.registry_snapshot.keys - before).first || File.basename(name, ".rb")
-  end
-  params_file_idx = args.index("--params")
-  file_params = {}
-  if params_file_idx
-    params_path = args.delete_at(params_file_idx + 1)
-    args.delete_at(params_file_idx)
-    begin
-      file_params = Browserctl::Runner.load_params_file(params_path)
-    rescue StandardError => e
-      abort "Error loading params file: #{e.message}"
-    end
-  end
-  cli_params = {}
-  args.each_slice(2) do |flag, val|
-    key = flag.sub(/\A--/, "").to_sym
-    cli_params[key] = val
-  end
-  params = file_params.merge(cli_params)
-  success = runner.run_workflow(name, **params)
-  exit(success ? 0 : 1)
-
-when "workflows"
-  list = runner.list_workflows
-  list.each { |w| puts "#{w[:name].ljust(24)} #{w[:desc]}" }
-
-when "describe"
-  name = args.shift or abort "usage: browserctl describe <workflow_name>"
-  puts JSON.pretty_generate(runner.describe_workflow(name))
-
-when "record" then Browserctl::Commands::Record.run(args)
-when "init"   then Browserctl::Commands::Init.run(args)
+when "workflow" then Browserctl::Commands::Workflow.run(runner, args)
+when "record"   then Browserctl::Commands::Record.run(args)
+when "init"     then Browserctl::Commands::Init.run(args)
+when "ask"      then Browserctl::Commands::Ask.run(args)
 
 else
   client = Browserctl::Client.new(Browserctl.socket_path(daemon_name))
 
   case cmd
-  when "open"     then Browserctl::Commands::OpenPage.run(client, args)
-  when "close"    then print_result(client.close_page(args[0]))
-  when "pages"    then print_result(client.list_pages)
-  when "goto"     then print_result(client.goto(args[0], args[1]))
+  when "page"     then Browserctl::Commands::Page.run(client, args)
+  when "cookie"   then Browserctl::Commands::Cookie.run(client, args)
+  when "storage"  then Browserctl::Commands::Storage.run(client, args)
+  when "session"  then Browserctl::Commands::Session.run(client, args)
+  when "daemon"   then Browserctl::Commands::Daemon.run(client, args)
+  when "navigate" then print_result(client.navigate(args[0], args[1]))
   when "fill"     then Browserctl::Commands::Fill.run(client, args)
   when "click"    then Browserctl::Commands::Click.run(client, args)
-  when "shot"     then Browserctl::Commands::Screenshot.run(client, args)
-  when "snap"     then Browserctl::Commands::Snapshot.run(client, args)
+  when "snapshot" then Browserctl::Commands::Snapshot.run(client, args)
+  when "screenshot" then Browserctl::Commands::Screenshot.run(client, args)
+  when "evaluate" then print_result(client.evaluate(args[0], args[1]))
   when "url"      then print_result(client.url(args[0]))
-  when "eval"     then print_result(client.evaluate(args[0], args[1]))
-  when "watch"    then Browserctl::Commands::Watch.run(client, args)
-  when "pause"    then Browserctl::Commands::Pause.run(client, args)
-  when "resume"   then Browserctl::Commands::Resume.run(client, args)
-  when "inspect"       then Browserctl::Commands::Inspect.run(client, args)
-  when "cookies"         then print_result(client.cookies(args[0]))
-  when "set-cookie"      then print_result(client.set_cookie(args[0], args[1], args[2], args[3]))
-  when "clear-cookies"   then print_result(client.clear_cookies(args[0]))
-  when "export-cookies" then Browserctl::Commands::ExportCookies.run(client, args)
-  when "import-cookies" then Browserctl::Commands::ImportCookies.run(client, args)
-  when "ping"     then print_result(client.ping)
-  when "status"   then Browserctl::Commands::Status.run(client)
-  when "shutdown" then print_result(client.shutdown)
+  when "wait"
+    opts = Optimist.options(args) do
+      opt :timeout, "Seconds to wait (default: 30)", default: 30.0, short: "-t"
+    end
+    name = args.shift
+    selector = args.shift
+    abort "usage: browserctl wait <page> <selector> [--timeout N]" unless name && selector
+    print_result(client.wait(name, selector, timeout: opts[:timeout]))
+  when "pause"
+    opts = Optimist.options(args) do
+      opt :message, "Message shown to human", type: :string, short: "-m"
+    end
+    name = args.shift or abort "usage: browserctl pause <page> [--message MSG]"
+    res = client.pause(name, message: opts[:message])
+    if res[:error]
+      warn "Error: #{res[:error]}"
+      exit 1
+    end
+    puts "Page '#{name}' paused. Browser is live — interact freely."
+    puts "(#{opts[:message]})" if opts[:message]
+    puts "When done: browserctl resume #{name}"
+  when "resume" then Browserctl::Commands::Resume.run(client, args)
+  when "press"
+    name = args.shift or abort "usage: browserctl press <page> <key>"
+    key  = args.shift or abort "usage: browserctl press <page> <key>"
+    print_result(client.press(name, key))
+  when "hover"
+    name     = args.shift or abort "usage: browserctl hover <page> <selector>"
+    selector = args.shift or abort "usage: browserctl hover <page> <selector>"
+    print_result(client.hover(name, selector))
+  when "upload"
+    name     = args.shift or abort "usage: browserctl upload <page> <selector> <file>"
+    selector = args.shift or abort "usage: browserctl upload <page> <selector> <file>"
+    path     = args.shift or abort "usage: browserctl upload <page> <selector> <file>"
+    print_result(client.upload(name, selector, path))
+  when "select"
+    name     = args.shift or abort "usage: browserctl select <page> <selector> <value>"
+    selector = args.shift or abort "usage: browserctl select <page> <selector> <value>"
+    value    = args.shift or abort "usage: browserctl select <page> <selector> <value>"
+    print_result(client.select(name, selector, value))
+  when "dialog" then Browserctl::Commands::Dialog.run(client, args)
+  when "devtools"
+    name = args.shift or abort "usage: browserctl devtools <page>"
+    res = client.devtools(name)
+    if res[:error]
+      warn "Error: #{res[:error]}"
+      exit 1
+    end
+    url = res[:devtools_url]
+    puts "Opening DevTools for '#{name}':"
+    puts "  #{url}"
+    opener = RUBY_PLATFORM =~ /darwin/ ? "open" : "xdg-open"
+    system(opener, url)
   else
     abort "unknown command: #{cmd}\nRun 'browserctl --help' for usage."
   end

data/bin/browserd

@@ -20,11 +20,17 @@ if opts[:name] && opts[:name] !~ /\A[a-zA-Z0-9_-]{1,64}\z/
   abort "Invalid daemon name #{opts[:name].inspect} — use only letters, digits, _ or -"
 end
 
-log_path = Browserctl.log_path(opts[:name])
+assigned_name = opts[:name] || Browserctl.next_daemon_name
+if assigned_name && !opts[:name]
+  warn "browserd: default slot taken — starting as '#{assigned_name}'"
+  warn "  to connect: browserctl --daemon #{assigned_name} <command>"
+end
+
+log_path = Browserctl.log_path(assigned_name)
 warn "browserd starting — log: #{log_path}"
 Browserctl.logger = Browserctl.build_logger(opts[:log_level], log_path: log_path)
 Browserctl::Server.new(
   headless: !opts[:headed],
-  socket_path: Browserctl.socket_path(opts[:name]),
-  pid_path: Browserctl.pid_path(opts[:name])
+  socket_path: Browserctl.socket_path(assigned_name),
+  pid_path: Browserctl.pid_path(assigned_name)
 ).run

data/examples/cloudflare_hitl.rb

@@ -7,7 +7,7 @@
 # pauses automation so a human can solve it in the live browser, then resumes.
 #
 # Run:
-#   browserctl run examples/cloudflare_hitl.rb --url https://example.com
+#   browserctl workflow run examples/cloudflare_hitl.rb --url https://example.com
 #
 # Note: modern Cloudflare often passes a real headed Chrome without challenge.
 # The pause/resume branch fires only when the challenge page is actually served
@@ -22,11 +22,11 @@ Browserctl.workflow "cloudflare_hitl" do
   param :selector, default: "body"
 
   step "open page" do
-    client.open_page("main")
+    open_page(:main)
   end
 
   step "navigate to target URL" do
-    res = client.goto("main", url)
+    res = client.navigate("main", url)
 
     if res[:challenge]
       $stdout.puts ""
@@ -54,12 +54,12 @@ Browserctl.workflow "cloudflare_hitl" do
   end
 
   step "wait for content and snapshot" do
-    page(:main).wait_for(selector, timeout: 15)
+    page(:main).wait(selector, timeout: 15)
     result = page(:main).snapshot(format: "elements")
     $stdout.puts "  Snapshot: #{result[:snapshot]&.length || 0} elements captured"
   end
 
   step "close page" do
-    client.close_page("main")
+    close_page(:main)
   end
 end

data/examples/smoke/params_file.rb

@@ -4,7 +4,7 @@
 # Smoke test for --params file loading (Task 7.5).
 #
 # Run with:
-#   browserctl run examples/smoke/params_file.rb --params examples/smoke/params_file.yml
+#   browserctl workflow run examples/smoke/params_file.rb --params examples/smoke/params_file.yml
 #
 # The workflow logs in using credentials from the params file and asserts
 # the secure area is reached — proving the params were loaded and available.
@@ -17,7 +17,7 @@ Browserctl.workflow "smoke/params_file" do
   param :base_url, default: "https://the-internet.herokuapp.com"
 
   step "open login page" do
-    client.open_page("main", url: "#{base_url}/login")
+    open_page(:main, url: "#{base_url}/login")
   end
 
   step "fill credentials from params file" do
@@ -29,6 +29,7 @@ Browserctl.workflow "smoke/params_file" do
   end
 
   step "assert login succeeded" do
+    page(:main).wait(".flash.success", timeout: 10)
     assert page(:main).url.include?("/secure"), "expected redirect to /secure — params may not have loaded"
     puts "  [ok] reached secure area — params file loaded correctly"
   end

data/examples/smoke/store_fetch.rb

@@ -12,12 +12,12 @@ Browserctl.workflow "smoke/store_fetch" do
   param :base_url, default: "https://the-internet.herokuapp.com"
 
   step "open dynamic loading page" do
-    client.open_page("main", url: "#{base_url}/dynamic_loading/1")
+    open_page(:main, url: "#{base_url}/dynamic_loading/1")
   end
 
   step "click start and capture loaded text" do
     page(:main).click("div#start button")
-    page(:main).wait_for("div#finish", timeout: 10)
+    page(:main).wait("div#finish", timeout: 10)
     text = client.evaluate("main", "document.querySelector('div#finish h4')?.innerText?.trim()")[:result]
     assert text && !text.empty?, "expected loaded text, got: #{text.inspect}"
     store(:loaded_text, text)
@@ -32,8 +32,8 @@ Browserctl.workflow "smoke/store_fetch" do
 
   step "confirm fetch raises for unknown key" do
     fetch(:nonexistent_key)
-    assert false, "expected KeyError was not raised"
-  rescue KeyError => e
-    puts "  [ok] KeyError raised as expected: #{e.message}"
+    assert false, "expected WorkflowError was not raised"
+  rescue Browserctl::WorkflowError => e
+    puts "  [ok] WorkflowError raised as expected: #{e.message}"
   end
 end

data/examples/test_automation_practices/advanced/ab_testing.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/advanced/ab_testing" do
+  desc "A/B testing page: verify one variant renders, click counter increments"
+
+  param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/tap_advanced_ab_testing.png")
+
+  step "open A/B testing page and detect variant" do
+    open_page(:main, url: "#{base_url}/#/ab-testing")
+    page(:main).wait("[data-test='ab-testing-page']", timeout: 10)
+    title = page(:main).evaluate(
+      "document.querySelector('[data-test=\"variant-title\"]')?.textContent?.trim()"
+    )
+    assert title&.length&.positive?, "expected variant title to be present, got: #{title.inspect}"
+    store(:variant_title, title)
+  end
+
+  step "variant title contains A or B" do
+    title = fetch(:variant_title)
+    assert title.include?("A") || title.include?("B"),
+           "expected variant A or B in title, got: #{title.inspect}"
+  end
+
+  step "click button — counter increments" do
+    initial_text = page(:main).evaluate(
+      "document.querySelector('[data-test=\"variant-button\"]')?.textContent?.trim()"
+    )
+    page(:main).click("[data-test='variant-button']")
+    sleep 0.5
+    updated_text = page(:main).evaluate(
+      "document.querySelector('[data-test=\"variant-button\"]')?.textContent?.trim()"
+    )
+    assert initial_text != updated_text,
+           "expected button text to change after click (counter), still: #{updated_text.inspect}"
+    page(:main).screenshot(path: screenshot_path)
+  end
+end