browserctl 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37a7ccbe134ac1d42b514959c3db2ed17fd0229fdaed839842cf0af4a872d132
-  data.tar.gz: cea2a653eab69d4f544612122deb1bffe7827fca546b74c6f17f5fa8a16c6e8d
+  metadata.gz: e63d2425e4bbd57beefebf31e3f616a3183823f467b08c89ba6a1e2bb32cca0b
+  data.tar.gz: 8f12b646d805237a46b2bba2c194fb91c21834dc78648db97a4f74b0cc672de6
 SHA512:
-  metadata.gz: 4bcf1b0d2200b774305555ec8d777d243556b4cb02c3aa7fc015392e6adec331613d17b020b0933212983914a8920beeab511b4dddadab7a2ee45f163897b84b
-  data.tar.gz: 551860c7cefd52148d764146e98083deb5c2cdea07e67fe458e33abf420c05a26e2783e763839e3bdd9011a0668a8fb1819f9284c97a47e746057afc3afeb6c3
+  metadata.gz: 50521d3c938c009818d85c93b793c55f5ec2b6d7ae64ec0daae5bf337d793f795189f870d1451d5dca18b285c428a2dd48ec1c0b6af210e6e7c3b41a49c14989
+  data.tar.gz: fe973906dbfe35134aaa32c2e3080196febaa99dc4c8858683ceb9a9e41579f9a40b7ca7865af67ba946a6b2acc68dd7bafa31036daafeebe96e23edbd3f53c6

data/CHANGELOG.md

@@ -10,6 +10,20 @@ 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.8.0](https://github.com/patrick204nqh/browserctl/compare/v0.7.0...v0.8.0) (2026-04-29)
+
+
+### Features
+
+* **v0.8:** secret resolver plugin system + load_session fallback ([#54](https://github.com/patrick204nqh/browserctl/issues/54)) ([69737bf](https://github.com/patrick204nqh/browserctl/commit/69737bf10528ad691a31abf916953325637af597))
+
+## [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)
 
 

data/bin/browserctl

@@ -27,6 +27,8 @@ 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]
@@ -62,7 +64,14 @@ def usage
       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>
@@ -127,6 +136,7 @@ case cmd
 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))
@@ -166,6 +176,25 @@ else
     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)

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

data/examples/test_automation_practices/advanced/broken_images.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/advanced/broken_images" do
+  desc "Broken images page: verify one image loads successfully and two are broken (naturalWidth == 0)"
+
+  param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/tap_advanced_broken_images.png")
+
+  step "open broken images page" do
+    open_page(:main, url: "#{base_url}/#/broken-images")
+    page(:main).wait("[data-test='image-container-0']", timeout: 10)
+    sleep 1
+  end
+
+  step "check which images loaded and which are broken" do
+    widths = page(:main).evaluate(
+      "[0,1,2].map(i => document.querySelector(`[data-test=\"image-${i}\"]`)?.naturalWidth ?? -1)"
+    )
+    loaded  = widths.count(&:positive?)
+    broken  = widths.count(&:zero?)
+    assert loaded == 1, "expected exactly 1 valid image, got #{loaded} (widths: #{widths.inspect})"
+    assert broken == 2, "expected exactly 2 broken images, got #{broken} (widths: #{widths.inspect})"
+    page(:main).screenshot(path: screenshot_path)
+  end
+end

