perchfall 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b71c5cd92df55f4c28471df0920f19be7c4b81586d52c76e0704a2d1a605265a
-  data.tar.gz: 2dbe1f2b439949f7d7ed2cff08a2a51979e8c02cf1cd7c74c701f3de3a428e01
+  metadata.gz: 7d608f361607d90f51b79aee9aab5c4585dfbc3c5f5a7556c60eef9154588664
+  data.tar.gz: 17a9717ef25c6c5e81a38fa8a255730013320d38aa5636f15b60d4ed15252297
 SHA512:
-  metadata.gz: 2372a6936e06871d890e272e7c722b5dc59e4a2c2ac86e08e882479f3537f85ef3a66bf68b0a913a24029c300740183126437dda332934b975f9bc84fc64146e
-  data.tar.gz: fd02d5e014638c12695932361995443ad1f1c6a66aa104c0db360b931e55291cfca1a176aa2353a16267e73c3e651325a94c5ce4bb1f334b3ee4cdadb6ebc6ff
+  metadata.gz: febd8246e1b5560784ab0530a50191d274697d863e50b73409e18acadd762fff8669a67b8b35894bf3f31ec386509c6f61e63b9ce1c9b74fda59fe3f0cfdb19b
+  data.tar.gz: cc4a837fe3f82be4686854348d556e60b362d7336c0f5f2277d8e3c4edad42f994234484c64b588b12d7ff6da90ce48448200edd73b33865d35a7f3a07ab35b9

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-03-27
+
+### Added
+
+- `capture_resources: false` option on `Perchfall.run` / `Client#run` — when `true`, collects metadata for every resource loaded during the page run and stores large ones on the report
+- `report.resources` — array of `Resource` objects (url, http_method, status, content_type, transfer_size, resource_type) whose transfer size met or exceeded the configured threshold, plus any resource whose size could not be determined (absent `content-length`)
+- `large_resource_threshold_bytes:` option (default 200 000 bytes / 200 KB) — controls the minimum transfer size for a resource to appear in `report.resources`; only meaningful when `capture_resources: true`
+- `Perchfall::Resource` value object (`Data.define`) with all resource fields; `transfer_size` is `Integer` or `nil` (nil means unknown, not zero)
+
+### Notes
+
+- Resource capture is opt-in and off by default. No overhead is incurred unless `capture_resources: true` is passed.
+- Resources with an unknown transfer size (`nil`) are always included in `report.resources` — they cannot be proven to be below the threshold.
+- `report.ok?` is not affected by `report.resources` — size is a metric, not a pass/fail signal.
+
 ## [0.3.2] - 2026-03-19
 
 ### Added
@@ -74,7 +89,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.2...HEAD
+[Unreleased]: https://github.com/beflagrant/perchfall/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/beflagrant/perchfall/compare/v0.3.2...v0.4.0
 [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

data/lib/perchfall/client.rb

@@ -82,29 +82,49 @@ module Perchfall
       report
     end
 
+    DEFAULT_RESOURCE_THRESHOLD = Parsers::PlaywrightJsonParser::DEFAULT_LARGE_RESOURCE_THRESHOLD_BYTES
+
+    RunOptions = Data.define(
+      :url, :ignore, :wait_until, :timeout_ms, :scenario_name,
+      :timestamp, :cache_profile, :capture_resources, :large_resource_threshold_bytes
+    ) do
+      def self.from_kwargs(url:, ignore: [], wait_until: 'load', timeout_ms: 30_000,
+                           scenario_name: nil, timestamp: Time.now.utc,
+                           cache_profile: :query_bust, capture_resources: false,
+                           large_resource_threshold_bytes: DEFAULT_RESOURCE_THRESHOLD)
+        new(url: url, ignore: ignore, wait_until: wait_until, timeout_ms: timeout_ms,
+            scenario_name: scenario_name, timestamp: timestamp, cache_profile: cache_profile,
+            capture_resources: capture_resources,
+            large_resource_threshold_bytes: large_resource_threshold_bytes)
+      end
+    end
+
     private
 
-    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)
-      effective_url = profile[:bust_url] ? append_cache_buster(url) : url
+    def invoke(url:, **kwargs)
+      opts    = RunOptions.from_kwargs(url: url, **kwargs)
+      profile = resolve_cache_profile!(opts.cache_profile)
+      validate_wait_until!(opts.wait_until)
+      validate_timeout_ms!(opts.timeout_ms)
+      effective_url = profile[:bust_url] ? append_cache_buster(opts.url) : opts.url
       @validator.validate!(effective_url)
