unmagic-browser 0.1.0

data/lib/unmagic/browser/session.rb

@@ -0,0 +1,588 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Unmagic
+  class Browser
+    # A live browser page you drive step by step.
+    #
+    # The verbs read like Capybara's, and they auto-wait: `click_button "Sign
+    # in"` keeps looking until a button by that name is on the page and
+    # actionable, so an explicit {#wait_for} is rare. Questions — `has_text?`
+    # and friends — answer immediately instead, because "no" is an answer a
+    # caller usually wants now rather than in ten seconds.
+    #
+    # A session is a plain object. Hold it and it stays live between calls,
+    # which is what lets an agent open a page in one turn and act on it in the
+    # next — and what makes {#close} your job.
+    #
+    # @example
+    #   browser.open("https://store.example.com") do |session|
+    #     session.fill_in "Search", with: "espresso"
+    #     session.click_button "Go"
+    #     session.all(".product").map { |element| element.text }
+    #   end
+    class Session
+      # Symbols that read better than Chrome's own key names.
+      KEYS = {
+        enter: "Enter",
+        return: "Enter",
+        tab: "Tab",
+        escape: "Escape",
+        esc: "Escape",
+        space: "Space",
+        backspace: "Backspace",
+        delete: "Delete",
+        up: "ArrowUp",
+        down: "ArrowDown",
+        left: "ArrowLeft",
+        right: "ArrowRight",
+        home: "Home",
+        end: "End",
+        page_up: "PageUp",
+        page_down: "PageDown",
+      }.freeze
+
+      # How often a waiting locator re-checks the page, in milliseconds. Slower
+      # than Chrome's animation frame on purpose: the matcher walks the DOM, and
+      # running that sixty times a second buys nothing a caller would notice.
+      POLL_INTERVAL_MS = 100
+
+      # `innerText` is what a person would read — it respects `display: none`
+      # and collapses the way the page renders — where `textContent` would hand
+      # back hidden markup as if it were on screen.
+      PAGE_TEXT_SCRIPT = <<~JAVASCRIPT
+        () => {
+          const body = document.body;
+          if (!body) return "";
+          return body.innerText === undefined ? body.textContent : body.innerText;
+        }
+      JAVASCRIPT
+
+      class << self
+        # Translate a key symbol into the name Chrome knows.
+        #
+        # @param key [Symbol, String] e.g. `:enter` or `"ArrowDown"`
+        # @return [String]
+        def key_name(key)
+          KEYS[key.to_s.downcase.to_sym] || key.to_s
+        end
+      end
+
+      # @return [Unmagic::Browser] the browser this session belongs to
+      attr_reader :browser
+
+      # @return [Emulation] what's currently being emulated
+      attr_reader :emulation
+
+      # @param browser [Unmagic::Browser] the browser that opened this session
+      # @param connection [Driver::Connection] the browser this session owns and will close
+      # @param page [Puppeteer::Page] the live page
+      # @param emulation [Emulation] what to emulate from the start
+      # @param timeout [Numeric] seconds a locator waits before giving up
+      # @param navigation_timeout [Numeric] seconds a navigation is given
+      def initialize(browser:, connection:, page:, emulation: nil, timeout: nil, navigation_timeout: nil)
+        @browser = browser
+        @connection = connection
+        @page = page
+        @emulation = Emulation.build(emulation)
+        @timeout = timeout || Browser.configuration.timeout
+        @navigation_timeout = navigation_timeout || Browser.configuration.navigation_timeout
+        @monitor = Monitor.new
+        @scopes = []
+        @closed = false
+
+        guarded("setting up emulation") { @emulation.apply(@page) }
+      end
+
+      # The live Puppeteer page, for everything this API doesn't wrap — network
+      # interception, tracing, the rest of the surface. Wrap multi-step native
+      # work in {#lock} when it has to be atomic against other callers.
+      #
+      # @return [Puppeteer::Page]
+      def driver
+        @page
+      end
+
+      # ---------------------------------------------------------------- navigate
+
+      # Go to a URL and wait for it to settle.
+      #
+      # @param url [String]
+      # @return [self]
+      def visit(url)
+        navigating("visiting #{url}") { @page.goto(url, wait_until: Driver::Base::WAIT_UNTIL, timeout: navigation_ms) }
+      end
+
+      # @return [self]
+      def reload
+        navigating("reloading") { @page.reload(wait_until: Driver::Base::WAIT_UNTIL, timeout: navigation_ms) }
+      end
+
+      # @return [self]
+      def go_back
+        navigating("going back") { @page.go_back(wait_until: Driver::Base::WAIT_UNTIL, timeout: navigation_ms) }
+      end
+
+      # @return [self]
+      def go_forward
+        navigating("going forward") { @page.go_forward(wait_until: Driver::Base::WAIT_UNTIL, timeout: navigation_ms) }
+      end
+
+      # @return [String] the URL currently shown
+      def current_url
+        guarded("reading the URL") { @page.url }
+      end
+
+      # @return [String] the page's title
+      def title
+        guarded("reading the title") { @page.title }
+      end
+
+      # ------------------------------------------------------------------- act
+
+      # Type into a field, replacing whatever's in it.
+      #
+      # @param query [String, nil] the field's label, placeholder, name or id
+      # @param with [String] the text to type
+      # @param options [Hash] see {Locator.build}
+      # @return [self]
+      # @raise [Error::NotFound] when no such field turns up in time
+      def fill_in(query = nil, with:, **options)
+        find(query, purpose: :field, **options).fill_in(with)
+        self
+      end
+
+      # @param query [String, nil] the button's text, value or name
+      # @param options [Hash] see {Locator.build}
+      # @return [self]
+      # @raise [Error::NotFound] when no such button turns up in time
+      def click_button(query = nil, **options)
+        find(query, purpose: :button, **options).click
+        self
+      end
+
+      # @param query [String, nil] the link's text
+      # @param options [Hash] see {Locator.build}
+      # @return [self]
+      # @raise [Error::NotFound] when no such link turns up in time
+      def click_link(query = nil, **options)
+        find(query, purpose: :link, **options).click
+        self
+      end
+
+      # Click whatever matches — a button, a link, a div, anything.
+      #
+      # @param query [String, nil] see {Locator.build}
+      # @param options [Hash] see {Locator.build}
+      # @return [self]
+      # @raise [Error::NotFound] when nothing matches in time
+      def click(query = nil, **options)
+        find(query, **options).click
+        self
+      end
+
+      # Pick an option in a select, by the label a reader sees.
+      #
+      # @param option [String] the option's visible label, or its value
+      # @param from [String, nil] the select's label or name
+      # @param options [Hash] see {Locator.build}
+      # @return [self]
+      # @raise [Error::NotFound] when the select or the option isn't there
+      def select(option, from: nil, **options)
+        # With nothing naming the select, there's only one sensible reading:
+        # the page has one, and this is it.
+        options = { css: "select" } if from.nil? && options.empty?
+        find(from, purpose: :select, **options).select_option(option)
+        self
+      end
+
+      # @param query [String, nil] the checkbox's label or name
+      # @param options [Hash] see {Locator.build}
+      # @return [self]
+      def check(query = nil, **options)
+        find(query, purpose: :checkbox, **options).check
+        self
+      end
+
+      # @param query [String, nil] the checkbox's label or name
+      # @param options [Hash] see {Locator.build}
+      # @return [self]
+      def uncheck(query = nil, **options)
+        find(query, purpose: :checkbox, **options).uncheck
+        self
+      end
+
+      # @param query [String, nil] the radio button's label or name
+      # @param options [Hash] see {Locator.build}
+      # @return [self]
+      def choose(query = nil, **options)
+        find(query, purpose: :radio, **options).click
+        self
+      end
+
+      # @param query [String, nil] the file field's label or name
+      # @param paths [Array<String>] the files to attach
+      # @param options [Hash] see {Locator.build}
+      # @return [self]
+      def attach_file(query = nil, *paths, **options)
+        find(query, purpose: :file_field, **options).attach(*paths)
+        self
+      end
+
+      # Press a key. With no locator it goes to whatever has focus.
+      #
+      # @param key [Symbol, String] e.g. `:enter`, `"ArrowDown"`
+      # @param on [String, Element, nil] press it with this element focused instead
+      # @param options [Hash] see {Locator.build}
+      # @return [self]
+      def press(key, on: nil, **options)
+        if on
+          element(on, **options).press(key)
+        else
+          guarded("pressing #{key}") { @page.keyboard.press(self.class.key_name(key)) }
+        end
+        self
+      end
+
+      # @param query [String, nil] see {Locator.build}
+      # @param options [Hash] see {Locator.build}
+      # @return [self]
+      def hover(query = nil, **options)
+        find(query, **options).hover
+        self
+      end
+
+      # ------------------------------------------------------------------ read
+
+      # @return [String] the visible text of the page, or of the current scope
+      def text
+        raw = if scope
+          scope.evaluate("(root) => (root.innerText === undefined ? root.textContent : root.innerText)")
+        else
+          guarded("reading the page") { @page.evaluate(PAGE_TEXT_SCRIPT) }
+        end
+        raw.to_s.gsub(/[ \t]+/, " ").strip
+      end
+
+      # @return [String] the page's HTML, as it stands after JavaScript has run
+      def html
+        return scope.html if scope
+
+        guarded("reading the page") { @page.content }
+      end
+
+      # @return [String] the page as Markdown
+      def markdown
+        Markdown.from_html(html)
+      end
+
+      # @param query [String, nil] the field's label, placeholder, name or id
+      # @param options [Hash] see {Locator.build}
+      # @return [String, nil] what's currently in the field
+      def value(query = nil, **options)
+        find(query, purpose: :field, **options).value
+      end
+
+      # @param full_page [Boolean] capture the whole scrollable page
+      # @param selector [String, Element, nil] capture just this element
+      # @return [String] PNG bytes
+      def screenshot(full_page: false, selector: nil)
+        target = selector || scope
+        return element(target).screenshot if target
+
+        guarded("taking a screenshot") { @page.screenshot(type: "png", full_page: full_page) }
+      end
+
+      # @return [String] PDF bytes
+      def pdf
+        guarded("printing to PDF") { @page.pdf }
+      end
+
+      # Run JavaScript in the page.
+      #
+      # @param script [String] an expression, or a function like `"() => document.title"`
+      # @param args [Array] arguments passed to the function form
+      # @return [Object] whatever it returns, as a Ruby value
+      def evaluate(script, *args)
+        guarded("evaluating JavaScript") { @page.evaluate(script, *args) }
+      end
+
+      # -------------------------------------------------------------- wait & ask
+
+      # Block until something shows up.
+      #
+      # @param text [String, nil] wait for this text to appear
+      # @param selector [String, nil] wait for an element matching this locator
+      # @param timeout [Numeric, nil] seconds to wait, defaulting to the session's
+      # @param options [Hash] see {Locator.build}
+      # @return [self]
+      # @raise [Error::TimedOut] when it never shows up
+      def wait_for(text: nil, selector: nil, timeout: nil, **options)
+        raise ArgumentError, "wait_for needs text: or selector:" if text.nil? && selector.nil?
+
+        wait_for_text(text, timeout) if text
+        find(selector, wait: timeout || @timeout, **options) if selector
+        self
+      end
+
+      # @param string [String] the text to look for
+      # @return [Boolean] whether it's on the page right now
+      def has_text?(string)
+        text.downcase.include?(string.to_s.downcase.gsub(/\s+/, " ").strip)
+      end
+
+      # @param query [String, nil] see {Locator.build}
+      # @param options [Hash] see {Locator.build}
+      # @return [Boolean] whether such a button is on the page right now
+      def has_button?(query = nil, **options)
+        exists?(query, purpose: :button, **options)
+      end
+
+      # @param query [String, nil] see {Locator.build}
+      # @param options [Hash] see {Locator.build}
+      # @return [Boolean] whether such a link is on the page right now
+      def has_link?(query = nil, **options)
+        exists?(query, purpose: :link, **options)
+      end
+
+      # @param query [String, nil] see {Locator.build}
+      # @param options [Hash] see {Locator.build}
+      # @return [Boolean] whether such a field is on the page right now
+      def has_field?(query = nil, **options)
+        exists?(query, purpose: :field, **options)
+      end
+
+      # @param css [String] a CSS selector
+      # @return [Boolean] whether anything matches it right now
+      def has_selector?(css)
+        exists?(css: css)
+      end
+
+      # @param query [String, nil] see {Locator.build}
+      # @param options [Hash] see {Locator.build}
+      # @return [Boolean] whether anything matches right now
+      def has_element?(query = nil, **options)
+        exists?(query, **options)
+      end
+
+      # ----------------------------------------------------------------- scope
+
+      # Find one element, waiting for it to turn up.
+      #
+      # @param query [String, nil] see {Locator.build}
+      # @param scope [Element, nil] search inside this element instead of the page
+      # @param wait [Numeric, nil] seconds to keep looking, defaulting to the session's
+      # @param purpose [Symbol] see {Locator::PURPOSES}
+      # @param options [Hash] see {Locator.build}
+      # @return [Element]
+      # @raise [Error::NotFound] when nothing matches in time
+      def find(query = nil, scope: nil, wait: nil, purpose: :any, **options)
+        locator = Locator.build(query, purpose: purpose, **options)
+        found = resolve(locator, scope: scope || self.scope, wait: wait || @timeout)
+        raise Error::NotFound, "Couldn't find a #{locator} on #{current_url}." unless found
+
+        found
+      end
+
+      # Find every matching element, right now — no waiting, because "none" is a
+      # legitimate answer.
+      #
+      # @param query [String, nil] see {Locator.build}
+      # @param scope [Element, nil] search inside this element instead of the page
+      # @param purpose [Symbol] see {Locator::PURPOSES}
+      # @param options [Hash] see {Locator.build}
+      # @return [Array<Element>]
+      def all(query = nil, scope: nil, purpose: :any, **options)
+        locator = Locator.build(query, purpose: purpose, **options)
+        resolve_all(locator, scope: scope || self.scope)
+      end
+
+      # Narrow every locator inside the block to one part of the page.
+      #
+      # @param query [String, Element, nil] see {Locator.build}
+      # @param options [Hash] see {Locator.build}
+      # @yield with the scope in force; the session is passed for convenience
+      # @yieldparam session [Session]
+      # @return [Object] whatever the block returns
+      def within(query = nil, **options)
+        inner = element(query, **options)
+        @scopes.push(inner)
+        begin
+          yield(self)
+        ensure
+          @scopes.pop
+        end
+      end
+
+      # @return [Element, nil] the element locators are currently scoped to
+      def scope
+        @scopes.last
+      end
+
+      # ------------------------------------------------------------- lifecycle
+
+      # Change what's emulated from here on, or — with a block — just for the
+      # block, reverting afterwards.
+      #
+      # @param config [Emulation, Hash, nil] a whole configuration
+      # @param knobs [Hash] individual settings, layered over what's already emulated
+      # @yield with the change in force
+      # @return [Emulation, Object] the emulation now in force, or the block's value
+      def emulate(config = nil, **knobs)
+        previous = @emulation
+        apply_emulation(previous.merge(config || knobs))
+        return @emulation unless block_given?
+
+        begin
+          yield
+        ensure
+          apply_emulation(previous)
+        end
+      end
+
+      # Hold the session for a whole sequence, so another caller can't slip a
+      # keystroke between two of your steps. Individual operations are already
+      # serialised; this is for when a *sequence* has to be atomic.
+      #
+      # @yield the sequence to run uninterrupted
+      # @return [Object] whatever the block returns
+      def lock(&block)
+        @monitor.synchronize(&block)
+      end
+      alias_method :synchronize, :lock
+
+      # Close the page and give the browser back. On Cloudflare that releases
+      # one of your concurrent slots, so a kept session that's finished with
+      # should always be closed.
+      #
+      # @return [void]
+      def close
+        @monitor.synchronize do
+          return if @closed
+
+          @closed = true
+          begin
+            @page.close
+          rescue StandardError
+            nil # The page may have gone with its browser; the connection close is what matters.
+          end
+          @connection.close
+        end
+      end
+
+      # @return [Boolean] whether this session has been closed
+      def closed?
+        @closed
+      end
+
+      # @return [String] the session and where it is, or that it's closed
+      def inspect
+        state = @closed ? "closed" : current_url
+        "#<#{self.class.name} #{state}>"
+      end
+
+      private
+
+      def navigation_ms
+        (@navigation_timeout * 1000).to_i
+      end
+
+      # Coerce whatever names an element — an Element, a locator string, keyword
+      # options — into an Element.
+      def element(query, **options)
+        query.is_a?(Element) ? query : find(query, **options)
+      end
+
+      def resolve(locator, scope:, wait:)
+        handle = guarded("looking for a #{locator}") do
+          if wait.to_f.positive?
+            wait_for_handle(locator, scope, wait)
+          else
+            @page.evaluate_handle(Locator::SCRIPT, locator.to_spec, scope&.handle)
+          end
+        end
+        found = handle&.as_element
+        handle.dispose if handle && found.nil?
+        found && Element.new(self, found)
+      end
+
+      def wait_for_handle(locator, scope, wait)
+        @page.wait_for_function(
+          Locator::SCRIPT,
+          args: [locator.to_spec, scope&.handle],
+          polling: POLL_INTERVAL_MS,
+          timeout: (wait * 1000).to_i,
+        )
+      rescue Puppeteer::TimeoutError
+        nil # Nothing matched in time. The caller decides whether that's an error.
+      end
+
+      def resolve_all(locator, scope:)
+        guarded("looking for every #{locator}") do
+          handle = @page.evaluate_handle(Locator::SCRIPT, locator.to_spec(all: true), scope&.handle)
+          begin
+            handle.properties
+              .sort_by { |index, _| index.to_i }
+              .filter_map { |_, item| item.as_element }
+              .map { |found| Element.new(self, found) }
+          ensure
+            handle.dispose
+          end
+        end
+      end
+
+      def exists?(query = nil, purpose: :any, **options)
+        find(query, purpose: purpose, wait: 0, **options)
+        true
+      rescue Error::NotFound
+        false
+      end
+
+      WAIT_FOR_TEXT_SCRIPT = <<~JAVASCRIPT
+        (needle, root) => {
+          const node = root || document.body;
+          if (!node) return false;
+          const text = (node.innerText === undefined ? node.textContent : node.innerText) || "";
+          return text.replace(/\\s+/g, " ").toLowerCase().indexOf(needle) !== -1;
+        }
+      JAVASCRIPT
+      private_constant :WAIT_FOR_TEXT_SCRIPT
+
+      def wait_for_text(string, timeout)
+        seconds = timeout || @timeout
+        guarded("waiting for #{string.inspect}") do
+          @page.wait_for_function(
+            WAIT_FOR_TEXT_SCRIPT,
+            args: [string.to_s.gsub(/\s+/, " ").strip.downcase, scope&.handle],
+            polling: POLL_INTERVAL_MS,
+            timeout: (seconds * 1000).to_i,
+          )
+        rescue Puppeteer::TimeoutError
+          raise Error::TimedOut, "Waited #{seconds}s for #{string.inspect} to appear on #{@page.url}."
+        end
+      end
+
+      def apply_emulation(wanted)
+        guarded("emulating #{wanted.to_h.compact.keys.join(", ")}") do
+          wanted.apply(@page)
+          @emulation = wanted
+        end
+      end
+
+      def navigating(doing)
+        guarded(doing) { yield }
+        self
+      end
+
+      # Everything that touches the page goes through here: it holds the session
+      # lock so two callers can't interleave, refuses to drive a closed session,
+      # and turns whatever puppeteer-ruby throws into one of our typed errors.
+      def guarded(doing)
+        raise Error::SessionClosed, "This session is closed." if @closed
+
+        @monitor.synchronize { Failures.wrap(doing) { yield } }
+      end
+    end
+  end
+end

data/lib/unmagic/browser/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Browser
+    # The gem's version.
+    VERSION = "0.1.0"
+  end
+end