data/examples/test_automation_practices/advanced/file_download.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/advanced/file_download" do
+  desc "File download page: trigger each download, verify button enters disabled state, verify no error shown"
+
+  param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/tap_advanced_file_download.png")
+
+  step "open file download page" do
+    open_page(:main, url: "#{base_url}/#/file-download")
+    page(:main).wait("[data-test='download-card-0']", timeout: 10)
+  end
+
+  step "click TXT download — button becomes disabled during download" do
+    page(:main).click("[data-test='download-button-0']")
+    page(:main).wait("[data-test='download-button-0'][disabled]", timeout: 5)
+    disabled = page(:main).evaluate(
+      "document.querySelector('[data-test=\"download-button-0\"]')?.disabled"
+    )
+    assert disabled, "expected download-button-0 to be disabled while downloading"
+    page(:main).wait("[data-test='download-button-0']:not([disabled])", timeout: 10)
+    no_error = page(:main).evaluate("!document.querySelector('[data-test=\"error-message\"]')")
+    assert no_error, "expected no error-message after TXT download"
+  end
+
+  step "click CSV download — completes without error" do
+    page(:main).click("[data-test='download-button-1']")
+    page(:main).wait("[data-test='download-button-1']:not([disabled])", timeout: 10)
+    no_error = page(:main).evaluate("!document.querySelector('[data-test=\"error-message\"]')")
+    assert no_error, "expected no error-message after CSV download"
+  end
+
+  step "click PDF download — completes without error" do
+    page(:main).click("[data-test='download-button-2']")
+    page(:main).wait("[data-test='download-button-2']:not([disabled])", timeout: 10)
+    no_error = page(:main).evaluate("!document.querySelector('[data-test=\"error-message\"]')")
+    assert no_error, "expected no error-message after PDF download"
+    page(:main).screenshot(path: screenshot_path)
+  end
+end

data/examples/test_automation_practices/advanced/iframes.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/advanced/iframes" do
+  desc "Iframes page: click inside sandboxed iframes, verify postMessage received in parent"
+
+  param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/tap_advanced_iframes.png")
+
+  step "open iframes page" do
+    open_page(:main, url: "#{base_url}/#/iframes")
+    page(:main).wait("[data-test='iframe-container']", timeout: 10)
+    sleep 0.5
+  end
+
+  step "click button inside iframe1 — message appears in parent" do
+    page(:main).evaluate(
+      "document.querySelector('[data-test=\"iframe-iframe1\"]').contentDocument.querySelector('button').click()"
+    )
+    page(:main).wait("[data-test='iframe-message-0']", timeout: 5)
+    msg = page(:main).evaluate(
+      "document.querySelector('[data-test=\"iframe-message-0\"]')?.textContent?.trim()"
+    )
+    assert msg&.length&.positive?, "expected a message after clicking iframe1 button, got: #{msg.inspect}"
+    page(:main).screenshot(path: screenshot_path)
+  end
+
+  step "click button inside iframe2 — second message appears" do
+    page(:main).evaluate(
+      "document.querySelector('[data-test=\"iframe-iframe2\"]').contentDocument.querySelector('button').click()"
+    )
+    page(:main).wait("[data-test='iframe-message-1']", timeout: 5)
+    count = page(:main).evaluate(
+      "document.querySelectorAll('[data-test^=\"iframe-message-\"]').length"
+    )
+    assert count >= 2, "expected at least 2 messages after both iframe clicks, got: #{count}"
+  end
+end

data/examples/test_automation_practices/advanced/shadow_dom.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/advanced/shadow_dom" do
+  desc "Shadow DOM page: query inside shadow root, click shadow-button, accept its alert"
+
+  param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/tap_advanced_shadow_dom.png")
+
+  step "open shadow DOM page" do
+    open_page(:main, url: "#{base_url}/#/shadow-dom")
+    page(:main).wait("[data-test='shadow-host']", timeout: 10)
+  end
+
+  step "verify shadow content is accessible via shadowRoot" do
+    text = page(:main).evaluate(
+      "document.querySelector('[data-test=\"shadow-host\"]').shadowRoot" \
+      "?.querySelector('[data-test=\"shadow-content\"]')?.textContent?.trim()"
+    )
+    assert text&.length&.positive?, "expected shadow-content text via shadowRoot, got: #{text.inspect}"
+    page(:main).screenshot(path: screenshot_path)
+  end
+
+  step "click shadow-button — accept the alert — page stays responsive" do
+    page(:main).dialog_accept
+    page(:main).evaluate(
+      "document.querySelector('[data-test=\"shadow-host\"]').shadowRoot" \
+      ".querySelector('[data-test=\"shadow-button\"]').click()"
+    )
+    sleep 0.3
+    still_present = page(:main).evaluate(
+      "!!document.querySelector('[data-test=\"shadow-host\"]')"
+    )
+    assert still_present, "expected shadow-host to remain in DOM after alert was accepted"
+  end
+end

