axe-cuprite 0.1.0

data/lib/axe/cuprite/results.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module AxeCuprite
+  # Wraps the (slimmed) payload returned by axe.run. We deliberately only carry
+  # `violations` and `incomplete` across the CDP boundary plus a little metadata
+  # — the full results object (with `passes`/`inapplicable`) can be huge.
+  class Results
+    attr_reader :raw
+
+    def initialize(raw)
+      @raw = raw || {}
+    end
+
+    def violations
+      @violations ||= Array(@raw["violations"]).map { |v| Violation.new(v) }
+    end
+
+    # Nodes axe could not decide on (needs review). Surfaced but never fails.
+    def incomplete
+      @incomplete ||= Array(@raw["incomplete"]).map { |v| Violation.new(v) }
+    end
+
+    def passes?
+      violations.empty?
+    end
+    alias clean? passes?
+
+    def url
+      @raw["url"]
+    end
+
+    def timestamp
+      @raw["timestamp"]
+    end
+
+    def test_engine
+      @raw["testEngine"]
+    end
+
+    def to_h
+      @raw
+    end
+  end
+
+  # A single axe rule violation, with one or more offending nodes.
+  class Violation
+    attr_reader :raw
+
+    def initialize(raw)
+      @raw = raw || {}
+    end
+
+    def id
+      @raw["id"]
+    end
+
+    def impact
+      @raw["impact"]
+    end
+
+    def description
+      @raw["description"]
+    end
+
+    def help
+      @raw["help"]
+    end
+
+    def help_url
+      @raw["helpUrl"]
+    end
+
+    def tags
+      Array(@raw["tags"])
+    end
+
+    def nodes
+      @nodes ||= Array(@raw["nodes"]).map { |n| Node.new(n) }
+    end
+
+    def color_contrast?
+      id == "color-contrast"
+    end
+  end
+
+  # A single offending DOM node within a violation.
+  class Node
+    attr_reader :raw
+
+    def initialize(raw)
+      @raw = raw || {}
+    end
+
+    # axe gives `target` as an array of CSS selectors (one per frame depth).
+    def target
+      Array(@raw["target"])
+    end
+
+    def selector
+      target.join(" ")
+    end
+
+    # The offending element's outer HTML (already truncated by axe).
+    def html
+      @raw["html"]
+    end
+
+    def failure_summary
+      @raw["failureSummary"]
+    end
+
+    # The check results that caused/contributed to the failure.
+    def any
+      Array(@raw["any"])
+    end
+
+    def all
+      Array(@raw["all"])
+    end
+
+    def none
+      Array(@raw["none"])
+    end
+
+    # For color-contrast violations axe stores rich data under any[].data.
+    # Returns a ContrastData (or nil if this node has no contrast data).
+    def contrast_data
+      check = any.find { |c| c.is_a?(Hash) && c["data"].is_a?(Hash) && c["data"].key?("contrastRatio") }
+      return nil unless check
+
+      ContrastData.new(check["data"])
+    end
+  end
+
+  # Typed view over a color-contrast check's `data` hash.
+  class ContrastData
+    attr_reader :raw
+
+    def initialize(raw)
+      @raw = raw || {}
+    end
+
+    def fg_color
+      @raw["fgColor"]
+    end
+
+    def bg_color
+      @raw["bgColor"]
+    end
+
+    def contrast_ratio
+      @raw["contrastRatio"]
+    end
+
+    def expected_contrast_ratio
+      @raw["expectedContrastRatio"]
+    end
+
+    def font_size
+      @raw["fontSize"]
+    end
+
+    def font_weight
+      @raw["fontWeight"]
+    end
+  end
+end

