browserctl 0.6.0 → 0.8.0

data/lib/browserctl/server/handlers/interaction.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      module Interaction
+        private
+
+        def cmd_press(req)
+          with_page(req[:name]) do |session|
+            session.page.keyboard.down(req[:key])
+            session.page.keyboard.up(req[:key])
+            { ok: true }
+          end
+        end
+
+        def cmd_hover(req)
+          with_page(req[:name]) do |session|
+            coords = session.page.evaluate(
+              "(function(sel) {   " \
+              "var el = document.querySelector(sel);   " \
+              "if (!el) return null;   " \
+              "var r = el.getBoundingClientRect();   " \
+              "return { x: r.left + r.width / 2, y: r.top + r.height / 2 }; " \
+              "})(#{req[:selector].to_json})"
+            )
+            return { error: "selector not found: #{req[:selector]}" } unless coords
+
+            session.page.mouse.move(x: coords["x"], y: coords["y"])
+            { ok: true }
+          end
+        end
+
+        def cmd_upload(req)
+          path = File.expand_path(req[:path])
+          return { error: "file not found: #{path}" } unless File.exist?(path)
+
+          with_page(req[:name]) do |session|
+            el = session.page.at_css(req[:selector])
+            return { error: "selector not found: #{req[:selector]}" } unless el
+
+            el.select_file(path)
+            { ok: true }
+          end
+        end
+
+        def cmd_select(req)
+          with_page(req[:name]) do |session|
+            el = session.page.at_css(req[:selector])
+            return { error: "selector not found: #{req[:selector]}" } unless el
+
+            el.evaluate(
+              "this.value = #{req[:value].to_json}; " \
+              "this.dispatchEvent(new Event('change', {bubbles: true}))"
+            )
+            { ok: true }
+          end
+        end
+
+        def cmd_dialog_accept(req)
+          session = @global_mutex.synchronize { @pages[req[:name]] }
+          return { error: "no page named '#{req[:name]}'" } unless session
+
+          text = req[:text]
+          id   = nil
+          id = session.page.on(:dialog) do |dialog|
+            session.page.off(:dialog, id)
+            dialog.accept(text)
+          end
+          { ok: true }
+        end
+
+        def cmd_dialog_dismiss(req)
+          session = @global_mutex.synchronize { @pages[req[:name]] }
+          return { error: "no page named '#{req[:name]}'" } unless session
+
+          id = nil
+          id = session.page.on(:dialog) do |dialog|
+            session.page.off(:dialog, id)
+            dialog.dismiss
+          end
+          { ok: true }
+        end
+      end
+    end
+  end
+end

data/lib/browserctl/server/handlers/page_lifecycle.rb

@@ -25,6 +25,10 @@ module Browserctl
         end
 
         def cmd_page_focus(req)
+          unless @browser.options.headless == false
+            return { error: "page focus requires headed mode — start browserd with --headed" }
+          end
+
           with_page(req[:name]) do |session|
             session.page.activate
             { ok: true }

data/lib/browserctl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Browserctl
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

data/lib/browserctl/workflow.rb

@@ -2,11 +2,11 @@
 
 require "timeout"
 require_relative "client"
+require_relative "errors"
+require_relative "secret_resolvers"
 
 module Browserctl
-  class WorkflowError < StandardError; end
-
-  ParamDef = Struct.new(:name, :required, :secret, :default, keyword_init: true)
+  ParamDef = Struct.new(:name, :required, :secret, :default, :secret_ref, keyword_init: true)
   StepResult = Struct.new(:name, :ok, :error, keyword_init: true)
   StepDef = Struct.new(:label, :block, :retry_count, :timeout, keyword_init: true)
 
@@ -67,17 +67,31 @@ module Browserctl
       res
     end
 
-    def load_session(session_name)
+    def load_session(session_name, fallback: nil)
       res = @client.session_load(session_name)
-      raise WorkflowError, res[:error] if res[:error]
+      return res unless res[:error]
 
-      res
+      raise WorkflowError, res[:error] unless fallback
+
+      invoke(fallback.to_s)
+      res2 = @client.session_load(session_name)
+      if res2[:error]
+        raise WorkflowError,
+              "session '#{session_name}' still unavailable after running fallback '#{fallback}'"
+      end
+
+      res2
     end
 
     def list_sessions
       @client.session_list[:sessions]
     end
 
+    def ask(prompt)
+      $stderr.print("[browserctl] #{prompt} ")
+      $stdin.gets.chomp
+    end
+
     def invoke(workflow_name, **override_params)
       name = workflow_name.to_s
       guard_circular!(name)