data/examples/test_automation_practices/{login.rb → auth/login.rb}

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-Browserctl.workflow "test_automation_practices/login" do
+Browserctl.workflow "test_automation_practices/auth/login" do
   desc "Auth page: fill credentials, verify success message, logout"
 
   param :username,        default: "admin"
   param :password,        default: "admin", secret: true
   param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
-  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/test_automation_practices_login.png")
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/tap_auth_login.png")
 
   step "open auth page" do
     open_page(:main, url: "#{base_url}/#/auth")
@@ -20,7 +20,7 @@ Browserctl.workflow "test_automation_practices/login" do
 
   step "verify successful login" do
     page(:main).wait("[data-test='auth-success']", timeout: 10)
-    msg = client.evaluate("main", "document.querySelector('[data-test=\"auth-success\"]')?.innerText?.trim()")[:result]
+    msg = page(:main).evaluate("document.querySelector('[data-test=\"auth-success\"]')?.innerText?.trim()")
     assert msg&.length&.positive?, "expected a success message, got: #{msg.inspect}"
     page(:main).screenshot(path: screenshot_path)
   end
@@ -28,7 +28,7 @@ Browserctl.workflow "test_automation_practices/login" do
   step "logout and verify form reappears" do
     page(:main).click("[data-test='logout-button']")
     page(:main).wait("[data-test='login-button']", timeout: 5)
-    visible = client.evaluate("main", "!!document.querySelector('[data-test=\"login-button\"]')")[:result]
+    visible = page(:main).evaluate("!!document.querySelector('[data-test=\"login-button\"]')")
     assert visible, "expected login form to reappear after logout"
   end
 end

data/examples/test_automation_practices/{login_negative.rb → auth/login_negative.rb}

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-Browserctl.workflow "test_automation_practices/login_negative" do
+Browserctl.workflow "test_automation_practices/auth/login_negative" do
   desc "Auth page: invalid credentials show an error message"
 
   param :base_url, default: "https://moatazeldebsy.github.io/test-automation-practices"
   param :screenshot_path,
-        default: File.expand_path(".browserctl/screenshots/test_automation_practices_login_negative.png")
+        default: File.expand_path(".browserctl/screenshots/tap_auth_login_negative.png")
 
   step "open auth page" do
     open_page(:main, url: "#{base_url}/#/auth")
@@ -19,9 +19,9 @@ Browserctl.workflow "test_automation_practices/login_negative" do
 
   step "verify error is shown and success is absent" do
     page(:main).wait("[data-test='auth-error']", timeout: 10)
-    error = client.evaluate("main", "document.querySelector('[data-test=\"auth-error\"]')?.innerText?.trim()")[:result]
+    error = page(:main).evaluate("document.querySelector('[data-test=\"auth-error\"]')?.innerText?.trim()")
     assert error&.length&.positive?, "expected an error message, got: #{error.inspect}"
-    no_success = client.evaluate("main", "!document.querySelector('[data-test=\"auth-success\"]')")[:result]
+    no_success = page(:main).evaluate("!document.querySelector('[data-test=\"auth-success\"]')")
     assert no_success, "expected no success element when credentials are invalid"
     page(:main).screenshot(path: screenshot_path)
   end

