axe-cuprite 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1005023d8e3178edd24de983e954208d297ee0ca720f33ba822f14c33861b17f
-  data.tar.gz: 5b0b13f67c92e8b89d1d4b4f2f9b4957ae71690d60eeb006edd2e9239bd89dd7
+  metadata.gz: 91d61bb330869ef24f40d7b9c09859daf23212f99dd8b6c14506238d48cfe9f2
+  data.tar.gz: 0d023ead7e8245bf03d428ef4912c093a32888c7528d0e95307ca3036a77db2b
 SHA512:
-  metadata.gz: 439317e53b00d1f6a4f4c275f02b5caa9c6d0add981079b809a3363c937fab3431226db540f6163ad908a47b0869782db0b0bfd98f5b229bb121b45b9733acb6
-  data.tar.gz: 9ade47a886507d6349a680abd9446fc5191048172b1a40f660a694dc93afa0841528d73a5eb4e281d30960fa4fad4b72e87d359a969c3e15274f9213c76c9587
+  metadata.gz: b41901a481d94378f0945a89cc4e7e4d6c3f198d45e06737d910841657aaaba6b4f8ccb32538cfb7af45607ea25049787e8a47b85e6e63a45845af7744a1033c
+  data.tar.gz: 906bb0a2bc25c10140185a9385192c1f629ef3803447cf31862f96e0c9f9d41589da8cb317b8220c6d3ffa37390eb8fe33f1f72729e243c8034104df12e4ae6a

data/CHANGELOG.md

