browserctl 0.5.0 → 0.7.0

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

@@ -81,32 +81,6 @@ module Browserctl
           name_safe = page_name.to_s.gsub(/[^a-zA-Z0-9_-]/, "_")
           File.join(SCREENSHOT_DIR, "browserctl_shot_#{name_safe}_#{Time.now.to_i}.png")
         end
-
-        def cmd_wait_for(req)
-          with_page(req[:name]) do |session|
-            wait_for_selector(session.page, req[:selector], req.fetch(:timeout, 10).to_f)
-          end
-        end
-
-        def cmd_watch(req)
-          with_page(req[:name]) do |session|
-            result = wait_for_selector(session.page, req[:selector], req.fetch(:timeout, 30).to_f)
-            result[:error] ? result : { ok: true, selector: req[:selector] }
-          end
-        end
-
-        def wait_for_selector(page, selector, timeout)
-          deadline = Time.now + timeout
-          loop do
-            found = page.at_css(selector)
-            break { ok: true } if found
-            if Time.now >= deadline
-              break { error: "wait_for timeout: selector '#{selector}' not found after #{timeout}s" }
-            end
-
-            sleep 0.2
-          end
-        end
       end
     end
   end

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

@@ -6,7 +6,7 @@ module Browserctl
       module PageLifecycle
         private
 
-        def cmd_open_page(req)
+        def cmd_page_open(req)
           session = @global_mutex.synchronize do
             @pages[req[:name]] ||= PageSession.new(@browser.create_page)
           end
@@ -14,15 +14,26 @@ module Browserctl
           { ok: true, name: req[:name] }
         end
 
-        def cmd_close_page(req)
+        def cmd_page_close(req)
           session = @global_mutex.synchronize { @pages.delete(req[:name]) }
           session&.page&.close
           { ok: true }
         end
 
-        def cmd_list_pages(_req)
+        def cmd_page_list(_req)
           { pages: @global_mutex.synchronize { @pages.keys } }
         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 }
