browserctl 0.5.0 → 0.6.0

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.6.0"
 end

data/lib/browserctl/workflow.rb

@@ -47,19 +47,37 @@ 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 invoke(workflow_name, **override_params)
       name = workflow_name.to_s
       guard_circular!(name)
@@ -100,15 +118,24 @@ 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
 
     private
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.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,12 @@ files:
 - 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/the_internet/add_remove_elements.rb
 - examples/the_internet/checkboxes.rb
 - examples/the_internet/dropdown.rb
@@ -150,19 +156,18 @@ files:
 - lib/browserctl/client.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/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
@@ -179,9 +184,12 @@ files:
 - 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

data/lib/browserctl/commands/status.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-
-module Browserctl
-  module Commands
-    module Status
-      def self.run(client)
-        ping = client.ping
-        pages = client.list_pages[:pages] || []
-        page_info = pages.map do |name|
-          url_res = client.url(name)
-          { name: name, url: url_res[:url] || url_res[:error] }
-        end
-
-        puts JSON.pretty_generate(
-          daemon: "online",
-          pid: ping[:pid],
-          protocol_version: ping[:protocol_version],
-          pages: page_info
-        )
-      rescue RuntimeError => e
-        raise unless e.message.include?("browserd is not running")
-
-        puts JSON.pretty_generate(daemon: "offline", error: e.message)
-        exit 1
-      end
-    end
-  end
-end

data/lib/browserctl/commands/watch.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-require "optimist"
-require_relative "cli_output"
-
-module Browserctl
-  module Commands
-    class Watch
-      extend CliOutput
-
-      def self.run(client, args)
-        opts = Optimist.options(args) do
-          banner "Usage: browserctl watch <page> <selector> [--timeout N]"
-          opt :timeout, "Seconds to wait (default: 30)", default: 30.0, short: "-t"
-        end
-        name     = args.shift
-        selector = args.shift
-        abort "usage: browserctl watch <page> <selector> [--timeout N]" unless name && selector
-        unless opts[:timeout].positive?
-          warn "Error: --timeout must be a positive number"
-          exit 1
-        end
-        print_result(client.watch(name, selector, timeout: opts[:timeout]))
-      end
-    end
-  end
-end