-      merged_ignore = Perchfall::DEFAULT_IGNORE_RULES + ignore
-      invoker_opts  = {
-        url:           effective_url,
-        original_url:  url,
-        ignore:        merged_ignore,
-        wait_until:    wait_until,
-        timeout_ms:    timeout_ms,
-        scenario_name: scenario_name,
-        timestamp:     timestamp,
-        cache_profile: cache_profile
+      @limiter.acquire { @invoker.run(**build_invoker_opts(opts, effective_url, profile)) }
+    end
+
+    def build_invoker_opts(opts, effective_url, profile)
+      result = {
+        url: effective_url, original_url: opts.url,
+        ignore: Perchfall::DEFAULT_IGNORE_RULES + opts.ignore,
+        wait_until: opts.wait_until, timeout_ms: opts.timeout_ms,
+        scenario_name: opts.scenario_name, timestamp: opts.timestamp,
+        cache_profile: opts.cache_profile
       }
-      invoker_opts[:extra_headers] = profile[:headers] unless profile[:headers].empty?
-      @limiter.acquire do
-        @invoker.run(**invoker_opts)
+      result[:extra_headers] = profile[:headers] unless profile[:headers].empty?
+      if opts.capture_resources
+        result[:capture_resources]              = true
+        result[:large_resource_threshold_bytes] = opts.large_resource_threshold_bytes
       end
+      result
     end
 
     private

data/lib/perchfall/parsers/playwright_json_parser.rb

@@ -13,16 +13,18 @@ module Perchfall
         @filter = filter
       end
 
-      def parse(raw_json, timestamp:, scenario_name: nil, original_url: nil, cache_profile: nil)
+      DEFAULT_LARGE_RESOURCE_THRESHOLD_BYTES = 200_000
+
+      def parse(raw_json, timestamp:, scenario_name: nil, original_url: nil, cache_profile: nil, capture_resources: false, large_resource_threshold_bytes: DEFAULT_LARGE_RESOURCE_THRESHOLD_BYTES)
         data = JSON.parse(raw_json, symbolize_names: true)
-        build_report(data, scenario_name: scenario_name, timestamp: timestamp, original_url: original_url, cache_profile: cache_profile)
+        build_report(data, scenario_name: scenario_name, timestamp: timestamp, original_url: original_url, cache_profile: cache_profile, capture_resources: capture_resources, large_resource_threshold_bytes: large_resource_threshold_bytes)
       rescue JSON::ParserError => e
         raise Errors::ParseError, "Invalid JSON from Playwright script: #{e.message}"
       end
 
       private
 
-      def build_report(data, scenario_name:, timestamp:, original_url: nil, cache_profile: nil)
+      def build_report(data, scenario_name:, timestamp:, original_url: nil, cache_profile: nil, capture_resources: false, large_resource_threshold_bytes: DEFAULT_LARGE_RESOURCE_THRESHOLD_BYTES)
         net_filtered     = @filter.filter_network(parse_network_errors(data.fetch(:network_errors, [])))
         console_filtered = @filter.filter_console(parse_console_errors(data.fetch(:console_errors, [])))
 
@@ -38,7 +40,8 @@ module Perchfall
           error:                  data[:error],
           scenario_name:          scenario_name,
           timestamp:              timestamp,
-          cache_profile:          cache_profile
+          cache_profile:          cache_profile,
+          resources:              capture_resources ? parse_resources(data.fetch(:resources, []), threshold_bytes: large_resource_threshold_bytes) : []
         )
       rescue KeyError => e
         raise Errors::ParseError, "Playwright JSON missing required field: #{e.message}"
@@ -67,6 +70,21 @@ module Perchfall
       rescue KeyError => e
         raise Errors::ParseError, "Malformed console_error entry: #{e.message}"
       end
+
+      def parse_resources(raw, threshold_bytes:)
+        raw.filter_map do |item|
+          size = item[:transfer_size]
+          next if size && size < threshold_bytes
+          Resource.new(
+            url:           item[:url],
+            http_method:   item[:method],
+            status:        item[:status],
+            content_type:  item[:content_type],
+            transfer_size: size,
+            resource_type: item[:resource_type]
+          )
+        end
+      end
     end
   end
 end

data/lib/perchfall/playwright_invoker.rb

@@ -24,10 +24,10 @@ module Perchfall
       @script_path = script_path
     end
 
-    def run(url:, timestamp:, timeout_ms: 30_000, wait_until: "load", scenario_name: nil, ignore: [], original_url: nil, extra_headers: {}, cache_profile: nil)
+    def run(url:, timestamp:, timeout_ms: 30_000, wait_until: "load", scenario_name: nil, ignore: [], original_url: nil, extra_headers: {}, cache_profile: nil, capture_resources: false, large_resource_threshold_bytes: Parsers::PlaywrightJsonParser::DEFAULT_LARGE_RESOURCE_THRESHOLD_BYTES)
       parser = build_parser(ignore)