+          end
+        end
       end
     end
   end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "../../session"
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      module Session
+        private
+
+        def cmd_session_save(req)
+          first_session = @global_mutex.synchronize { @pages.values.first }
+          return { error: "no open pages — open a page before saving a session" } unless first_session
+
+          cookies = first_session.page.cookies.all.values.map(&:to_h)
+
+          pages_meta    = {}
+          local_storage = {}
+          @global_mutex.synchronize { @pages.dup }.each do |page_name, session|
+            session.mutex.synchronize do
+              origin    = session.page.evaluate("location.origin")
+              local_str = session.page.evaluate("JSON.stringify({...localStorage})")
+              pages_meta[page_name] = { url: session.page.current_url, title: session.page.title }
+              local_storage[origin] = JSON.parse(local_str)
+            end
+          end
+
+          now = Time.now.iso8601
+          Browserctl::Session.save(
+            req[:session_name],
+            metadata: { version: 1, name: req[:session_name],
+                        created_at: now, updated_at: now, pages: pages_meta },
+            cookies: cookies,
+            local_storage: local_storage,
+            session_storage: {}
+          )
+          { ok: true, path: Browserctl::Session.path(req[:session_name]),
+            pages: pages_meta.length, cookies: cookies.length }
+        end
+
+        def cmd_session_load(req)
+          data = Browserctl::Session.load(req[:session_name])
+
+          data[:metadata][:pages].each do |page_name, page_data|
+            existing = @global_mutex.synchronize { @pages[page_name.to_s] }
+            if existing
+              existing.page.go_to(page_data[:url])
+            else
+              new_page = @browser.create_page
+              new_page.go_to(page_data[:url])
+              @global_mutex.synchronize { @pages[page_name.to_s] = PageSession.new(new_page) }
+            end
+          end
+
+          seed_session = @global_mutex.synchronize { @pages.values.first }
+          cookie_count = data[:cookies].length
+          data[:cookies].each { |c| seed_session.page.cookies.set(**c.slice(:name, :value, :domain, :path)) }
+
+          ls_key_count = 0
+          data[:local_storage].each do |origin, keys|
+            next if keys.empty?
+
+            tmp_page = @browser.create_page
+            begin
+              tmp_page.go_to(origin)
+              keys.each do |k, v|
+                tmp_page.evaluate("localStorage.setItem(#{k.to_json}, #{v.to_json})")
+                ls_key_count += 1
+              end
+            ensure
+              tmp_page.close
+            end
+          end
+
+          { ok: true, cookies: cookie_count, pages: data[:metadata][:pages].length,
+            local_storage_keys: ls_key_count }
+        rescue RuntimeError => e
+          { error: e.message }
+        end
+
+        def cmd_session_list(_req)
+          sessions = Browserctl::Session.all
+          { ok: true, sessions: sessions }
+        end
+
+        def cmd_session_delete(req)
+          Browserctl::Session.delete(req[:session_name])
+          { ok: true }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      module Storage
+        private
+
+        # Returns { ok: true, value: } or { error: }
+        def cmd_storage_get(req)
+          with_page(req[:name]) do |session|
+            store = req.fetch(:store, "local")
+            js    = storage_js_get(store, req[:key])
+            return { error: "unknown store '#{store}' — use 'local' or 'session'" } unless js
+
+            value = session.page.evaluate(js)
+            { ok: true, value: value }
+          end
+        end
+
+        # Returns { ok: true } or { error: }
+        def cmd_storage_set(req)
+          with_page(req[:name]) do |session|
+            store = req.fetch(:store, "local")
+            js    = storage_js_set(store, req[:key], req[:value])
+            return { error: "unknown store '#{store}' — use 'local' or 'session'" } unless js
+
+            session.page.evaluate(js)
+            { ok: true }
+          end
+        end
+
+        # Exports localStorage and/or sessionStorage to a JSON file.
+        # Returns { ok: true, path:, key_count: } or { error: }
+        def cmd_storage_export(req)
+          with_page(req[:name]) do |session|
+            stores  = req.fetch(:stores, "all")
+            data    = {}
+
+            origin = session.page.evaluate("location.origin")
+            data[origin] = {}
+
+            if %w[local all].include?(stores)
+              local = JSON.parse(session.page.evaluate("JSON.stringify({...localStorage})") || "{}")
+              data[origin].merge!(local)
+            end
+
+            if %w[session all].include?(stores)
+              sess = JSON.parse(session.page.evaluate("JSON.stringify({...sessionStorage})") || "{}")
+              data[origin].merge!(sess)
+            end
+
+            path = File.expand_path(req[:path])
+            FileUtils.mkdir_p(File.dirname(path))
+            File.write(path, JSON.generate(data))
+            { ok: true, path: path, key_count: data[origin].length }
+          end
+        end
+
+        # Imports keys from a JSON file into the page's localStorage only.
+        # sessionStorage keys in the file are ignored (sessionStorage is tab-scoped and not restorable).
+        # Returns { ok: true, origins: N, key_count: M } or { error: }
+        def cmd_storage_import(req)
+          path = File.expand_path(req[:path])
+          return { error: "file not found: #{path}" } unless File.exist?(path)
+
+          data = JSON.parse(File.read(path))
+          return { error: "invalid storage file format" } unless data.is_a?(Hash)
+
+          with_page(req[:name]) do |session|
+            key_count = 0
+            data.each_value do |keys|
+              keys.each do |k, v|
+                session.page.evaluate("localStorage.setItem(#{k.to_json}, #{v.to_json})")
+                key_count += 1
+              end
+            end
+            { ok: true, origins: data.length, key_count: key_count }
+          end
+        end
+
+        # Clears localStorage and/or sessionStorage for the page.
+        # Returns { ok: true } or { error: }
+        def cmd_storage_delete(req)
+          with_page(req[:name]) do |session|
+            stores = req.fetch(:stores, "all")
+            session.page.evaluate("localStorage.clear()")   if %w[local all].include?(stores)
+            session.page.evaluate("sessionStorage.clear()") if %w[session all].include?(stores)
+            { ok: true }
+          end
+        end
+
+        def storage_js_get(store, key)
+          case store
+          when "local"   then "localStorage.getItem(#{key.to_json})"
+          when "session" then "sessionStorage.getItem(#{key.to_json})"
+          end
+        end
+
+        def storage_js_set(store, key, value)
+          case store
+          when "local"   then "localStorage.setItem(#{key.to_json}, #{value.to_json})"
+          when "session" then "sessionStorage.setItem(#{key.to_json}, #{value.to_json})"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/browserctl/server.rb

@@ -76,7 +76,7 @@ module Browserctl
       return unless pid.positive?
 
       Process.kill(0, pid)
-      abort "browserd already running (PID #{pid}). Use 'browserctl shutdown' first."
+      abort "browserd already running (PID #{pid}). Use 'browserctl daemon stop' first."
     rescue Errno::ESRCH
       # Dead process — stale PID file, safe to continue
     rescue Errno::EPERM
@@ -125,7 +125,7 @@ module Browserctl
 
     def quietly
       yield
-    rescue Exception # rubocop:disable Lint/RescueException
+    rescue Exception
       nil
     end
   end