data/lib/axe/cuprite/rspec/matchers.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "axe/cuprite"
+require "axe/cuprite/normalize"
+
+module AxeCuprite
+  module RSpec
+    # The matcher behind `be_axe_clean` / `be_accessible`.
+    #
+    #   expect(page).to be_axe_clean
+    #   expect(page).to be_axe_clean.checking_only(:color_contrast).within("#main")
+    #   expect(page).to be_axe_clean.according_to(:wcag2aa).excluding(".third-party")
+    #   expect(page).to be_axe_clean.skipping(:region)
+    #
+    # All chainers return self so they compose in any order.
+    class BeAxeClean
+      # Cap how many offending elements we print per rule, to keep failure
+      # messages readable on noisy pages.
+      MAX_NODES = 5
+      # Cap HTML snippet length per node.
+      HTML_SNIPPET = 200
+
+      def initialize
+        @includes   = []
+        @excludes   = []
+        @only_rules = []
+        @skip_rules = []
+        @tags       = []
+        @run_options = {}
+        @timeout    = nil
+      end
+
+      # --- chainable DSL ----------------------------------------------------
+
+      # Scope the run to one or more selectors (axe context "include").
+      def within(*selectors)
+        @includes.concat(selectors.flatten)
+        self
+      end
+
+      # Exclude one or more selectors from the run (axe context "exclude").
+      def excluding(*selectors)
+        @excludes.concat(selectors.flatten)
+        self
+      end
+
+      # Run ONLY these rules. Accepts symbols or axe ids; underscores -> hyphens.
+      def checking_only(*rules)
+        @only_rules.concat(rules.flatten)
+        self
+      end
+
+      # Disable these rules for this run (merged with the global skip-list).
+      def skipping(*rules)
+        @skip_rules.concat(rules.flatten)
+        self
+      end
+
+      # Restrict the run to axe tags, e.g. :wcag2aa, :wcag21aa, :best_practice.
+      def according_to(*tags)
+        @tags.concat(tags.flatten)
+        self
+      end
+
+      # Escape hatch: merge raw axe run options (deep-merged, wins on conflict).
+      def with_options(options)
+        @run_options = deep_merge(@run_options, options)
+        self
+      end
+
+      # Override the axe timeout (seconds) for this assertion only.
+      def with_timeout(seconds)
+        @timeout = seconds
+        self
+      end
+
+      # --- RSpec protocol ---------------------------------------------------
+
+      def matches?(page)
+        run!(page)
+
+        if config.report_only && !@violations.empty?
+          config.logger.warn("report_only: #{summary_line}\n#{details}")
+          return true
+        end
+
+        @violations.empty?
+      end
+
+      # Negation ignores report_only: `to_not be_axe_clean` passes iff there
+      # really are violations.
+      def does_not_match?(page)
+        run!(page)
+        !@violations.empty?
+      end
+
+      def failure_message
+        "#{summary_line}\n\n#{details}"
+      end
+
+      def failure_message_when_negated
+        "expected page to have axe-core accessibility violations, but it was clean " \
+          "(0 violations for the selected rules/scope)."
+      end
+
+      def description
+        "be free of axe-core accessibility violations"
+      end
+
+      # Exposed so callers/tests can inspect the full result after matching.
+      attr_reader :results, :violations
+
+      private
+
+      def run!(page)
+        @results = Runner.new(page, configuration: config).run(
+          context: build_context,
+          options: build_options,
+          timeout: @timeout
+        )
+        @violations = @results.violations
+      end
+
+      def config
+        AxeCuprite.configuration
+      end
+
+      # --- context / options builders --------------------------------------
+
+      def build_context
+        if @excludes.empty?
+          return nil if @includes.empty?
+
+          @includes.length == 1 ? @includes.first : { include: @includes }
+        else
+          ctx = { exclude: @excludes }
+          ctx[:include] = @includes unless @includes.empty?
+          ctx
+        end
+      end
+
+      def build_options
+        if !@only_rules.empty? && !@tags.empty?
+          raise ArgumentError,
+                "Use either .checking_only (specific rules) or .according_to (tags), not both."
+        end
+
+        opts = {}
+        if !@only_rules.empty?
+          opts[:runOnly] = { type: "rule", values: Normalize.rules(@only_rules) }
+        elsif !@tags.empty?
+          opts[:runOnly] = { type: "tag", values: Normalize.tags(@tags) }
+        end
+
+        unless @skip_rules.empty?
+          opts[:rules] = Normalize.rules(@skip_rules).each_with_object({}) do |id, h|
+            h[id] = { enabled: false }
+          end
+        end
+
+        deep_merge(opts, @run_options)
+      end
+
+      # --- failure message formatting --------------------------------------
+
+      def summary_line
+        rule_count = @violations.length
+        node_count = @violations.sum { |v| v.nodes.length }
+        "expected page to be axe-clean, but found #{rule_count} " \
+          "#{pluralize(rule_count, 'violation')} across #{node_count} " \
+          "#{pluralize(node_count, 'element')}:"
+      end
+
+      def details
+        @violations.map { |v| format_violation(v) }.join("\n\n")
+      end
+
+      def format_violation(violation)
+        lines = []
+        impact = violation.impact || "n/a"
+        lines << "  ● [#{impact}] #{violation.id} — #{violation.help} " \
+                 "(#{violation.nodes.length} #{pluralize(violation.nodes.length, 'element')})"
+        lines << "    #{violation.help_url}" if violation.help_url
+
+        violation.nodes.first(MAX_NODES).each do |node|
+          lines.concat(format_node(node))
+        end
+
+        remaining = violation.nodes.length - MAX_NODES
+        lines << "      … and #{remaining} more #{pluralize(remaining, 'element')}" if remaining.positive?
+        lines.join("\n")
+      end
+
+      def format_node(node)
+        lines = ["      - #{node.selector}"]
+        lines << "        #{truncate(node.html)}" if node.html
+
+        if (cd = node.contrast_data)
+          lines << "        contrast #{cd.contrast_ratio}:1 (needs #{cd.expected_contrast_ratio}:1) — " \
+                   "fg #{cd.fg_color} on bg #{cd.bg_color}, font #{cd.font_size}/#{cd.font_weight}"
+        elsif (msg = first_check_message(node))
+          lines << "        #{msg}"
+        end
+        lines
+      end
+
+      def first_check_message(node)
+        (node.any + node.none).map { |c| c["message"] if c.is_a?(Hash) }.compact.first
+      end
+
+      def truncate(text)
+        text = text.to_s.gsub(/\s+/, " ").strip
+        text.length > HTML_SNIPPET ? "#{text[0, HTML_SNIPPET]}…" : text
+      end
+
+      def pluralize(count, word)
+        count == 1 ? word : "#{word}s"
+      end
+
+      def deep_merge(base, override)
+        base.merge(override) do |_key, a, b|
+          a.is_a?(Hash) && b.is_a?(Hash) ? deep_merge(a, b) : b
+        end
+      end
+    end
+  end
+end

