dommy-rack 0.8.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a1a9aaa4ae2c0fcc61a4054b66fe4e9e9fadb65093acfa912c1b73a5216ac7be
+  data.tar.gz: 3ead606c9fc898c53aeb6e05222f0ddbf2c4c3f08a8ccce6e881867de537019d
+SHA512:
+  metadata.gz: 1f5e7fb4b35c073c069812de208765c5ba7e3aaca832a8071d320a991cc2f215ecf6d27ccec6e87988719ede65550b4d0b8901810380428495427e8fa48b6716
+  data.tar.gz: 21f1916ec0327d598142776993685685d0257e76dfa4ac998556aa116819678e96ead4b1615e31cccab60c3645de34d29a8e46f1e42638528bf1bd89071520a1

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.8.0 — 2026-05-31
+
+Versioned in lockstep with [`dommy`](https://github.com/takahashim/dommy) 0.8.0.
+No functional changes to dommy-rack itself.
+
+## 0.7.0 — 2026-05-30
+
+Initial release.
+
+Versioned in lockstep with the [`dommy`](https://github.com/takahashim/dommy)
+gem. dommy-rack lets a Rack application (including Rails) be visited and
+manipulated as a `Dommy::Document` without launching a real browser, providing a
+small, synchronous, browser-like session API with navigation, cookies,
+redirects, link clicking, and form submission.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Masayoshi Takahashi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,230 @@
+# Dommy::Rack
+
+`dommy-rack` lets a Rack application (including Rails) be visited and manipulated as a [Dommy](https://github.com/takahashim/dommy) `Document`, without launching a real browser.
+It provides a small, synchronous, browser-like session API: navigation, cookies, redirects, link clicking, form submission, JSON requests, and simple matchers.
+
+There is no JavaScript engine and no network: requests are dispatched straight to your Rack app object, and responses are parsed into a Dommy DOM.
+This makes it a fast backend for integration tests and a building block for higher-level drivers such as [capybara-dommy](https://github.com/takahashim/capybara-dommy).
+
+## Installation
+
+```ruby
+# Gemfile
+gem "dommy-rack"
+```
+
+```bash
+bundle install
+```
+
+## Quick start
+
+```ruby
+require "dommy/rack"
+
+session = Dommy::Rack::Session.new(MyRackApp)
+
+session.visit("/")
+session.click_link("New post")
+
+session.fill_in("post[title]", with: "Hello")
+session.click_button("Create")
+
+session.current_path        # => "/posts/1"
+session.at_css(".notice").text_content  # => "Created"
+```
+
+`Session.new` accepts any Rack-callable `app` plus options:
+
+| option | default | meaning |
+| --- | --- | --- |
+| `default_host` | `"http://example.org"` | base for relative URLs |
+| `follow_redirects` | `true` | follow 3xx responses |
+| `max_redirects` | `5` | redirect / meta-refresh limit |
+| `respect_method_override` | `true` | honor Rails `_method` |
+| `method_override_param` | `"_method"` | override param name |
+| `user_agent` | `"DommyRack"` | default `User-Agent` |
+| `accept` | HTML accept string | default `Accept` |
+| `enforce_same_origin` | `true` | block cross-origin requests |
+| `follow_meta_refresh` | `true` | follow `<meta http-equiv="refresh">` (delay 0) |
+
+## Navigation
+
+```ruby
+session.visit("/path")
+session.get("/path", headers: {})
+session.post("/path", params: {a: 1})
+session.put("/path", params: {})
+session.patch("/path", params: {})
+session.delete("/path")
+session.request("REPORT", "/path", params: {})
+
+session.reload
+session.back
+session.forward
+
+session.current_url    # full URL
+session.current_path   # path component
+session.current_host
+```
+
+`fetch` issues a request **without** changing the current page or history, and returns the `Response` directly:
+
+```ruby
+res = session.fetch("/api/ping", redirect: :manual) # :follow | :manual | :error
+res.status
+```
+
+## Inspecting the current page
+
+```ruby
+session.status      # last response status (Integer)
+session.headers     # last response headers (Hash)
+session.body        # raw response body (String)
+session.html        # serialized document HTML
+session.text        # document body text
+
+session.success?       # 2xx
+session.not_found?     # 404
+session.client_error?  # 4xx
+session.server_error?  # 5xx
+
+session.save_page                 # write HTML to a temp file, returns path
+session.save_page("out.html")     # write to a specific path
+```
+
+### DOM queries
+
+```ruby
+session.at_css("h1")          # first match (a Dommy element) or nil
+session.all_css("li")         # all matches
+session.at_xpath("//h1")
+session.all_xpath("//li")
+```
+
+### Redirect chain
+
+```ruby
+session.visit("/a")     # /a -> /b -> /c
+session.redirected?     # => true
+session.redirects       # => [{status: 302, url: ".../a", location: "/b"}, ...]
+```
+
+## Forms
+
+```ruby
+session.fill_in("Email", with: "a@example.com")  # by label, id, name, placeholder, aria-label
+session.choose("Male")                            # radio
+session.check("Subscribe")                        # checkbox
+session.uncheck("Subscribe")
+session.select("Tokyo", from: "City")             # <select>
+session.unselect("Tokyo", from: "City")
+session.attach_file("Avatar", "/path/to/file.png")
+
+session.click_button("Save")        # submits the owning form
+session.submit_form(session.at_css("form"))
+```
+
+Locators are Capybara-style and depend on the element type:
+fields match by `id`, `name`, label text, placeholder, or `aria-label`;
+links match by visible text, `id`, `title`, or exact `href`;
+buttons match by button text, `value`, `id`, `name`, or `alt`.
+
+## JSON
+
+```ruby
+session.post_json("/api/posts", {title: "Hi"})    # also put_json / patch_json / delete_json
+session.status                                     # => 201
+session.json                                       # => {"id" => 7}
+session.json(symbolize_names: true)                # => {id: 7}
+
+# On a Response:
+res = session.fetch("/api/posts")
+res.json?   # content-type is JSON-ish (application/json, text/json, *+json)
+res.json    # parsed body (parses regardless of content-type)
+```
+
+A `String` passed to `post_json` is sent verbatim (already-encoded JSON).
+`Content-Type` and `Accept` default to `application/json` and can be overridden via `headers:`.
+
+## Persistent headers and authentication
+
+```ruby
+session.set_header("X-Api-Key", "secret")  # sent on every request
+session.delete_header("X-Api-Key")
+session.default_headers                     # current persistent headers (copy)
+
+session.basic_auth("alice", "s3cret")       # Authorization: Basic ...
+session.authorization_bearer("token123")    # Authorization: Bearer token123
+```
+
+Per-request `headers:` override persistent defaults (case-insensitively).
+
+## Cookies
+
+```ruby
+session.cookies                       # all cookies
+session.get_cookie("sid")
+session.set_cookie("sid", "42", path: "/")
+session.clear_cookies
+```
+
+Cookies set by the app via `Set-Cookie` are stored and replayed automatically.
+
+## Scoping and matchers
+
+```ruby
+session.within("#sidebar") do |s|
+  s.click_link("Help")
+  s.has_text?("Contact us")   # scoped to #sidebar
+end
+
+session.has_css?(".item", count: 3)
+session.has_no_css?(".error")
+session.has_text?("Welcome")
+session.has_no_text?("Error")
+session.has_link?("Home")
+session.has_button?("Save")
+session.has_field?("Email")
+```
+
+### iframes
+
+```ruby
+session.within_frame("preview") do |s|   # by id, name, CSS, or the sole frame
+  s.has_text?("inside the iframe")
+end
+```
+
+`within_frame` fetches the iframe's `src` as a sub-document and scopes finds and matchers to it for the block.
+
+## Instrumentation
+
+```ruby
+session.on_request  { |env|      Rails.logger.info("-> #{env["PATH_INFO"]}") }
+session.on_response { |response| Rails.logger.info("<- #{response.status}") }
+```
+
+## Errors
+
+All errors inherit from `Dommy::Rack::Error`:
+`ElementNotFoundError`, `AmbiguousElementError`, `ElementNotClickableError`,
+`UnsupportedURLError`, `CrossOriginError`, `TooManyRedirectsError`,
+`UnsupportedContentTypeError`, `InvalidFormError`, `FileNotFoundError`.
+
+## Development
+
+```bash
+bin/setup        # install dependencies
+rake test        # run the test suite
+bin/console      # interactive prompt
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome at
+https://github.com/takahashim/dommy-rack.
+
+## License
+
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/lib/dommy/rack/cookie_jar.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "uri"
+require "time"
+
+module Dommy
+  module Rack
+    # A simplified, same-origin cookie store. Parses Set-Cookie response
+    # headers, generates the Cookie request header, and applies domain, path,
+    # expiry, and secure matching. No public-suffix handling.
+    class CookieJar
+      CookieEntry = Struct.new(
+        :name, :value, :domain, :path, :expires, :secure, :http_only, :host_only,
+        keyword_init: true
+      )
+
+      def initialize
+        @entries = []
+      end
+
+      # Parse a single Set-Cookie header value and store the result.
+      def store_from_header(set_cookie_string, request_url)
+        uri = URI.parse(request_url)
+        entry = parse_set_cookie(set_cookie_string, uri)
+        return unless entry
+
+        if expired?(entry)
+          remove(entry.name, entry.domain, entry.path)
+        else
+          store_entry(entry)
+        end
+      end
+
+      # Manually store a cookie. domain defaults to host-only on request_host.
+      def set!(name, value, domain: nil, path: "/", expires: nil, secure: false, http_only: false)
+        entry = CookieEntry.new(
+          name: name.to_s,
+          value: value.to_s,
+          domain: (domain || "").sub(/\A\./, "").downcase,
+          path: path || "/",
+          expires: expires,
+          secure: secure,
+          http_only: http_only,
+          host_only: domain.nil?
+        )
+        store_entry(entry)
+      end
+
+      # First non-expired cookie value matching the name.
+      def get(name)
+        @entries.find { |e| e.name == name.to_s && !expired?(e) }&.value
+      end
+
+      def clear
+        @entries = []
+      end
+
+      def all
+        @entries.reject { |e| expired?(e) }
+      end
+
+      # Build the Cookie request header value for the given URL, or "".
+      def cookies_for(request_url)
+        uri = URI.parse(request_url)
+        secure_request = uri.scheme == "https"
+        host = uri.host.to_s.downcase
+        path = uri.path.to_s.empty? ? "/" : uri.path
+
+        matches = @entries.reject { |e| expired?(e) }.select do |e|
+          domain_match?(e, host) &&
+            path_match?(e.path, path) &&
+            (!e.secure || secure_request)
+        end
+
+        # More specific (longer) paths first, per RFC 6265.
+        matches.sort_by! { |e| -e.path.length }
+        matches.map { |e| "#{e.name}=#{e.value}" }.join("; ")
+      end
+
+      private
+
+      def store_entry(entry)
+        remove(entry.name, entry.domain, entry.path)
+        @entries << entry
+      end
+
+      def remove(name, domain, path)
+        @entries.reject! { |e| e.name == name && e.domain == domain && e.path == path }
+      end
+
+      def parse_set_cookie(string, request_uri)
+        segments = string.split(";").map(&:strip)
+        name_value = segments.shift.to_s
+        return nil unless name_value.include?("=")
+
+        name, value = name_value.split("=", 2)
+        name = name.to_s.strip
+        return nil if name.empty?
+
+        attrs = parse_attributes(segments)
+        request_host = request_uri.host.to_s.downcase
+
+        domain = attrs["domain"]
+        host_only = domain.nil? || domain.empty?
+        domain = host_only ? request_host : domain.sub(/\A\./, "").downcase
+
+        CookieEntry.new(
+          name: name,
+          value: value.to_s.strip,
+          domain: domain,
+          path: attrs["path"] || default_path(request_uri),
+          expires: resolve_expiry(attrs),
+          secure: attrs.key?("secure"),
+          http_only: attrs.key?("httponly"),
+          host_only: host_only
+        )
+      end
+
+      def parse_attributes(segments)
+        segments.each_with_object({}) do |segment, acc|
+          key, val = segment.split("=", 2)
+          acc[key.to_s.strip.downcase] = val&.strip
+        end
+      end
+
+      # Max-Age takes precedence over Expires.
+      def resolve_expiry(attrs)
+        if attrs["max-age"]
+          seconds = attrs["max-age"].to_i
+          Time.now + seconds
+        elsif attrs["expires"]
+          Time.parse(attrs["expires"]) rescue nil
+        end
+      end
+
+      # RFC 6265 default-path: directory portion of the request path.
+      def default_path(uri)
+        path = uri.path.to_s
+        return "/" if path.empty? || !path.start_with?("/")
+
+        idx = path.rindex("/")
+        idx.nil? || idx.zero? ? "/" : path[0...idx]
+      end
+
+      def expired?(entry)
+        entry.expires && entry.expires <= Time.now
+      end
+
+      def domain_match?(entry, host)
+        if entry.host_only
+          host == entry.domain
+        else
+          host == entry.domain || host.end_with?(".#{entry.domain}")
+        end
+      end
+
+      # RFC 6265 path-match.
+      def path_match?(cookie_path, request_path)
+        return true if cookie_path == request_path
+        return false unless request_path.start_with?(cookie_path)
+
+        cookie_path.end_with?("/") || request_path[cookie_path.length] == "/"
+      end
+    end
+  end
+end

data/lib/dommy/rack/errors.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Rack
+    class Error < StandardError; end
+
+    # Raised when a locator matches no element.
+    class ElementNotFoundError < Error; end
+
+    # Raised when an element cannot be clicked (e.g. a link with no href).
+    class ElementNotClickableError < Error; end
+
+    # Raised when a locator matches more than one element.
+    class AmbiguousElementError < Error; end
+
+    # Raised for hrefs that dommy-rack cannot navigate to (javascript:, mailto:, ...).
+    class UnsupportedURLError < Error; end
+
+    # Raised when a request would cross origins, which is not allowed.
+    class CrossOriginError < Error; end
+
+    # Raised when a redirect chain exceeds max_redirects.
+    class TooManyRedirectsError < Error; end
+
+    # Raised when a response content type cannot be handled as requested.
+    class UnsupportedContentTypeError < Error; end
+
+    # Raised when a form is malformed or cannot be submitted.
+    class InvalidFormError < Error; end
+
+    # Raised when a file to be uploaded does not exist.
+    class FileNotFoundError < Error; end
+  end
+end

data/lib/dommy/rack/field_interactor.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Rack
+    # Drives form fields in the current document: fills text inputs, toggles
+    # radios / checkboxes, selects options, attaches files. Pure DOM mutation —
+    # it locates fields via a Locator and mutates the live Dommy elements, but
+    # issues no requests (Session turns a subsequent submit into navigation).
+    class FieldInteractor
+      def initialize(finder, document)
+        @finder = finder
+        @document = document
+      end
+
+      def fill_in(locator, with:)
+        field = @finder.find_field(locator)
+        field.value = with.to_s
+        field
+      end
+
+      def choose(locator)
+        radio = @finder.find_field(locator)
+        clear_radio_group(radio)
+        radio.checked = true
+        radio
+      end
+
+      def check(locator)
+        box = @finder.find_field(locator)
+        box.checked = true
+        box
+      end
+
+      def uncheck(locator)
+        box = @finder.find_field(locator)
+        box.checked = false
+        box
+      end
+
+      def attach_file(locator, path)
+        input = @finder.find_field(locator)
+        raise FileNotFoundError, "no such file: #{path}" unless ::File.exist?(path)
+
+        file = Dommy::File.new(
+          [::File.binread(path)], ::File.basename(path), "type" => FileUpload.mime_type_for(path)
+        )
+        input.__driver_set_files__([file])
+        input
+      end
+
+      def select(value, from:)
+        select_el = @finder.find_field(from)
+        option = @finder.find_option(select_el, value)
+        raise ElementNotFoundError, "no option #{value.inspect} in #{from.inspect}" unless option
+
+        select_el.options.each { |o| o.remove_attribute("selected") } unless select_el.multiple
+        option.set_attribute("selected", "")
+        select_el
+      end
+
+      def unselect(value, from:)
+        select_el = @finder.find_field(from)
+        option = @finder.find_option(select_el, value)
+        option&.remove_attribute("selected")
+        select_el
+      end
+
+      private
+
+      def clear_radio_group(radio)
+        name = radio.get_attribute("name")
+        return unless name
+
+        scope = radio.closest("form") || @document
+        scope.query_selector_all("input[type='radio']").each do |r|
+          r.checked = false if r.get_attribute("name") == name
+        end
+      end
+    end
+  end
+end

data/lib/dommy/rack/file_upload.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Dommy
+  module Rack
+    # Encodes collected form params (ordered [name, value] pairs) as a
+    # multipart/form-data body. File/Blob values become file parts; other
+    # values become text parts. Owns the multipart serialization so the HTTP
+    # layer (not Dommy::FormData) is responsible for it.
+    module FileUpload
+      MIME_TYPES = {
+        ".txt" => "text/plain",
+        ".html" => "text/html",
+        ".htm" => "text/html",
+        ".json" => "application/json",
+        ".csv" => "text/csv",
+        ".xml" => "application/xml",
+        ".png" => "image/png",
+        ".jpg" => "image/jpeg",
+        ".jpeg" => "image/jpeg",
+        ".gif" => "image/gif",
+        ".pdf" => "application/pdf"
+      }.freeze
+
+      module_function
+
+      # Guess a MIME type from a file path's extension.
+      def mime_type_for(path)
+        MIME_TYPES.fetch(::File.extname(path).downcase, "application/octet-stream")
+      end
+
+      # True when any pair value is a File/Blob.
+      def multipart?(pairs)
+        return false unless pairs
+
+        pairs.any? { |(_name, value)| value.respond_to?(:__dommy_bytes__) }
+      end
+
+      # Returns [body (ASCII-8BIT String), content_type with boundary].
+      def encode(pairs, boundary = nil)
+        boundary ||= "----DommyRackBoundary#{SecureRandom.hex(16)}"
+        body = +"".b
+        pairs.each { |name, value| body << part(boundary, name, value) }
+        body << "--#{boundary}--\r\n"
+        [body, "multipart/form-data; boundary=#{boundary}"]
+      end
+
+      def part(boundary, name, value)
+        head = +"--#{boundary}\r\n"
+        if value.respond_to?(:__dommy_bytes__) # File / Blob
+          filename = value.respond_to?(:name) ? value.name.to_s : ""
+          content_type = file_content_type(value)
+          head << %(Content-Disposition: form-data; name="#{escape(name)}"; filename="#{escape(filename)}"\r\n)
+          head << "Content-Type: #{content_type}\r\n\r\n"
+          head.b << value.__dommy_bytes__ << "\r\n".b
+        else
+          head << %(Content-Disposition: form-data; name="#{escape(name)}"\r\n\r\n)
+          head.b << value.to_s.dup.force_encoding(Encoding::ASCII_8BIT) << "\r\n".b
+        end
+      end
+
+      def file_content_type(value)
+        type = value.respond_to?(:type) ? value.type.to_s : ""
+        type.empty? ? "application/octet-stream" : type
+      end
+
+      def escape(str)
+        str.to_s.gsub('"', "%22").gsub(/[\r\n]/, "")
+      end
+    end
+  end
+end