axe-cuprite 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1005023d8e3178edd24de983e954208d297ee0ca720f33ba822f14c33861b17f
-  data.tar.gz: 5b0b13f67c92e8b89d1d4b4f2f9b4957ae71690d60eeb006edd2e9239bd89dd7
+  metadata.gz: e56b57fadf23c8ab623bd1a3005d94ce158832160a9ec3bfd1591b070312d953
+  data.tar.gz: 2cdad2a18469b669266938df7476040d702b53419bb8a80076e918c282bf218e
 SHA512:
-  metadata.gz: 439317e53b00d1f6a4f4c275f02b5caa9c6d0add981079b809a3363c937fab3431226db540f6163ad908a47b0869782db0b0bfd98f5b229bb121b45b9733acb6
-  data.tar.gz: 9ade47a886507d6349a680abd9446fc5191048172b1a40f660a694dc93afa0841528d73a5eb4e281d30960fa4fad4b72e87d359a969c3e15274f9213c76c9587
+  metadata.gz: 2262ff93c4a88cda10c54d650b74f9353d8d1ae98f0f0a4df82b1483cc755e6347e23be923dedee4fffa726de3229ae4f4e9a00d18f704750f21513038d2515e
+  data.tar.gz: 8f001777544278d53266271b66c9d93bb32e0ed2d9e8969fa2413d69342649028be46c78c40706ec526e863c2fa13106a451856b7dfa7db8d23e0852b3367a9f

data/CHANGELOG.md