data/examples/test_automation_practices/dialogs/alerts.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/dialogs/alerts" do
+  desc "Alerts page: pre-register accept/dismiss handlers before triggering each JS dialog type"
+
+  param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/tap_dialogs_alerts.png")
+
+  step "open alerts page" do
+    open_page(:main, url: "#{base_url}/#/alerts")
+  end
+
+  step "accept an alert — result-container shows confirmation" do
+    page(:main).dialog_accept
+    page(:main).click("[data-test='alert-button']")
+    page(:main).wait("[data-test='result-container']", timeout: 5)
+    result = page(:main).evaluate("document.querySelector('[data-test=\"result-container\"]')?.textContent?.trim()")
+    assert result == "Last action: Alert shown", "expected alert result, got: #{result.inspect}"
+  end
+
+  step "accept a confirm — result-container shows true" do
+    page(:main).dialog_accept
+    page(:main).click("[data-test='confirm-button']")
+    page(:main).wait("[data-test='result-container']", timeout: 5)
+    result = page(:main).evaluate("document.querySelector('[data-test=\"result-container\"]')?.textContent?.trim()")
+    assert result == "Last action: Confirm dialog: true", "expected confirm true result, got: #{result.inspect}"
+  end
+
+  step "dismiss a confirm — result-container shows false" do
+    page(:main).dialog_dismiss
+    page(:main).click("[data-test='confirm-button']")
+    page(:main).wait("[data-test='result-container']", timeout: 5)
+    result = page(:main).evaluate("document.querySelector('[data-test=\"result-container\"]')?.textContent?.trim()")
+    assert result == "Last action: Confirm dialog: false", "expected confirm false result, got: #{result.inspect}"
+  end
+
+  step "accept a prompt with text — result-container shows entered text" do
+    page(:main).dialog_accept(text: "browserctl")
+    page(:main).click("[data-test='prompt-button']")
+    page(:main).wait("[data-test='result-container']", timeout: 5)
+    result = page(:main).evaluate("document.querySelector('[data-test=\"result-container\"]')?.textContent?.trim()")
+    assert result&.include?("browserctl"), "expected prompt text in result, got: #{result.inspect}"
+    page(:main).screenshot(path: screenshot_path)
+  end
+end

data/examples/test_automation_practices/{notifications.rb → dialogs/notifications.rb}

@@ -6,36 +6,36 @@ NOTIFICATION_ITEMS_JS = <<~JS
   document.querySelectorAll('[data-test^="notification-"]:not([data-test="notification-container"])').length
 JS
 
-Browserctl.workflow "test_automation_practices/notifications" do
+Browserctl.workflow "test_automation_practices/dialogs/notifications" do
   desc "Notifications: trigger success, error, and info toasts — verify count increases on each trigger"
 
   param :base_url, default: "https://moatazeldebsy.github.io/test-automation-practices"
   param :screenshot_path,
-        default: File.expand_path(".browserctl/screenshots/test_automation_practices_notifications.png")
+        default: File.expand_path(".browserctl/screenshots/tap_dialogs_notifications.png")
 
   step "open notifications page and record baseline" do
     open_page(:main, url: "#{base_url}/#/notifications")
     page(:main).wait("[data-test='notification-container']", timeout: 5)
     # Let any delayed on-load notifications finish appearing before we snapshot the baseline
     sleep 1
-    store(:baseline, client.evaluate("main", NOTIFICATION_ITEMS_JS)[:result])
+    store(:baseline, page(:main).evaluate(NOTIFICATION_ITEMS_JS))
   end
 
   step "trigger success notification and verify count increased by 1" do
     base = fetch(:baseline)
     page(:main).click("[data-test='add-success']")
     page(:main).wait("[data-test^='notification-']:not([data-test='notification-container'])", timeout: 5)
-    count = client.evaluate("main", NOTIFICATION_ITEMS_JS)[:result]
+    count = page(:main).evaluate(NOTIFICATION_ITEMS_JS)
     assert count == base + 1, "expected #{base + 1} notifications after success, got: #{count}"
   end
 
   step "dismiss one notification and verify count returns to baseline" do
     base = fetch(:baseline)
-    client.evaluate("main", "document.querySelector('[data-test^=\"close-notification-\"]')?.click()")
+    page(:main).evaluate("document.querySelector('[data-test^=\"close-notification-\"]')?.click()")
     deadline = Time.now + 5
     remaining = nil
     loop do
-      remaining = client.evaluate("main", NOTIFICATION_ITEMS_JS)[:result]
+      remaining = page(:main).evaluate(NOTIFICATION_ITEMS_JS)
       break if remaining <= base || Time.now > deadline
 
       sleep 0.2
@@ -50,7 +50,7 @@ Browserctl.workflow "test_automation_practices/notifications" do
     page(:main).click("[data-test='add-error']")
     page(:main).click("[data-test='add-info']")
     page(:main).wait("[data-test^='notification-']:not([data-test='notification-container'])", timeout: 5)