-      result = execute(build_command(url: url, timeout_ms: timeout_ms, wait_until: wait_until, extra_headers: extra_headers))
-      parse(result, parser: parser, scenario_name: scenario_name, timestamp: timestamp, original_url: original_url || url, cache_profile: cache_profile)
+      result = execute(build_command(url: url, timeout_ms: timeout_ms, wait_until: wait_until, extra_headers: extra_headers, capture_resources: capture_resources))
+      parse(result, parser: parser, scenario_name: scenario_name, timestamp: timestamp, original_url: original_url || url, cache_profile: cache_profile, capture_resources: capture_resources, large_resource_threshold_bytes: large_resource_threshold_bytes)
     end
 
     private
@@ -36,9 +36,10 @@ module Perchfall
       Parsers::PlaywrightJsonParser.new(filter: ErrorFilter.new(rules: ignore_rules))
     end
 
-    def build_command(url:, timeout_ms:, wait_until:, extra_headers: {})
+    def build_command(url:, timeout_ms:, wait_until:, extra_headers: {}, capture_resources: false)
       cmd = ["node", @script_path, "--url", url, "--timeout", timeout_ms.to_s, "--wait-until", wait_until]
       cmd += ["--headers", extra_headers.to_json] unless extra_headers.empty?
+      cmd += ["--capture-resources"] if capture_resources
       cmd
     end
 
@@ -57,7 +58,7 @@ module Perchfall
         )
       end
 
-      parser.parse(result.stdout, **opts)
+      parser.parse(result.stdout, timestamp: opts[:timestamp], scenario_name: opts[:scenario_name], original_url: opts[:original_url], cache_profile: opts[:cache_profile], capture_resources: opts[:capture_resources] || false, large_resource_threshold_bytes: opts[:large_resource_threshold_bytes] || Parsers::PlaywrightJsonParser::DEFAULT_LARGE_RESOURCE_THRESHOLD_BYTES)
     end
 
   end

data/lib/perchfall/report.rb

@@ -18,10 +18,13 @@ module Perchfall
   #   ignored_console_errors - Array<ConsoleError>: errors suppressed by ignore rules
   #   error                  - String or nil: set only when status == "error"
   #   cache_profile          - Symbol or nil: the cache profile used for this run
+  #   resources              - Array<Resource>: resources that exceeded the configured size
+  #                            threshold; only populated when capture_resources: true was passed
   class Report
     attr_reader :status, :url, :scenario_name, :timestamp, :duration_ms,
                 :http_status, :network_errors, :ignored_network_errors,
-                :console_errors, :ignored_console_errors, :error, :cache_profile
+                :console_errors, :ignored_console_errors, :error, :cache_profile,
+                :resources
 
     def initialize(
       status:,
@@ -35,7 +38,8 @@ module Perchfall
       ignored_console_errors: [],
       scenario_name: nil,
       timestamp: Time.now.utc,
-      cache_profile: nil
+      cache_profile: nil,
+      resources: []
     )
       @status                 = status.freeze
       @url                    = url.freeze
@@ -49,6 +53,7 @@ module Perchfall
       @ignored_console_errors = ignored_console_errors.freeze
       @error                  = error&.freeze
       @cache_profile          = cache_profile
+      @resources              = resources.freeze
       freeze
     end
 
@@ -70,7 +75,8 @@ module Perchfall
         console_errors:         console_errors.map(&:to_h),
         ignored_console_errors: ignored_console_errors.map(&:to_h),
         error:          error,
-        cache_profile:  cache_profile
+        cache_profile:  cache_profile,
+        resources:      resources.map(&:to_h)
       }
     end
 

data/lib/perchfall/resource.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Perchfall
+  # Represents a single resource loaded during a page run.
+  #
+  # Attributes:
+  #   url           - String: the resource URL
+  #   http_method   - String: HTTP method (e.g. "GET")
+  #   status        - Integer: HTTP response status code
+  #   content_type  - String or nil: Content-Type header value
+  #   transfer_size - Integer or nil: wire bytes from Content-Length header;
+  #                   nil means the header was absent (chunked/inline) — unknown, not zero
+  #   resource_type - String: Playwright resource type (e.g. "image", "script", "stylesheet")
+  Resource = Data.define(:url, :http_method, :status, :content_type, :transfer_size, :resource_type)
+end

data/lib/perchfall/version.rb

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

data/lib/perchfall.rb

@@ -10,6 +10,7 @@ require_relative "perchfall/error_filter"
 require_relative "perchfall/command_runner"
 require_relative "perchfall/concurrency_limiter"
 require_relative "perchfall/url_validator"