@@ -7,6 +7,107 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-06-16
+
+First stable release. No functional changes since `0.2.0` — this tags the API as
+stable under [Semantic Versioning](https://semver.org/spec/v2.0.0.html). The
+public API is the documented surface of `AxeCuprite`, `AxeCuprite::Configuration`,
+`AxeCuprite::Runner`, the result wrappers (`Results`/`Violation`/`Node`/
+`ContrastData`), the error classes, and the RSpec matcher DSL; classes such as
+`AxeCuprite::Injector` and `AxeCuprite::DeepFreeze` are internal and not covered
+by the stability guarantee.
+
+### Fixed
+- The packaged gem no longer ships the dev-only vendoring rake tasks
+  (`lib/axe/cuprite/tasks/*.rake` — `axe:update` / `axe:verify` / `axe:version`).
+  These operate on the gem's read-only, version-pinned `vendor/` directory and
+  `axe:verify` couldn't even run from an installed gem (its recorded checksum
+  isn't shipped), so they were broken for consumers. They remain available in a
+  repo checkout for development
+  ([#32](https://github.com/Guided-Rails/axe-cuprite/issues/32)).
+
+### Changed
+- Repositioned as **Cuprite-only**: the README, gemspec `description`, and
+  `AGENTS.md` no longer advertise support for "any real-browser Capybara driver."
+  Cuprite is the only supported and tested driver; the driver-neutral JS approach
+  is described as the implementation detail that makes the gem work on Cuprite
+  (and avoid Selenium internals), not a promise of broad driver support. The
+  best-effort non-Ferrum fallback in `Injector#evaluate_axe` is kept but is now
+  documented as unsupported/untested
+  ([#31](https://github.com/Guided-Rails/axe-cuprite/issues/31)).
+- Documented that `AxeCuprite::Results` (and its nested wrappers) takes ownership
+  of the hash passed in and deep-freezes it **in place** — so a caller
+  constructing `Results.new(hash)` shouldn't pass or reuse a hash they intend to
+  mutate afterward. No behavior change; clarifies the existing read-only contract
+  in the `Results` doc comment and the README runner section
+  ([#33](https://github.com/Guided-Rails/axe-cuprite/issues/33)).
+
+### Added
+- A unit test pinning the best-effort non-Ferrum fallback in
+  `Injector#evaluate_axe`: with no Ferrum page it routes through
+  `evaluate_async_script` under the explicit timeout rather than
+  `Capybara.default_max_wait_time`, so the path can't silently break
+  ([#31](https://github.com/Guided-Rails/axe-cuprite/issues/31)).
+
+## [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
@@ -38,3 +139,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   auto-inject toggle, and report-only mode.
 - `rake axe:update[VERSION]` to refresh the vendored axe-core engine and bump
   the `AXE_CORE_VERSION` constant.
+
+[Unreleased]: https://github.com/Guided-Rails/axe-cuprite/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/Guided-Rails/axe-cuprite/compare/v0.2.0...v1.0.0
+[0.2.0]: https://github.com/Guided-Rails/axe-cuprite/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/Guided-Rails/axe-cuprite/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/Guided-Rails/axe-cuprite/releases/tag/v0.1.0

data/README.md

@@ -1,5 +1,9 @@
 # axe-cuprite
 
+[![Gem Version](https://img.shields.io/gem/v/axe-cuprite)](https://rubygems.org/gems/axe-cuprite)
+[![CI](https://github.com/Guided-Rails/axe-cuprite/actions/workflows/ci.yml/badge.svg)](https://github.com/Guided-Rails/axe-cuprite/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
 Run the [axe-core](https://github.com/dequelabs/axe-core) accessibility engine
 against pages in your **Capybara system/feature tests driven by
 [Cuprite](https://github.com/rubycdp/cuprite)** (the CDP/Ferrum headless-Chrome
@@ -23,13 +27,24 @@ they break.
 just a JavaScript file — a driver-agnostic engine — so we drive it exclusively
 through Capybara's **driver-neutral** JavaScript API (`execute_script`,
 `evaluate_async_script`), which Cuprite fully implements. That single decision is
-what makes this gem work where the official one doesn't. As a bonus it stays
-driver-agnostic (it works on any real-browser Capybara driver), but **Cuprite is
-the primary, must-pass target.**
+what makes this gem work where the official one doesn't.
+
+**Cuprite is the only supported and tested driver.** Driving axe through the
+driver-neutral JS API is what lets the gem avoid Selenium internals — not a promise
+of broad driver support. Other real-browser drivers may happen to work (a
+best-effort fallback exists), but they are unsupported and untested.
 
 There is no runtime dependency on Selenium, Cuprite, or Ferrum — the only runtime
 dependency is Capybara. You bring your own driver.
 
+## Requirements
+
+- **Ruby** >= 3.0
+- **Capybara** >= 3.0, < 4.0 (the only runtime dependency)
+- **[Cuprite](https://github.com/rubycdp/cuprite)** as the Capybara driver — the
+  only supported and tested driver
+- **Chrome or Chromium**, which Cuprite drives over CDP
+
 ## Installation
 
 ```ruby
@@ -146,6 +161,13 @@ on top of your configured defaults. Only `violations` and `incomplete` are
 carried back across the CDP boundary — the full results object (with
 `passes`/`inapplicable`) can be huge.
 
+`AxeCuprite::Results` is read-only: it **takes ownership of the hash it's given
+and deep-freezes it in place** (this backs the read-only `raw`/`to_h` contract).
+You normally get one straight from `Runner#run`, so this is transparent — but if
+you construct `Results.new(hash)` yourself, don't pass or keep a reference to a
+hash you intend to mutate afterward, or you'll hit a `FrozenError`. Dup it first
+if you need a mutable copy.
+
 ## Configuration
 
 ```ruby
@@ -156,6 +178,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 +190,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`)
@@ -180,10 +219,11 @@ page routinely exceeds.
 axe-cuprite avoids this trap: on Cuprite it calls Ferrum's
 `page.evaluate_async(script, explicit_wait, *args)` **directly**, with its own
 timeout (default **30s**, configurable) that is completely **decoupled from
-`default_max_wait_time`**. On non-Ferrum drivers it falls back to
-`evaluate_async_script` under a temporarily-raised wait time. If axe still
-doesn't finish, you get a clear `AxeCuprite::TimeoutError` telling you to raise
-the timeout or scope the run with `.within`.
+`default_max_wait_time`**. (On a non-Ferrum driver there is a best-effort,
+untested fallback to `evaluate_async_script` under a temporarily-raised wait time —
+but Cuprite is the only supported driver.) If axe still doesn't finish, you get a
+clear `AxeCuprite::TimeoutError` telling you to raise the timeout or scope the run
+with `.within`.
 
 Tune it globally (`c.timeout = 60`) or per assertion (`.with_timeout(60)`).
 
@@ -223,10 +263,33 @@ 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`.
+
+## Versioning
+
+axe-cuprite follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The **public API** covered by that guarantee is the documented surface:
+`AxeCuprite` (module methods), `AxeCuprite::Configuration`, `AxeCuprite::Runner`,
+the result wrappers (`Results` / `Violation` / `Node` / `ContrastData`), the error
+classes, and the RSpec matcher DSL (`be_axe_clean` / `be_accessible` and its
+chainers). Classes like `AxeCuprite::Injector` and `AxeCuprite::DeepFreeze` are
+internal implementation details and may change in any release. Breaking changes to
+the public API only land in a major version, and every release is noted in
+[`CHANGELOG.md`](CHANGELOG.md).
+
+Note that the **vendored axe-core version** can change in a minor release; axe may
+report new violations after an engine bump, which can turn a previously-green
+suite red. Such bumps are always called out in the changelog.
 
 ## 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,43 @@
 # 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).
+  #
+  # Ownership note: `Results` (and the nested `Violation`/`Node`/`ContrastData`
+  # wrappers) **take ownership of the hash passed in and deep-freeze it in place**
+  # — they do not copy first. For the internal flow this is safe (the payload
+  # comes fresh off the CDP boundary), but if you construct `Results.new(hash)`
+  # yourself, don't pass — or hold onto — a hash you intend to mutate afterward,
+  # or you'll hit a `FrozenError`. Dup it first if you need a mutable copy.
   class Results
     attr_reader :raw
 
     def initialize(raw)
-      @raw = raw || {}
+      @raw = DeepFreeze.call(raw || {})
     end
 
     def violations
@@ -47,7 +76,7 @@ module AxeCuprite
     attr_reader :raw
 
     def initialize(raw)
-      @raw = raw || {}
+      @raw = DeepFreeze.call(raw || {})
     end
 
     def id
@@ -88,7 +117,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 +166,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/runner.rb

@@ -73,11 +73,7 @@ module AxeCuprite
     # 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
+      context.is_a?(Hash) ? deep_stringify(context) : context
     end
 
     def deep_stringify(value)

data/lib/axe/cuprite/version.rb

@@ -2,7 +2,7 @@
 
 module AxeCuprite
   # Version of the axe-cuprite gem itself.
-  VERSION = "0.1.1"
+  VERSION = "1.0.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`.

data/lib/axe/cuprite.rb

@@ -8,8 +8,10 @@ require "axe/cuprite/injector"
 require "axe/cuprite/runner"
 
 # axe-cuprite drives the axe-core accessibility engine through Capybara's
-# driver-neutral JavaScript API, so it works with Cuprite (Ferrum/CDP) and any
-# other real-browser Capybara driver — without ever touching Selenium internals.
+# driver-neutral JavaScript API. That approach is what lets it avoid Selenium
+# internals and work on Cuprite (Ferrum/CDP) — the only supported and tested
+# driver. Other real-browser drivers may work via a best-effort, untested
+# fallback, but they are unsupported.
 #
 # Quick start:
 #

data/lib/axe-cuprite.rb

@@ -1,5 +1,3 @@
 # frozen_string_literal: true
 
-# Convenience entry point so `require "axe-cuprite"` works.
-# The canonical require path is "axe/cuprite".
 require "axe/cuprite"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: axe-cuprite
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Abdullah Hashim
@@ -29,165 +29,13 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '4.0'
-- !ruby/object:Gem::Dependency
-  name: cuprite
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.17'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.17'
-- !ruby/object:Gem::Dependency
-  name: ferrum
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.17'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.17'
-- !ruby/object:Gem::Dependency
-  name: puma
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '5.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '9.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '5.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '9.0'
-- !ruby/object:Gem::Dependency
-  name: rack
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4.0'
-- !ruby/object:Gem::Dependency
-  name: rackup
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.86'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.86'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.7'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.7'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
 description: |
   axe-cuprite runs the axe-core accessibility engine against pages rendered in
   Capybara system/feature tests and exposes the results as RSpec matchers
   (be_axe_clean / be_accessible). Unlike Deque's official axe-core-capybara gem,
   it never touches Selenium-specific driver internals: axe is driven entirely
-  through Capybara's driver-neutral JavaScript API, so it works with Cuprite
-  and any other real-browser driver.
+  through Capybara's driver-neutral JavaScript API, which is what makes it work
+  on Cuprite. Cuprite is the only supported and tested driver.
 email:
 - abdullah@guidedrails.com
 executables: []
@@ -207,7 +55,6 @@ files:
 - lib/axe/cuprite/rspec.rb
 - lib/axe/cuprite/rspec/matchers.rb
 - lib/axe/cuprite/runner.rb
-- lib/axe/cuprite/tasks/axe.rake
 - lib/axe/cuprite/vendor/axe-core-LICENSE.txt
 - lib/axe/cuprite/vendor/axe.min.js
 - lib/axe/cuprite/version.rb
@@ -217,6 +64,8 @@ licenses:
 metadata:
   source_code_uri: https://github.com/Guided-Rails/axe-cuprite
   changelog_uri: https://github.com/Guided-Rails/axe-cuprite/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Guided-Rails/axe-cuprite/issues
+  documentation_uri: https://github.com/Guided-Rails/axe-cuprite/blob/main/README.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:

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

@@ -1,73 +0,0 @@
-# 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