-    count = client.evaluate("main", NOTIFICATION_ITEMS_JS)[:result]
+    count = page(:main).evaluate(NOTIFICATION_ITEMS_JS)
     assert count == base + 2, "expected #{base + 2} notifications (error + info), got: #{count}"
     page(:main).screenshot(path: screenshot_path)
   end

data/examples/test_automation_practices/{dynamic_elements.rb → dynamic/dynamic_elements.rb}

@@ -1,18 +1,18 @@
 # frozen_string_literal: true
 
-Browserctl.workflow "test_automation_practices/dynamic_elements" do
+Browserctl.workflow "test_automation_practices/dynamic/dynamic_elements" do
   desc "Dynamic elements: trigger reload, wait for items, toggle hidden content"
 
   param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
   param :screenshot_path,
-        default: File.expand_path(".browserctl/screenshots/test_automation_practices_dynamic_elements.png")
+        default: File.expand_path(".browserctl/screenshots/tap_dynamic_dynamic_elements.png")
 
   step "open dynamic elements page" do
     open_page(:main, url: "#{base_url}/#/dynamic-elements")
   end
 
   step "assert no dynamic items exist before reload" do
-    absent = client.evaluate("main", "!document.querySelector('[data-test=\"dynamic-item-0\"]')")[:result]
+    absent = page(:main).evaluate("!document.querySelector('[data-test=\"dynamic-item-0\"]')")
     assert absent, "expected no dynamic items before triggering reload"
   end
 
@@ -23,10 +23,9 @@ Browserctl.workflow "test_automation_practices/dynamic_elements" do
   end
 
   step "verify all three dynamic items are present" do
-    count = client.evaluate(
-      "main",
+    count = page(:main).evaluate(
       "[0,1,2].filter(i => !!document.querySelector(`[data-test=\"dynamic-item-${i}\"]`)).length"
-    )[:result]
+    )
     assert count == 3, "expected 3 dynamic items, got: #{count}"
     page(:main).screenshot(path: screenshot_path)
   end
@@ -34,7 +33,9 @@ Browserctl.workflow "test_automation_practices/dynamic_elements" do
   step "toggle hidden content on" do
     page(:main).click("[data-test='toggle-hidden-button']")
     page(:main).wait("[data-test='hidden-content']", timeout: 5)
-    visible = client.evaluate("main", "!!document.querySelector('[data-test=\"hidden-content\"]')")[:result]
-    assert visible, "expected hidden content to appear after toggle"
+    visible = page(:main).evaluate(
+      "!document.querySelector('[data-test=\"hidden-content\"]')?.classList.contains('hidden')"
+    )
+    assert visible, "expected hidden-content to become visible after toggle (hidden class should be absent)"
   end
 end

data/examples/test_automation_practices/dynamic/tables.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/dynamic/tables" do
+  desc "Tables page: verify initial data, sort by column ascending and descending"
+
+  param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/tap_dynamic_tables.png")
+
+  step "open tables page and verify initial rows" do
+    open_page(:main, url: "#{base_url}/#/tables")
+    page(:main).wait("[data-test='dynamic-table']", timeout: 10)
+    rows = page(:main).evaluate(
+      "Array.from(document.querySelectorAll('[data-test^=\"table-row-\"]')).map(r => r.dataset.test)"
+    )
+    assert rows.length == 3, "expected 3 rows, got: #{rows.length}"
+  end
+
+  step "sort by name ascending — alphabetical order" do
+    page(:main).click("[data-test='table-header-name']")
+    sleep 0.2
+    names = page(:main).evaluate(
+      "Array.from(document.querySelectorAll('[data-test^=\"table-cell-name-\"]')).map(el => el.textContent?.trim())"
+    )
+    sorted = names.sort
+    assert names == sorted, "expected names sorted ascending, got: #{names.inspect}"
+    page(:main).screenshot(path: screenshot_path)
+  end
+
+  step "sort by name descending — click header again" do
+    page(:main).click("[data-test='table-header-name']")
+    sleep 0.2
+    names = page(:main).evaluate(
+      "Array.from(document.querySelectorAll('[data-test^=\"table-cell-name-\"]')).map(el => el.textContent?.trim())"
+    )
+    sorted_desc = names.sort.reverse
+    assert names == sorted_desc, "expected names sorted descending, got: #{names.inspect}"
+  end
+
+  step "sort by status — Active/Inactive grouping" do
+    page(:main).click("[data-test='table-header-status']")
+    sleep 0.2
+    statuses = page(:main).evaluate(
+      "Array.from(document.querySelectorAll('[data-test^=\"table-cell-status-\"]')).map(el => el.textContent?.trim())"
+    )
+    assert statuses == statuses.sort, "expected statuses sorted ascending, got: #{statuses.inspect}"
+  end
+end