data/lib/axe/cuprite/rspec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "axe/cuprite"
+require "axe/cuprite/rspec/matchers"
+
+module AxeCuprite
+  module RSpec
+    # Methods mixed into RSpec example groups to expose the matchers.
+    module DSL
+      # expect(page).to be_axe_clean ...
+      def be_axe_clean
+        AxeCuprite::RSpec::BeAxeClean.new
+      end
+
+      # Alias: expect(page).to be_accessible ...
+      def be_accessible
+        AxeCuprite::RSpec::BeAxeClean.new
+      end
+    end
+  end
+end
+
+if defined?(::RSpec) && ::RSpec.respond_to?(:configure)
+  ::RSpec.configure do |config|
+    config.include AxeCuprite::RSpec::DSL
+  end
+end

data/lib/axe/cuprite/runner.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "axe/cuprite/normalize"
+
+module AxeCuprite
+  # Framework-agnostic entry point. No RSpec required.
+  #
+  #   results = AxeCuprite::Runner.new(page).run(
+  #     context: "#main",
+  #     options: { runOnly: { type: "rule", values: ["color-contrast"] } }
+  #   )
+  #   results.violations  # => [AxeCuprite::Violation, ...]
+  #
+  # `page` is a Capybara session (e.g. the `page` in a Capybara test).
+  class Runner
+    attr_reader :page, :configuration
+
+    def initialize(page, configuration: AxeCuprite.configuration)
+      @page = page
+      @configuration = configuration
+      @injector = Injector.new(page, configuration)
+    end
+
+    # Inject axe if not already present, run axe.run(context, options) via the
+    # async path, and return an AxeCuprite::Results.
+    #
+    # - context: axe context arg — a CSS selector String, or a Hash with
+    #   :include / :exclude, or nil for the whole document.
+    # - options: axe run options Hash (runOnly, rules, resultTypes, ...).
+    #   Deep-merged on top of the configured default_options.
+    # - timeout: override the configured axe timeout (seconds) for this run.
+    def run(context: nil, options: {}, timeout: nil)
+      merged = merge_options(options)
+      @injector.run(context: normalize_context(context), options: merged, timeout: timeout)
+    end
+
+    # Force or ensure axe is injected (idempotent unless force: true). Useful
+    # when auto_inject is disabled, or to re-inject after a navigation.
+    def inject!(force: false)
+      @injector.ensure_injected!(force: force)
+    end
+
+    # Is axe-core present on the current page?
+    def injected?
+      @injector.injected?
+    end
+
+    private
+
+    # Apply global configuration (default_options, default_tags, skip_rules)
+    # underneath the caller-supplied options, which always win on conflict.
+    def merge_options(caller_options)
+      opts = deep_stringify(@configuration.default_options)
+      opts = deep_merge(opts, deep_stringify(caller_options))
+
+      # default_tags become a tag-based runOnly, but only if nothing already
+      # scopes runOnly (an explicit rule/tag selection takes precedence).
+      tags = Normalize.tags(@configuration.default_tags)
+      if !opts.key?("runOnly") && !tags.empty?
+        opts["runOnly"] = { "type" => "tag", "values" => tags }
+      end
+
+      # global skip_rules disable rules, without clobbering an explicit caller
+      # setting for the same rule.
+      skip = Normalize.rules(@configuration.skip_rules)
+      unless skip.empty?
+        rules = opts["rules"] || {}
+        skip.each { |id| rules[id] ||= { "enabled" => false } }
+        opts["rules"] = rules
+      end
+
+      opts
+    end
+
+    # axe accepts a selector string, or {include:, exclude:}. Stringify hash
+    # keys so Ferrum serializes them predictably across CDP.
+    def normalize_context(context)
+      case context
+      when nil, String then context
+      when Hash then deep_stringify(context)
+      else context
+      end
+    end
+
+    def deep_stringify(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(k, v), h| h[k.to_s] = deep_stringify(v) }
+      when Array
+        value.map { |v| deep_stringify(v) }
+      else
+        value
+      end
+    end
+
+    def deep_merge(base, override)
+      base.merge(override) do |_key, a, b|
+        a.is_a?(Hash) && b.is_a?(Hash) ? deep_merge(a, b) : b
+      end
+    end
+  end
+end