data/lib/browserctl/session.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require_relative "constants"
+
+module Browserctl
+  class Session
+    BASE_DIR = File.join(BROWSERCTL_DIR, "sessions")
+
+    SAFE_NAME = /\A[a-zA-Z0-9_-]{1,64}\z/
+
+    def self.path(name)    = File.join(BASE_DIR, name)
+    def self.exist?(name)  = Dir.exist?(path(name))
+
+    def self.delete(name)
+      validate_name!(name)
+      FileUtils.rm_rf(path(name))
+    end
+
+    def self.all
+      Dir[File.join(BASE_DIR, "*/metadata.json")].filter_map { |f| load_meta(f) }
+    end
+
+    def self.save(session_name, metadata:, cookies:, local_storage:, session_storage:)
+      validate_name!(session_name)
+      dir = path(session_name)
+      FileUtils.mkdir_p(dir)
+      write_json(File.join(dir, "metadata.json"),     metadata)
+      write_secret(File.join(dir, "cookies.json"),    cookies)
+      write_secret(File.join(dir, "local_storage.json"), local_storage)
+      return if session_storage.empty?
+
+      write_secret(File.join(dir, "session_storage.json"), session_storage)
+    end
+
+    def self.load(session_name)
+      validate_name!(session_name)
+      dir = path(session_name)
+      raise "session '#{session_name}' not found" unless Dir.exist?(dir)
+
+      {
+        metadata: JSON.parse(File.read(File.join(dir, "metadata.json")), symbolize_names: true),
+        cookies: JSON.parse(File.read(File.join(dir, "cookies.json")), symbolize_names: true),
+        local_storage: JSON.parse(File.read(File.join(dir, "local_storage.json")), symbolize_names: false),
+        session_storage: load_session_storage(dir)
+      }
+    end
+
+    def self.load_meta(path)
+      JSON.parse(File.read(path), symbolize_names: true)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def self.validate_name!(name)
+      return if SAFE_NAME.match?(name.to_s)
+
+      raise ArgumentError, "invalid session name #{name.inspect} — use letters, digits, _ or - (max 64 chars)"
+    end
+
+    def self.load_session_storage(dir)
+      ss_path = File.join(dir, "session_storage.json")
+      File.exist?(ss_path) ? JSON.parse(File.read(ss_path), symbolize_names: false) : {}
+    end
+    private_class_method :load_session_storage
+
+    def self.write_json(path, data)
+      File.write(path, JSON.generate(data))
+    end
+    private_class_method :write_json
+
+    # Cookies and storage contain secrets — restrict to owner read/write only.
+    def self.write_secret(path, data)
+      File.open(path, "w", 0o600) { |f| f.write(JSON.generate(data)) }
+    end
+    private_class_method :write_secret
+  end
+end

data/lib/browserctl/version.rb

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

data/lib/browserctl/workflow.rb

@@ -47,19 +47,42 @@ module Browserctl
     end
 
     def open_page(page_name, url: nil)
-      res = @client.open_page(page_name.to_s, url: url)
+      res = @client.page_open(page_name.to_s, url: url)
       raise WorkflowError, res[:error] if res[:error]
 
       res
     end
 
     def close_page(page_name)
-      res = @client.close_page(page_name.to_s)
+      res = @client.page_close(page_name.to_s)
       raise WorkflowError, res[:error] if res[:error]
 
       res
     end
 
+    def save_session(session_name)
+      res = @client.session_save(session_name)
+      raise WorkflowError, res[:error] if res[:error]
+
+      res
+    end
+
+    def load_session(session_name)
+      res = @client.session_load(session_name)
+      raise WorkflowError, res[:error] if res[:error]
+
+      res
+    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)
@@ -100,15 +123,31 @@ module Browserctl
       @client = client
     end
 
-    def goto(url)        = unwrap @client.goto(@name, url)
-    def fill(sel, val)   = unwrap @client.fill(@name, sel, val)
-    def click(sel)       = unwrap @client.click(@name, sel)
-    def snapshot(**) = unwrap @client.snapshot(@name, **)
-    def screenshot(**) = unwrap @client.screenshot(@name, **)
-    def watch(sel, timeout: 30)    = unwrap @client.watch(@name, sel, timeout: timeout)
-    def wait_for(sel, timeout: 10) = unwrap @client.wait_for(@name, sel, timeout: timeout)
-    def url              = @client.url(@name)[:url]
-    def evaluate(expr)   = @client.evaluate(@name, expr)[:result]
+    def navigate(url)             = unwrap @client.navigate(@name, url)
+    def fill(sel, val)            = unwrap @client.fill(@name, sel, val)
+    def click(sel)                = unwrap @client.click(@name, sel)
+    def snapshot(**)              = unwrap @client.snapshot(@name, **)
+    def screenshot(**)            = unwrap @client.screenshot(@name, **)
+    def wait(sel, timeout: 30)    = unwrap @client.wait(@name, sel, timeout: timeout)
+    def delete_cookies             = unwrap @client.delete_cookies(@name)
+    def devtools                   = @client.devtools(@name)[:devtools_url]
+    def url                        = @client.url(@name)[:url]
+    def evaluate(expr)             = @client.evaluate(@name, expr)[:result]
+
+    def storage_get(key, store: "local")
+      @client.storage_get(@name, key, store: store)[:value]
+    end
+
+    def storage_set(key, value, store: "local")
+      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
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Patrick
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-25 00:00:00.000000000 Z
+date: 2026-04-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ferrum
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '2.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -141,6 +141,26 @@ files:
 - examples/cloudflare_hitl.rb
 - examples/smoke/params_file.rb
 - examples/smoke/store_fetch.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