@@ -137,6 +151,13 @@ module Browserctl
       unwrap @client.storage_set(@name, key, value, store: store)
     end
 
+    def press(key)               = unwrap @client.press(@name, key)
+    def hover(selector)          = unwrap @client.hover(@name, selector)
+    def upload(selector, path)   = unwrap @client.upload(@name, selector, path)
+    def select(selector, value)  = unwrap @client.select(@name, selector, value)
+    def dialog_accept(text: nil) = unwrap @client.dialog_accept(@name, text: text)
+    def dialog_dismiss           = unwrap @client.dialog_dismiss(@name)
+
     private
 
     def unwrap(res)
@@ -160,8 +181,10 @@ module Browserctl
       @description = text
     end
 
-    def param(name, required: false, secret: false, default: nil)
-      @param_defs[name] = ParamDef.new(name: name, required: required, secret: secret, default: default)
+    def param(name, required: false, secret: false, default: nil, secret_ref: nil)
+      secret = true if secret_ref
+      @param_defs[name] =
+        ParamDef.new(name: name, required: required, secret: secret, default: default, secret_ref: secret_ref)
     end
 
     def step(label, retry_count: 0, timeout: nil, &block)
@@ -211,7 +234,11 @@ module Browserctl
 
     def resolve_params(provided)
       @param_defs.each_with_object({}) do |(name, defn), out|
-        val = provided[name] || defn.default
+        val = if defn.secret_ref
+                SecretResolverRegistry.resolve(defn.secret_ref)
+              else
+                provided[name] || defn.default
+              end
         raise WorkflowError, "required param '#{name}' missing" if defn.required && val.nil?
 
         out[name] = val

data/lib/browserctl.rb

@@ -3,6 +3,7 @@
 require_relative "browserctl/version"
 require_relative "browserctl/constants"
 require_relative "browserctl/errors"
+require_relative "browserctl/secret_resolvers"
 require_relative "browserctl/workflow"
 require_relative "browserctl/runner"
 require_relative "browserctl/client"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Patrick
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-28 00:00:00.000000000 Z
+date: 2026-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ferrum
@@ -139,14 +139,26 @@ files:
 - bin/browserd
 - bin/setup
 - examples/cloudflare_hitl.rb
-- examples/smoke/params_file.rb
-- examples/smoke/store_fetch.rb
-- examples/test_automation_practices/checkboxes.rb
-- examples/test_automation_practices/dynamic_elements.rb
-- examples/test_automation_practices/key_press.rb
-- examples/test_automation_practices/login.rb
-- examples/test_automation_practices/login_negative.rb
-- examples/test_automation_practices/notifications.rb
+- examples/test_automation_practices/advanced/ab_testing.rb
+- examples/test_automation_practices/advanced/broken_images.rb
+- examples/test_automation_practices/advanced/file_download.rb
+- examples/test_automation_practices/advanced/iframes.rb
+- examples/test_automation_practices/advanced/shadow_dom.rb
+- examples/test_automation_practices/auth/login.rb
+- examples/test_automation_practices/auth/login_negative.rb
+- examples/test_automation_practices/dialogs/alerts.rb
+- examples/test_automation_practices/dialogs/notifications.rb
+- examples/test_automation_practices/dynamic/dynamic_elements.rb
+- examples/test_automation_practices/dynamic/tables.rb
+- examples/test_automation_practices/forms/checkboxes.rb
+- examples/test_automation_practices/forms/file_upload.rb
+- examples/test_automation_practices/forms/forms.rb
+- examples/test_automation_practices/forms/slider.rb
+- examples/test_automation_practices/interactions/context_menu.rb
+- examples/test_automation_practices/interactions/drag_drop.rb
+- examples/test_automation_practices/interactions/exit_intent.rb
+- examples/test_automation_practices/interactions/hover.rb
+- examples/test_automation_practices/interactions/key_press.rb
 - examples/the_internet/add_remove_elements.rb
 - examples/the_internet/checkboxes.rb
 - examples/the_internet/dropdown.rb
@@ -154,10 +166,12 @@ files:
 - examples/the_internet/login.rb
 - lib/browserctl.rb
 - lib/browserctl/client.rb
+- lib/browserctl/commands/ask.rb
 - lib/browserctl/commands/cli_output.rb
 - lib/browserctl/commands/click.rb
 - lib/browserctl/commands/cookie.rb
 - lib/browserctl/commands/daemon.rb