@@ -7,6 +7,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-06-10
+
+### Added
+- `config.include_html` (default `true`) — set to `false` to suppress the
+  truncated outer-HTML snippets that failure messages and `report_only` logs
+  print for each offending element. Useful for suites that render sensitive data
+  (staging-backed tests, seeded PII), keeping page content out of CI logs while
+  still reporting rule id, selector, and check message. Documented the snippet
+  behavior and `logger` guidance in the README
+  ([#14](https://github.com/Guided-Rails/axe-cuprite/issues/14)).
+
+### Fixed
+- The result wrappers (`Results`/`Violation`/`Node`/`ContrastData`) now honor
+  their documented read-only contract: `@raw` is deep-frozen at construction, so
+  `raw` and `to_h` can safely expose the live underlying hash without a caller
+  being able to mutate the wrapper's internal state (which, via memoization,
+  could previously desync `violations`/`incomplete` from `raw`)
+  ([#17](https://github.com/Guided-Rails/axe-cuprite/issues/17)).
+- `Injector#inject_source!` no longer hides the real cause of an injection
+  failure behind a blanket Content-Security-Policy message. When both the
+  primary `execute_script` path and the `add_script_tag` fallback fail, the
+  exceptions they raised are now captured and appended to the `InjectionError`
+  message (`Underlying errors: execute_script: ...; add_script_tag: ...`), so a
+  dead browser, dead CDP session, or misconfigured driver is no longer
+  misattributed to CSP ([#15](https://github.com/Guided-Rails/axe-cuprite/issues/15)).
+- `Injector#timeout_error?` no longer reclassifies arbitrary failures as
+  `AxeCuprite::TimeoutError` just because the error message mentions a timeout.
+  A genuine page-side JavaScript error (e.g. a `Ferrum::JavaScriptError` from axe
+  or the app whose text happens to contain "timeout") now propagates untouched
+  instead of being rewritten with misleading "increase the timeout / scope the
+  run" guidance. Classification is driven by error class (Ferrum's
+  timeout/script-timeout classes), with a narrow class-gated message check only
+  for Ferrum's async-evaluation "timed out promise" case; this also removes a
+  dead code branch that could never affect the result
+  ([#16](https://github.com/Guided-Rails/axe-cuprite/issues/16)).
+
+### Security
+- `rake axe:update` now vendors axe-core from the official npm registry tarball
+  (`registry.npmjs.org`) instead of the unpkg CDN, verifies the tarball against
+  the registry-published sha512 `dist.integrity` (and legacy `dist.shasum`)
+  **before writing anything**, and treats a banner/version mismatch as fatal
+  instead of a warning ([#11](https://github.com/Guided-Rails/axe-cuprite/issues/11)).
+- The sha512 of the vendored `axe.min.js` is now recorded in
+  `lib/axe/cuprite/vendor/axe.min.js.sha512`; a new `rake axe:verify` task
+  re-checks the vendored engine against it, and CI runs it on every build.
+- Hardened the CI workflow: added a least-privilege `permissions: contents: read`
+  block (the `GITHUB_TOKEN` previously inherited the repo default, potentially
+  write-all) and pinned `actions/checkout` and `ruby/setup-ruby` to full commit
+  SHAs instead of mutable major-version tags. Added a Dependabot config
+  (`.github/dependabot.yml`) for the `github-actions` and `bundler` ecosystems so
+  the pinned SHAs and gem dependencies get automated update PRs
+  ([#12](https://github.com/Guided-Rails/axe-cuprite/issues/12)).
+- `rake axe:update[VERSION]` now validates the `VERSION` argument against a
+  semver-ish pattern **before** any network call or file write. The value was
+  previously spliced unvalidated into the registry/download URL and into
+  `version.rb`, so a crafted string (e.g. `4.12.0/../other-pkg`, or one
+  containing a quote) could vendor a different package or break out of the
+  version string literal ([#13](https://github.com/Guided-Rails/axe-cuprite/issues/13)).
+
 ## [0.1.1] - 2026-06-09
 
 ### Added

data/README.md

@@ -156,6 +156,7 @@ AxeCuprite.configure do |c|
   c.skip_rules      = [:region]   # globally disabled rules
   c.auto_inject     = true        # (re)inject axe on demand inside #run
   c.report_only     = false       # log violations instead of failing (see below)
+  c.include_html    = true        # include element HTML snippets in output (see below)
   c.logger          = Logger.new($stdout)
 end
 ```
@@ -167,6 +168,22 @@ This eases incremental adoption on an existing app — you can see what axe find
 without turning the suite red. Negated assertions (`expect(page).not_to
 be_axe_clean`) ignore this flag.
 
+### Sensitive page content in output (`include_html`)
+
+Both failure messages and `report_only` logs include a **truncated outer-HTML
+snippet** (capped at 200 chars) of each offending element, so you can see *what*
+failed at a glance. On suites that render real data — staging-backed tests,
+seeded PII — those snippets can carry page content into CI logs or log
+aggregation. This is normal for a testing tool, but if it matters to you:
+
+- Point `c.logger` somewhere appropriate (a redacted sink, a dropped stream)
+  rather than `$stdout`, so `report_only` output doesn't fan out to aggregation.
+- Set `c.include_html = false` to drop the HTML snippets entirely. Output then
+  carries only the rule id, impact, help URL, element **selector**, and the axe
+  check message (for color-contrast, the fg/bg colors and ratio) — enough to
+  locate and fix a violation without echoing page content. Note the selector
+  itself can still reflect ids/classes from your markup.
+
 ## Caveats & engineering notes
 
 ### Timeout (decoupled from `default_max_wait_time`)
@@ -223,10 +240,17 @@ To refresh it:
 rake 'axe:update[4.12.0]'   # pin a version
 rake axe:update             # or grab the latest from npm
 rake axe:version            # print the currently vendored version
+rake axe:verify             # check axe.min.js against its recorded sha512
 ```
 
-`axe:update` downloads `axe.min.js` and its `LICENSE` from unpkg and bumps the
-`AXE_CORE_VERSION` constant. Note the bump in `CHANGELOG.md`.
+`axe:update` downloads the official `axe-core` tarball from
+**registry.npmjs.org**, verifies it against the sha512 integrity the registry
+publishes (aborting on any mismatch before writing a byte), extracts
+`axe.min.js` and its `LICENSE`, and bumps the `AXE_CORE_VERSION` constant. The
+sha512 of the vendored engine is recorded in
+`lib/axe/cuprite/vendor/axe.min.js.sha512` so it can be re-checked at any time
+with `rake axe:verify` (CI does this on every run). Note the bump in
+`CHANGELOG.md`.
 
 ## Licensing
 

data/lib/axe/cuprite/configuration.rb

@@ -34,6 +34,13 @@ module AxeCuprite
     # Logger used for report_only output and warnings.
     attr_accessor :logger
 
+    # When true (default), failure messages and report_only logs include a
+    # truncated outer-HTML snippet of each offending element. Set to false to
+    # suppress those snippets (rule id + selector + check message only) on
+    # suites that render sensitive data, so page content can't leak into CI
+    # logs. See BeAxeClean#format_node.
+    attr_accessor :include_html
+
     def initialize
       @timeout         = 30
       @default_options = {}
@@ -41,6 +48,7 @@ module AxeCuprite
       @skip_rules      = []
       @auto_inject     = true
       @report_only     = false
+      @include_html    = true
       @logger          = default_logger
     end
 

data/lib/axe/cuprite/injector.rb

@@ -46,6 +46,17 @@ module AxeCuprite
     # JS expression that reports whether axe is loaded and runnable.
     PRESENCE_JS = "typeof window.axe !== 'undefined' && typeof window.axe.run === 'function'"
 
+    # Dedicated timeout classes that mean "the evaluation timed out" regardless
+    # of message. Matched by name (not constant) so we keep no hard dependency on
+    # ferrum — it's a dev-only dep. Covers Ferrum's own timeouts (the Cuprite
+    # fast-path, via page.evaluate_async). A non-Ferrum driver's own script-timeout
+    # error propagates raw rather than being wrapped — we don't depend on or test
+    # any such driver here, so we don't guess at its class names. See #timeout_error?.
+    TIMEOUT_ERROR_CLASS_NAMES = [
+      "Ferrum::TimeoutError",
+      "Ferrum::ScriptTimeoutError"
+    ].freeze
+
     def initialize(page, configuration = AxeCuprite.configuration)
       @page = page
       @config = configuration
@@ -73,20 +84,23 @@ module AxeCuprite
     # to Ferrum's add_script_tag.
     def inject_source!
       source = AxeCuprite.axe_source
+      errors = {}
 
       begin
         @page.execute_script(source)
-      rescue StandardError
-        nil
+      rescue StandardError => e
+        errors["execute_script"] = e
       end
       return true if injected?
 
-      try_add_script_tag(source)
+      begin
+        try_add_script_tag(source)
+      rescue StandardError => e
+        errors["add_script_tag"] = e
+      end
       return true if injected?
 
-      raise InjectionError,
-            "axe-core did not load after injection. The page may be blocking " \
-            "script injection (e.g. a strict Content-Security-Policy)."
+      raise InjectionError, injection_failure_message(errors)
     end
 
     # Run axe and return a Results object. Injects on demand if needed.
@@ -154,24 +168,47 @@ module AxeCuprite
       nil
     end
 
-    # Best-effort CSP fallback via Ferrum's add_script_tag(content:).
+    # Best-effort CSP fallback via Ferrum's add_script_tag(content:). Returns
+    # false when no Ferrum add_script_tag is available (non-Ferrum drivers); lets
+    # a genuine injection failure propagate so inject_source! can report it.
     def try_add_script_tag(source)
       fpage = ferrum_page
       return false unless fpage.respond_to?(:add_script_tag)
 
       fpage.add_script_tag(content: source)
       true
-    rescue StandardError
-      false
     end
 
+    # Build the InjectionError message, appending whatever the injection paths
+    # actually raised so a non-CSP failure (dead browser, dead CDP session,
+    # misconfigured driver) isn't silently blamed on Content-Security-Policy.
+    def injection_failure_message(errors)
+      message = "axe-core did not load after injection. The page may be blocking " \
+                "script injection (e.g. a strict Content-Security-Policy)."
+      return message if errors.empty?
+
+      detail = errors.map { |path, e| "#{path}: #{e.class}: #{e.message}" }.join("; ")
+      "#{message}\nUnderlying errors: #{detail}"
+    end
+
+    # Did `evaluate_axe` fail because axe.run genuinely timed out (so the
+    # "increase the timeout / scope the run" guidance is right), or did it hit a
+    # real page-side error that must propagate untouched?
+    #
+    # Classification is driven by error CLASS, not message. A message that merely
+    # mentions a timeout is deliberately NOT sufficient: a real Ferrum::JavaScriptError
+    # from axe or the app whose text happens to contain "timeout" must not be
+    # rewritten as an AxeCuprite::TimeoutError with misleading guidance.
+    #
+    # The one message check is narrow and class-gated: Ferrum reports its own
+    # async-evaluation timeout (page.evaluate_async) as a generic JavaScriptError
+    # carrying a "timed out promise" message, so for that class — and only that
+    # class — the message is what tells a timeout apart from a real JS error.
     def timeout_error?(error)
-      return true if error.message.to_s =~ /tim(e|ed)\s*out/i
+      name = error.class.name.to_s
+      return true if TIMEOUT_ERROR_CLASS_NAMES.include?(name)
 
-      # Ferrum raises its own timeout/JS errors; match by class name without a
-      # hard dependency on the Ferrum constants (ferrum is only a dev dep here).
-      error.class.name.to_s =~ /Ferrum::(Timeout|JavaScript)Error/ &&
-        error.message.to_s =~ /timed out promise/i
+      name == "Ferrum::JavaScriptError" && error.message.to_s.match?(/timed out promise/i)
     end
   end
 end

data/lib/axe/cuprite/results.rb

@@ -1,14 +1,36 @@
 # frozen_string_literal: true
 
 module AxeCuprite
+  # Recursively freezes a parsed-JSON tree (hashes/arrays of scalars) so the
+  # read-only wrappers below can hand out `raw`/`to_h` without a caller being
+  # able to mutate internal state (which, via memoization, could otherwise
+  # desync `violations`/`incomplete` from `raw`). Idempotent and cheap on the
+  # slimmed payload we carry back.
+  module DeepFreeze
+    module_function
+
+    def call(obj)
+      case obj
+      when Hash
+        obj.each { |k, v| [k, v].each { |o| call(o) } }
+      when Array
+        obj.each { |v| call(v) }
+      end
+      obj.freeze
+    end
+  end
+
   # 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.
+  #
+  # The wrappers are read-only: `@raw` is deep-frozen at construction, so `raw`
+  # and `to_h` expose the live underlying hash safely (callers cannot mutate it).
   class Results
     attr_reader :raw
 
     def initialize(raw)
-      @raw = raw || {}
+      @raw = DeepFreeze.call(raw || {})
     end
 
     def violations
@@ -47,7 +69,7 @@ module AxeCuprite
     attr_reader :raw
 
     def initialize(raw)
-      @raw = raw || {}
+      @raw = DeepFreeze.call(raw || {})
     end
 
     def id
@@ -88,7 +110,7 @@ module AxeCuprite
     attr_reader :raw
 
     def initialize(raw)
-      @raw = raw || {}
+      @raw = DeepFreeze.call(raw || {})
     end
 
     # axe gives `target` as an array of CSS selectors (one per frame depth).
@@ -137,7 +159,7 @@ module AxeCuprite
     attr_reader :raw
 
     def initialize(raw)
-      @raw = raw || {}
+      @raw = DeepFreeze.call(raw || {})
     end
 
     def fg_color

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

@@ -193,7 +193,7 @@ module AxeCuprite
 
       def format_node(node)
         lines = ["      - #{node.selector}"]
-        lines << "        #{truncate(node.html)}" if node.html
+        lines << "        #{truncate(node.html)}" if node.html && config.include_html
 
         if (cd = node.contrast_data)
           lines << "        contrast #{cd.contrast_ratio}:1 (needs #{cd.expected_contrast_ratio}:1) — " \

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

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
-require "open-uri"
+require "digest"
 require "fileutils"
 require "json"
+require "open-uri"
+require "rubygems/package"
+require "stringio"
+require "zlib"
 
 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)"
@@ -15,40 +19,60 @@ namespace :axe do
   task :version do
     puts AxeCupriteVendor.vendored_version
   end
+
+  desc "Verify the vendored axe.min.js against its recorded sha512 checksum"
+  task :verify do
+    AxeCupriteVendor.verify_vendored!
+  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.
+#
+# Supply-chain note: the vendored axe.min.js is the JavaScript this gem injects
+# into every consumer's browser session, so its integrity is the gem's most
+# important supply-chain property. We therefore download the *official npm
+# tarball* from registry.npmjs.org (not a CDN re-serving it), verify it against
+# the sha512 integrity the registry publishes in its metadata, and abort on any
+# mismatch before a single byte is written. The verified content hash of the
+# extracted axe.min.js is recorded next to it (axe.min.js.sha512) so reviewers
+# and CI can re-check the vendored artifact without re-downloading.
 module AxeCupriteVendor
   VENDOR_DIR   = File.expand_path("../vendor", __dir__)
   AXE_JS       = File.join(VENDOR_DIR, "axe.min.js")
+  AXE_SHA512   = File.join(VENDOR_DIR, "axe.min.js.sha512")
   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
 
+  # A semver-ish version string: three dot-separated numbers with an optional
+  # prerelease suffix. Rejecting anything else keeps the value safe to splice
+  # into the registry URL and into version.rb, and catches honest typos before
+  # they corrupt the vendor directory.
+  VERSION_FORMAT = /\A\d+\.\d+\.\d+(-[\w.]+)?\z/
+
   def update!(version)
+    abort "Invalid version: #{version.inspect}" unless version.match?(VERSION_FORMAT)
+
     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")
+    dist = registry_dist(version)
+    puts "Downloading #{dist.fetch("tarball")} ..."
+    tarball = download(dist.fetch("tarball"))
+    verify_tarball!(tarball, dist)
+
+    js, license = extract(tarball, "package/axe.min.js", "package/LICENSE")
+    verify_banner!(js, version)
 
     File.write(AXE_JS, js)
     File.write(AXE_LICENSE, license)
+    File.write(AXE_SHA512, "#{Digest::SHA512.hexdigest(js)}  axe.min.js\n")
     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."
+    report(version, js)
   end
 
   def latest_version
@@ -59,8 +83,71 @@ module AxeCupriteVendor
     File.read(AXE_JS)[/axe v([0-9][0-9.]*)/, 1] || "unknown"
   end
 
+  def verify_vendored!
+    abort "No recorded checksum at #{AXE_SHA512} — run rake axe:update first." unless File.exist?(AXE_SHA512)
+
+    expected = File.read(AXE_SHA512).split.first
+    actual   = Digest::SHA512.hexdigest(File.binread(AXE_JS))
+    unless actual == expected
+      abort <<~MSG
+        MISMATCH: #{AXE_JS} does not match its recorded sha512.
+          recorded: #{expected}
+          actual:   #{actual}
+      MSG
+    end
+
+    puts "OK: axe.min.js matches its recorded sha512."
+  end
+
+  def registry_dist(version)
+    puts "Fetching axe-core@#{version} metadata from #{REGISTRY} ..."
+    JSON.parse(download("#{REGISTRY}/#{version}")).fetch("dist")
+  end
+
+  # Abort unless the downloaded tarball matches the integrity values the npm
+  # registry publishes for it (dist.integrity sha512, plus legacy dist.shasum).
+  def verify_tarball!(tarball, dist)
+    integrity = dist["integrity"]
+    abort "Registry metadata has no sha512 integrity for the tarball — refusing to vendor." unless integrity&.start_with?("sha512-")
+
+    actual = "sha512-#{Digest::SHA512.base64digest(tarball)}"
+    unless actual == integrity
+      abort <<~MSG
+        Tarball integrity check FAILED — refusing to vendor.
+          expected (registry dist.integrity): #{integrity}
+          actual   (downloaded tarball):      #{actual}
+      MSG
+    end
+
+    shasum = dist["shasum"]
+    if shasum && Digest::SHA1.hexdigest(tarball) != shasum
+      abort "Tarball sha1 shasum mismatch (registry says #{shasum}) — refusing to vendor."
+    end
+
+    puts "  tarball integrity verified (#{integrity})"
+  end
+
+  # Secondary sanity check on the extracted engine itself; fatal on mismatch.
+  def verify_banner!(engine_js, version)
+    return if engine_js.match?(/axe v#{Regexp.escape(version)}\b/)
+
+    abort "Extracted axe.min.js banner does not mention v#{version} — refusing to vendor."
+  end
+
+  def extract(tarball, *paths)
+    found = {}
+    Zlib::GzipReader.wrap(StringIO.new(tarball)) do |gz|
+      Gem::Package::TarReader.new(gz) do |tar|
+        tar.each { |entry| found[entry.full_name] = entry.read if paths.include?(entry.full_name) }
+      end
+    end
+    missing = paths - found.keys
+    abort "Tarball is missing expected file(s): #{missing.join(", ")}" unless missing.empty?
+    found.values_at(*paths)
+  end
+
   def download(url)
-    URI.parse(url).open(&:read)
+    URI.parse(url).open("rb", &:read)
   rescue OpenURI::HTTPError => e
     abort "Failed to download #{url}: #{e.message}"
   end
@@ -70,4 +157,13 @@ module AxeCupriteVendor
     updated = contents.sub(/(AXE_CORE_VERSION\s*=\s*)"[^"]*"/, %(\\1"#{version}"))
     File.write(VERSION_FILE, updated)
   end
+
+  def report(version, engine_js)
+    puts "Vendored axe-core #{version} (tarball integrity verified):"
+    puts "  #{AXE_JS} (#{engine_js.bytesize} bytes)"
+    puts "  #{AXE_SHA512}"
+    puts "  #{AXE_LICENSE}"
+    puts "  updated AXE_CORE_VERSION in #{VERSION_FILE}"
+    puts "Remember to note the version bump in CHANGELOG.md."
+  end
 end

data/lib/axe/cuprite/version.rb

@@ -2,7 +2,7 @@
 
 module AxeCuprite
   # Version of the axe-cuprite gem itself.
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 
   # Version of the axe-core engine vendored under lib/axe/cuprite/vendor/axe.min.js.
   # Keep this in sync with the vendored file via `rake axe:update`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: axe-cuprite
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Abdullah Hashim