+require_relative "perchfall/resource"
 require_relative "perchfall/parsers/playwright_json_parser"
 require_relative "perchfall/playwright_invoker"
 require_relative "perchfall/client"

data/playwright/check.js

@@ -20,10 +20,11 @@ const { parseArgs } = require("node:util");
 
 const { values: args } = parseArgs({
   options: {
-    url:        { type: "string" },
-    timeout:    { type: "string", default: "30000" },
-    "wait-until": { type: "string", default: "load" },
-    headers:    { type: "string", default: "{}" },
+    url:                { type: "string" },
+    timeout:            { type: "string", default: "30000" },
+    "wait-until":       { type: "string", default: "load" },
+    headers:            { type: "string", default: "{}" },
+    "capture-resources": { type: "boolean", default: false },
   },
   strict: true,
 });
@@ -33,9 +34,10 @@ if (!args.url) {
   process.exit(1);
 }
 
-const TARGET_URL = args.url;
-const TIMEOUT_MS = parseInt(args.timeout, 10);
-const WAIT_UNTIL = args["wait-until"];
+const TARGET_URL       = args.url;
+const TIMEOUT_MS       = parseInt(args.timeout, 10);
+const WAIT_UNTIL       = args["wait-until"];
+const CAPTURE_RESOURCES = args["capture-resources"];
 
 let EXTRA_HEADERS;
 try {
@@ -66,8 +68,8 @@ try {
 // Helpers
 // ---------------------------------------------------------------------------
 
-function buildResult({ status, durationMs, httpStatus, networkErrors, consoleErrors, error }) {
-  return JSON.stringify({
+function buildResult({ status, durationMs, httpStatus, networkErrors, consoleErrors, resources, error }) {
+  const result = {
     status,
     url:            TARGET_URL,
     duration_ms:    durationMs,
@@ -75,7 +77,25 @@ function buildResult({ status, durationMs, httpStatus, networkErrors, consoleErr
     network_errors: networkErrors,
     console_errors: consoleErrors,
     error:          error ?? null,
-  });
+  };
+  if (resources !== undefined) result.resources = resources;
+  return JSON.stringify(result);
+}
+
+async function resolveResources(pending) {
+  if (pending === null) return undefined;
+  return Promise.all(pending.map(async (res) => {
+    const headers   = await res.allHeaders();
+    const rawLength = headers["content-length"];
+    return {
+      url:           res.url(),
+      method:        res.request().method(),
+      status:        res.status(),
+      content_type:  headers["content-type"] ?? null,
+      transfer_size: rawLength != null ? parseInt(rawLength, 10) : null,
+      resource_type: res.request().resourceType(),
+    };
+  }));
 }
 
 // ---------------------------------------------------------------------------
@@ -86,6 +106,7 @@ async function run() {
   const startedAt      = Date.now();
   const networkErrors  = [];
   const consoleErrors  = [];
+  const pendingResources = CAPTURE_RESOURCES ? [] : null;
   let   browser;
 
   try {
@@ -106,6 +127,7 @@ async function run() {
     });
 
     // Collect non-2xx/3xx responses as network errors too.
+    // When resource capture is enabled, stash every response for later processing.
     page.on("response", (response) => {
       const status = response.status();
       if (status >= 400) {
@@ -115,6 +137,9 @@ async function run() {
           failure: `HTTP ${status}`,
         });
       }
+      if (pendingResources !== null) {
+        pendingResources.push(response);
+      }
     });
 
     // Collect browser console errors.
@@ -135,6 +160,7 @@ async function run() {
     });
 
     const durationMs = Date.now() - startedAt;
+    const resources  = await resolveResources(pendingResources);
 
     process.stdout.write(buildResult({
       status:        "ok",
@@ -142,6 +168,7 @@ async function run() {
       httpStatus:    response ? response.status() : null,
       networkErrors,
       consoleErrors,
+      resources,
       error:         null,
     }));
 
@@ -150,6 +177,7 @@ async function run() {
   } catch (err) {
     // Page-level failure (timeout, DNS, etc.) — exit 0 so Ruby reads the JSON.
     const durationMs = Date.now() - startedAt;
+    const resources  = await resolveResources(pendingResources);
 
     process.stdout.write(buildResult({
       status:        "error",
@@ -157,6 +185,7 @@ async function run() {
       httpStatus:    null,
       networkErrors,
       consoleErrors,
+      resources,
       error:         err.message,
     }));
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: perchfall
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Jim Remsik
@@ -89,6 +89,7 @@ files:
 - lib/perchfall/parsers/playwright_json_parser.rb
 - lib/perchfall/playwright_invoker.rb
 - lib/perchfall/report.rb
+- lib/perchfall/resource.rb
 - lib/perchfall/url_validator.rb
 - lib/perchfall/version.rb
 - perchfall.gemspec