@@ -148,21 +168,22 @@ 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/export_cookies.rb
+- lib/browserctl/commands/cookie.rb
+- lib/browserctl/commands/daemon.rb
+- lib/browserctl/commands/dialog.rb
 - lib/browserctl/commands/fill.rb
-- lib/browserctl/commands/import_cookies.rb
 - lib/browserctl/commands/init.rb
-- lib/browserctl/commands/inspect.rb
-- lib/browserctl/commands/open_page.rb
-- lib/browserctl/commands/pause.rb
+- lib/browserctl/commands/page.rb
 - lib/browserctl/commands/record.rb
 - lib/browserctl/commands/resume.rb
 - lib/browserctl/commands/screenshot.rb
+- lib/browserctl/commands/session.rb
 - lib/browserctl/commands/snapshot.rb
-- lib/browserctl/commands/status.rb
-- lib/browserctl/commands/watch.rb
+- lib/browserctl/commands/storage.rb
+- lib/browserctl/commands/workflow.rb
 - lib/browserctl/constants.rb
 - lib/browserctl/detectors.rb
 - lib/browserctl/errors.rb
@@ -176,12 +197,16 @@ files:
 - 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
+- lib/browserctl/server/handlers/session.rb
+- lib/browserctl/server/handlers/storage.rb
 - lib/browserctl/server/idle_watcher.rb
 - lib/browserctl/server/page_session.rb
 - lib/browserctl/server/snapshot_builder.rb
+- lib/browserctl/session.rb
 - lib/browserctl/version.rb
 - lib/browserctl/workflow.rb
 homepage: https://github.com/patrick204nqh/browserctl

data/lib/browserctl/commands/export_cookies.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Browserctl
-  module Commands
-    class ExportCookies
-      def self.run(client, args)
-        page = args.shift or abort "usage: browserctl export-cookies <page> <path>"
-        path = args.shift or abort "usage: browserctl export-cookies <page> <path>"
-        result = client.export_cookies(page, path)
-        if result[:error]
-          warn "Error: #{result[:error]}"
-          exit 1
-        end
-        puts result.to_json
-      end
-    end
-  end
-end

data/lib/browserctl/commands/import_cookies.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-module Browserctl
-  module Commands
-    class ImportCookies
-      def self.run(client, args)
-        page = args.shift or abort "usage: browserctl import-cookies <page> <path>"
-        path = args.shift or abort "usage: browserctl import-cookies <page> <path>"
-        begin
-          result = client.import_cookies(page, path)
-        rescue StandardError => e
-          warn "Error: #{e.message}"
-          exit 1
-        end
-        if result[:error]
-          warn "Error: #{result[:error]}"
-          exit 1
-        end
-        puts result.to_json
-      end
-    end
-  end
-end

data/lib/browserctl/commands/inspect.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module Browserctl
-  module Commands
-    class Inspect
-      def self.run(client, args)
-        name = args.shift or abort "usage: browserctl inspect <page>"
-        res = client.inspect_page(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)
-      end
-    end
-  end
-end

data/lib/browserctl/commands/open_page.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-require "optimist"
-require_relative "cli_output"
-
-module Browserctl
-  module Commands
-    class OpenPage
-      extend CliOutput
-
-      def self.run(client, args)
-        opts = Optimist.options(args) do
-          banner "Usage: browserctl open <page> [--url URL]"
-          opt :url, "URL to navigate to", type: :string, short: "-u"
-        end
-        name = args.shift or abort "usage: browserctl open <page> [--url URL]"
-        print_result(client.open_page(name, url: opts[:url]))
-      end
-    end
-  end
-end

data/lib/browserctl/commands/pause.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "cli_output"
-
-module Browserctl
-  module Commands
-    module Pause
-      extend CliOutput
-
-      def self.run(client, args)
-        name = args.shift or abort "usage: browserctl pause <page>"
-        res = client.pause(name)
-        if res[:error]
-          warn "Error: #{res[:error]}"
-          exit 1
-        end
-        puts "Page '#{name}' paused. Browser is live — interact freely."
-        puts "When done: browserctl resume #{name}"
-      end
-    end
-  end
-end