+- lib/browserctl/commands/dialog.rb
 - lib/browserctl/commands/fill.rb
 - lib/browserctl/commands/init.rb
 - lib/browserctl/commands/page.rb
@@ -175,12 +189,19 @@ files:
 - lib/browserctl/policy.rb
 - lib/browserctl/recording.rb
 - lib/browserctl/runner.rb
+- lib/browserctl/secret_resolver_registry.rb
+- lib/browserctl/secret_resolvers.rb
+- lib/browserctl/secret_resolvers/base.rb
+- lib/browserctl/secret_resolvers/env.rb
+- lib/browserctl/secret_resolvers/macos_keychain.rb
+- lib/browserctl/secret_resolvers/one_password.rb
 - lib/browserctl/server.rb
 - lib/browserctl/server/command_dispatcher.rb
 - lib/browserctl/server/handlers/cookies.rb
 - lib/browserctl/server/handlers/daemon_control.rb
 - lib/browserctl/server/handlers/devtools.rb
 - lib/browserctl/server/handlers/hitl.rb
+- lib/browserctl/server/handlers/interaction.rb
 - lib/browserctl/server/handlers/navigation.rb
 - lib/browserctl/server/handlers/observation.rb
 - lib/browserctl/server/handlers/page_lifecycle.rb

data/examples/smoke/params_file.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-#
-# Smoke test for --params file loading (Task 7.5).
-#
-# Run with:
-#   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.
-
-Browserctl.workflow "smoke/params_file" do
-  desc "Smoke: load credentials from a --params file and use them in a workflow"
-
-  param :username, required: true
-  param :password, required: true, secret: true
-  param :base_url, default: "https://the-internet.herokuapp.com"
-
-  step "open login page" do
-    open_page(:main, url: "#{base_url}/login")
-  end
-
-  step "fill credentials from params file" do
-    puts "  [params] username = #{username.inspect}"
-    puts "  [params] password = (#{password.length} chars, secret)"
-    page(:main).fill("input#username", username)
-    page(:main).fill("input#password", password)
-    page(:main).click("button[type=submit]")
-  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
-end

data/examples/smoke/store_fetch.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-#
-# Smoke test for WorkflowContext#store / #fetch (Task 7.3).
-#
-# Uses the-internet's dynamic loading example: click Start, wait for "Hello World!",
-# capture the text in step 1, assert it is still accessible in step 2 via fetch.
-
-Browserctl.workflow "smoke/store_fetch" do
-  desc "Smoke: store a value in one step and retrieve it in a later step"
-
-  param :base_url, default: "https://the-internet.herokuapp.com"
-
-  step "open dynamic loading page" do
-    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("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)
-    puts "  [store] loaded_text = #{text.inspect}"
-  end
-
-  step "fetch value from previous step and assert" do
-    text = fetch(:loaded_text)
-    puts "  [fetch] loaded_text = #{text.inspect}"
-    assert text == "Hello World!", "expected 'Hello World!', got: #{text.inspect}"
-  end
-
-  step "confirm fetch raises for unknown key" do
-    fetch(:nonexistent_key)
-    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/key_press.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-Browserctl.workflow "test_automation_practices/key_press" do
-  desc "Key press page: dispatch keyboard events, verify last-key display and history list update"
-
-  param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
-  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/test_automation_practices_key_press.png")
-
-  step "open key press page" do
-    open_page(:main, url: "#{base_url}/#/key-press")
-  end
-
-  step "dispatch key events and verify last-key display" do
-    keys = %w[A B C D E]
-    keys.each do |key|
-      client.evaluate(
-        "main",
-        "document.dispatchEvent(new KeyboardEvent('keydown', { key: '#{key}', bubbles: true }))"
-      )
-      sleep 0.1
-    end
-
-    last = client.evaluate("main",
-                           "document.querySelector('[data-test=\"last-key-pressed\"]')?.innerText?.trim()")[:result]
-    assert last == keys.last, "expected last key '#{keys.last}', got: #{last.inspect}"
-    store(:keys, keys)
-  end
-
-  step "verify key history contains all dispatched keys" do
-    keys = fetch(:keys)
-    history = client.evaluate(
-      "main",
-      "Array.from(document.querySelectorAll('[data-test^=\"key-\"]')).map(el => el.innerText?.trim())"
-    )[:result]
-    # History shows most recent first; each entry typically contains the key label
-    keys.each do |key|
-      assert history.any? { |entry| entry&.include?(key) }, "expected '#{key}' in history, got: #{history.inspect}"
-    end
-    page(:main).screenshot(path: screenshot_path)
-  end
-end