perchfall 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e958ae8eb16aae40c5d8b0b0e91d3798b14306247aac27f09b2ff8dd08b291b8
-  data.tar.gz: c1f4aca810150d302129aa536ae9df128dad6c6f2b4a12e1873a9078fd999ce0
+  metadata.gz: b71c5cd92df55f4c28471df0920f19be7c4b81586d52c76e0704a2d1a605265a
+  data.tar.gz: 2dbe1f2b439949f7d7ed2cff08a2a51979e8c02cf1cd7c74c701f3de3a428e01
 SHA512:
-  metadata.gz: 83fc8408712d42dc29cf567659b9685c739aa5d5f4483fc8e02afd68624d0f4ea0d1aedbecb0d5bc52e015e119082e9a18cfad91701594988976b1d92de6d63d
-  data.tar.gz: c56040589ec68c2193df0117be65f6919b243a8c82c475096b813390a27050ea09e645fad54acafe63be85f1a4f343e0c51ac9fa597ba668f28c03a6432090de
+  metadata.gz: 2372a6936e06871d890e272e7c722b5dc59e4a2c2ac86e08e882479f3537f85ef3a66bf68b0a913a24029c300740183126437dda332934b975f9bc84fc64146e
+  data.tar.gz: fd02d5e014638c12695932361995443ad1f1c6a66aa104c0db360b931e55291cfca1a176aa2353a16267e73c3e651325a94c5ce4bb1f334b3ee4cdadb6ebc6ff

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-03-19
+
+### Added
+
+- `Perchfall.run!` — like `.run` but raises `PageLoadError` when the report is not ok. Use in scripts or jobs that should abort on any page failure.
+
+### Changed
+
+- `Perchfall.run` now always returns a `Report`, even when the page has unignored errors. Callers check `report.ok?` and handle failures themselves. This makes notification workflows possible without rescuing exceptions.
+
 ## [0.3.1] - 2026-03-19
 
 ### Changed
@@ -64,7 +74,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Full dependency injection throughout — test suite runs in ~0.4 s with no browser, Node, or network required
 - GitHub Actions CI workflow (unit suite) and manual Playwright smoke check workflow
 
-[Unreleased]: https://github.com/beflagrant/perchfall/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/beflagrant/perchfall/compare/v0.3.2...HEAD
+[0.3.2]: https://github.com/beflagrant/perchfall/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/beflagrant/perchfall/compare/v0.2.0...v0.3.1
 [0.2.0]: https://github.com/beflagrant/perchfall/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/beflagrant/perchfall/releases/tag/v0.1.0

data/lib/perchfall/client.rb

@@ -55,20 +55,36 @@ module Perchfall
     end
 
     # Run a synthetic browser check against the given URL.
+    # Always returns a Report — callers must check report.ok? to determine success.
     #
     # @param url [String] the URL to check (required, must be http or https)
     # @param timeout_ms [Integer] ms before Playwright gives up (default 30_000)
     # @param scenario_name [String, nil] optional label included in the report
     # @param timestamp [Time] override the run timestamp (default Time.now.utc)
-    # @return [Report] on success
+    # @return [Report]
     # @raise [ArgumentError] if the URL is not http/https
     # @raise [Errors::ConcurrencyLimitError] if the concurrency cap is reached
     # @raise [Errors::InvocationError] if Node could not be started
     # @raise [Errors::ScriptError] if the Node script exited non-zero
     # @raise [Errors::ParseError] if the script output was not valid JSON
-    # @raise [Errors::PageLoadError] if the page itself failed to load
+    def run(url:, **opts)
+      invoke(url: url, **opts)
+    end
+
+    # Like #run, but raises PageLoadError if the report is not ok.
+    # Use this in scripts or jobs that should abort on any page failure.
+    #
+    # @return [Report] only if report.ok?
+    # @raise [Errors::PageLoadError] if the page failed to load or has unignored errors
+    def run!(url:, **opts)
+      report = invoke(url: url, **opts)
+      raise Errors::PageLoadError.new(report) unless report.ok?
+      report
+    end
+
+    private
 
-    def run(url:, ignore: [], wait_until: "load", timeout_ms: 30_000, scenario_name: nil, timestamp: Time.now.utc, cache_profile: :query_bust)
+    def invoke(url:, ignore: [], wait_until: "load", timeout_ms: 30_000, scenario_name: nil, timestamp: Time.now.utc, cache_profile: :query_bust)
       profile = resolve_cache_profile!(cache_profile)
       validate_wait_until!(wait_until)
       validate_timeout_ms!(timeout_ms)

data/lib/perchfall/playwright_invoker.rb

@@ -27,9 +27,7 @@ module Perchfall
     def run(url:, timestamp:, timeout_ms: 30_000, wait_until: "load", scenario_name: nil, ignore: [], original_url: nil, extra_headers: {}, cache_profile: nil)
       parser = build_parser(ignore)
       result = execute(build_command(url: url, timeout_ms: timeout_ms, wait_until: wait_until, extra_headers: extra_headers))
-      report = parse(result, parser: parser, scenario_name: scenario_name, timestamp: timestamp, original_url: original_url || url, cache_profile: cache_profile)
-      raise_if_page_load_error(report)
-      report
+      parse(result, parser: parser, scenario_name: scenario_name, timestamp: timestamp, original_url: original_url || url, cache_profile: cache_profile)
     end
 
     private
@@ -62,8 +60,5 @@ module Perchfall
       parser.parse(result.stdout, **opts)
     end
 
-    def raise_if_page_load_error(report)
-      raise Errors::PageLoadError.new(report) unless report.ok?
-    end
   end
 end

data/lib/perchfall/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Perchfall
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

data/lib/perchfall.rb

@@ -43,9 +43,8 @@ module Perchfall
     @default_limiter ||= ConcurrencyLimiter.new(limit: 5)
   end
 
-  # Convenience method. Equivalent to Perchfall::Client.new.run(url:, **opts).
-  # Creates a fresh Client (and thus a fresh PlaywrightInvoker) on each call —
-  # no shared state between invocations.
+  # Returns a Report always — callers check report.ok? to determine success.
+  # Use this when you want to handle or notify on failures yourself.
   #
   # @param url [String]
   # @param opts [Hash] forwarded to Client#run
@@ -53,4 +52,15 @@ module Perchfall
   def self.run(url:, **opts)
     Client.new.run(url: url, **opts)
   end
+
+  # Like .run, but raises PageLoadError if the report is not ok.
+  # Use this in scripts or jobs that should abort on any page failure.
+  #
+  # @param url [String]
+  # @param opts [Hash] forwarded to Client#run!
+  # @return [Report] only if report.ok?
+  # @raise [Errors::PageLoadError]
+  def self.run!(url:, **opts)
+    Client.new.run!(url: url, **opts)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: perchfall
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Jim Remsik