data/examples/test_automation_practices/{checkboxes.rb → forms/checkboxes.rb}

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-Browserctl.workflow "test_automation_practices/checkboxes" do
+Browserctl.workflow "test_automation_practices/forms/checkboxes" do
   desc "Checkboxes: toggle individual, check all, uncheck all — assert state each time"
 
   param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
-  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/test_automation_practices_checkboxes.png")
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/tap_forms_checkboxes.png")
 
   step "open checkboxes page" do
     open_page(:main, url: "#{base_url}/#/checkboxes")
@@ -12,20 +12,20 @@ Browserctl.workflow "test_automation_practices/checkboxes" do
 
   step "read initial state — checkbox 2 pre-checked" do
     js = "[1,2,3].map(i => document.querySelector(`[data-test=\"checkbox-checkbox${i}\"]`)?.checked)"
-    states = client.evaluate("main", js)[:result]
+    states = page(:main).evaluate(js)
     assert states == [false, true, false], "expected initial state [false, true, false], got: #{states.inspect}"
   end
 
   step "toggle checkbox 1 on" do
     page(:main).click("[data-test='checkbox-checkbox1']")
-    checked = client.evaluate("main", "document.querySelector('[data-test=\"checkbox-checkbox1\"]').checked")[:result]
+    checked = page(:main).evaluate("document.querySelector('[data-test=\"checkbox-checkbox1\"]').checked")
     assert checked, "expected checkbox 1 to be checked after click"
   end
 
   step "check all and verify" do
     page(:main).click("[data-test='check-all-button']")
     js = "[1,2,3].map(i => document.querySelector(`[data-test=\"checkbox-checkbox${i}\"]`)?.checked)"
-    states = client.evaluate("main", js)[:result]
+    states = page(:main).evaluate(js)
     assert states.all?, "expected all checkboxes checked, got: #{states.inspect}"
     page(:main).screenshot(path: screenshot_path)
   end
@@ -33,7 +33,7 @@ Browserctl.workflow "test_automation_practices/checkboxes" do
   step "uncheck all and verify" do
     page(:main).click("[data-test='uncheck-all-button']")
     js = "[1,2,3].map(i => document.querySelector(`[data-test=\"checkbox-checkbox${i}\"]`)?.checked)"
-    states = client.evaluate("main", js)[:result]
+    states = page(:main).evaluate(js)
     assert states.none?, "expected all checkboxes unchecked, got: #{states.inspect}"
   end
 end

data/examples/test_automation_practices/forms/file_upload.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/forms/file_upload" do
+  desc "File upload page: attach a local file via the hidden file input, verify the file is selected"
+
+  param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path,
+        default: File.expand_path(".browserctl/screenshots/tap_forms_file_upload.png")
+
+  step "open file upload page" do
+    open_page(:main, url: "#{base_url}/#/file-upload")
+    page(:main).wait("[data-test='file-uploader']", timeout: 10)
+  end
+
+  step "upload a file and verify it is selected" do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "browserctl_test.txt")
+      File.write(path, "browserctl v0.7 upload test")
+
+      page(:main).upload("[data-test='file-input']", path)
+      page(:main).wait("[data-test='uploaded-file-0']", timeout: 10)
+
+      filename = page(:main).evaluate(
+        "document.querySelector('[data-test=\"uploaded-file-0\"]')?.querySelector('span.truncate')?.textContent?.trim()"
+      )
+      assert filename == "browserctl_test.txt", "expected filename in list, got: #{filename.inspect}"
+    end
+    page(:main).screenshot(path: screenshot_path)
+  end
+end