data/lib/axe/cuprite/tasks/axe.rake

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "open-uri"
+require "fileutils"
+require "json"
+
+namespace :axe do
+  desc "Refresh the vendored axe-core engine. Usage: rake 'axe:update[4.12.0]' or VERSION=4.12.0 rake axe:update (default: latest)"
+  task :update, [:version] do |_task, args|
+    version = args[:version] || ENV["VERSION"] || AxeCupriteVendor.latest_version
+    AxeCupriteVendor.update!(version)
+  end
+
+  desc "Print the currently vendored axe-core version"
+  task :version do
+    puts AxeCupriteVendor.vendored_version
+  end
+end
+
+# Helpers for vendoring axe-core. Kept in a module so the rake tasks stay thin
+# and the logic is easy to read. Never used at runtime — vendoring is a
+# development-time step; the engine ships in the gem.
+module AxeCupriteVendor
+  VENDOR_DIR   = File.expand_path("../vendor", __dir__)
+  AXE_JS       = File.join(VENDOR_DIR, "axe.min.js")
+  AXE_LICENSE  = File.join(VENDOR_DIR, "axe-core-LICENSE.txt")
+  VERSION_FILE = File.expand_path("../version.rb", __dir__)
+  REGISTRY     = "https://registry.npmjs.org/axe-core"
+  CDN          = "https://unpkg.com/axe-core"
+
+  module_function
+
+  def update!(version)
+    FileUtils.mkdir_p(VENDOR_DIR)
+
+    puts "Fetching axe-core@#{version} ..."
+    js = download("#{CDN}@#{version}/axe.min.js")
+    unless js =~ /axe v#{Regexp.escape(version)}\b/
+      warn "Warning: downloaded axe.min.js banner does not mention v#{version} — continuing anyway."
+    end
+    license = download("#{CDN}@#{version}/LICENSE")
+
+    File.write(AXE_JS, js)
+    File.write(AXE_LICENSE, license)
+    bump_version_constant(version)
+
+    puts "Vendored axe-core #{version}:"
+    puts "  #{AXE_JS} (#{js.bytesize} bytes)"
+    puts "  #{AXE_LICENSE}"
+    puts "  updated AXE_CORE_VERSION in #{VERSION_FILE}"
+    puts "Remember to note the version bump in CHANGELOG.md."
+  end
+
+  def latest_version
+    JSON.parse(download("#{REGISTRY}/latest")).fetch("version")
+  end
+
+  def vendored_version
+    File.read(AXE_JS)[/axe v([0-9][0-9.]*)/, 1] || "unknown"
+  end
+
+  def download(url)
+    URI.parse(url).open(&:read)
+  rescue OpenURI::HTTPError => e
+    abort "Failed to download #{url}: #{e.message}"
+  end
+
+  def bump_version_constant(version)
+    contents = File.read(VERSION_FILE)
+    updated = contents.sub(/(AXE_CORE_VERSION\s*=\s*)"[^"]*"/, %(\\1"#{version}"))
+    File.write(VERSION_FILE, updated)
+  end
+end