High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat: add deterministic template-group sampling to audit runs
Luigi Agostif0704b27ffb2
diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.goindex c2bff8ef..a519bdfc 100644--- a/cmd/pinchtab/cmd_cli_register.go+++ b/cmd/pinchtab/cmd_cli_register.go@@ -356,7 +356,7 @@ func configureBrowserFlags() {errorsCmd.Flags().String("limit", "", "Maximum entries to return")auditCmd.Flags().Bool("sitemap", false, "Treat the URL as a sitemap.xml and audit the discovered pages")- auditCmd.Flags().Int("sample-size", 0, "Cap the number of audited pages (0 = no cap)")+ auditCmd.Flags().Int("sample-size", 0, "Pages audited per template group, e.g. /products/p1..pN (0 = all pages; deterministic picks)")auditCmd.Flags().Bool("screenshot", true, "Capture page screenshots")auditCmd.Flags().Bool("network-monitor", true, "Collect network requests and broken assets")auditCmd.Flags().String("output-dir", "", "Write report.json and screenshots/ to this directory")diff --git a/internal/audit/run.go b/internal/audit/run.goindex 2029a4af..ea8cb971 100644--- a/internal/audit/run.go+++ b/internal/audit/run.go@@ -18,8 +18,8 @@ const (// RunOptions configures a multi-page audit run.type RunOptions struct {- // SampleSize caps the number of audited pages, 0 = no cap. (Per-group- // sampling lands with page grouping; this is a plain truncation.)+ // SampleSize caps how many pages each template group contributes+ // (see SamplePages), 0 = no cap.SampleSize int// Concurrency is the number of pages audited in parallel, clamped to// [1, MaxConcurrency].@@ -102,10 +102,7 @@ func RunAudit(input AuditInput, opts RunOptions, discover SitemapFetcher, auditPurls = discovered}- plan := PlanURLs(urls)- if opts.SampleSize > 0 && len(plan) > opts.SampleSize {- plan = plan[:opts.SampleSize]- }+ plan := SamplePages(PlanURLs(urls), opts.SampleSize, nil)if len(plan) == 0 {return AuditReport{}, errors.New("no URLs to audit")}diff --git a/internal/audit/run_test.go b/internal/audit/run_test.goindex a346a646..9d0ca463 100644--- a/internal/audit/run_test.go+++ b/internal/audit/run_test.go@@ -176,7 +176,7 @@ func TestRunAuditSitemapMode(t *testing.T) {func TestRunAuditSampleSizeAndEmpty(t *testing.T) {auditor, _, _ := fakeAuditor()report, err := RunAudit(- AuditInput{URLs: []string{"http://x/1", "http://x/2", "http://x/3"}},+ AuditInput{URLs: []string{"http://x/p1.html", "http://x/p2.html", "http://x/p3.html"}},RunOptions{SampleSize: 2},nil, auditor,)@@ -184,7 +184,7 @@ func TestRunAuditSampleSizeAndEmpty(t *testing.T) {t.Fatalf("RunAudit: %v", err)}if len(report.Pages) != 2 {- t.Errorf("pages = %d, want 2 (sample size)", len(report.Pages))+ t.Errorf("pages = %d, want 2 (template group sampled)", len(report.Pages))}if _, err := RunAudit(AuditInput{}, RunOptions{}, nil, auditor); err == nil {diff --git a/internal/audit/sample.go b/internal/audit/sample.gonew file mode 100644index 00000000..b8afcf58--- /dev/null+++ b/internal/audit/sample.go@@ -0,0 +1,117 @@+package audit++import (+ "net/url"+ "regexp"+ "sort"+)++// PageGroup is a set of URLs sharing a path template. Groups with a single+// member are ordinary pages; only groups of two or more are treated as+// template groups by SamplePages.+type PageGroup struct {+ // Template is the digit-normalized URL template shared by the members.+ Template string+ // URLs are the member URLs in first-occurrence order.+ URLs []string+}++var digitRuns = regexp.MustCompile(`\d+`)++// templateKey normalizes a URL to its path template: scheme, host, and path+// with digit runs collapsed to '#'. Query and fragment are ignored, so+// /products/p1.html and /products/p2.html share one template.+func templateKey(raw string) string {+ u, err := url.Parse(raw)+ if err != nil || u.Host == "" {+ return digitRuns.ReplaceAllString(raw, "#")+ }+ return u.Scheme + "://" + u.Host + digitRuns.ReplaceAllString(u.Path, "#")+}++// GroupURLs groups URLs by path template, deterministically: groups appear+// in first-occurrence order and members keep input order.+func GroupURLs(urls []string) []PageGroup {+ index := map[string]int{}+ var groups []PageGroup+ for _, u := range urls {+ key := templateKey(u)+ i, ok := index[key]+ if !ok {+ i = len(groups)+ index[key] = i+ groups = append(groups, PageGroup{Template: key})+ }+ groups[i].URLs = append(groups[i].URLs, u)+ }+ return groups+}++// SamplePages reduces urls to a bounded, prioritized audit plan:+//+// - the entry URL (urls[0]) is always first+// - ungrouped pages (unique templates) are all kept, in input order+// - each template group (>= 2 members) contributes at most sampleSize+// pages, picked in lexical order for stability; an entry URL belonging+// to a group counts toward its quota+// - template-group pages come after ungrouped pages (homepage and nav+// pages ahead of deep template pages)+//+// sampleSize <= 0 keeps every page (prioritized ordering still applies).+// groups may be supplied externally (e.g. from a SeaPortal SiteReport); nil+// computes them locally from URL structure. Fully deterministic: identical+// inputs always yield the identical plan.+func SamplePages(urls []string, sampleSize int, groups []PageGroup) []string {+ if len(urls) == 0 {+ return nil+ }+ if groups == nil {+ groups = GroupURLs(urls)+ }++ groupOf := map[string]string{}+ for _, g := range groups {+ if len(g.URLs) < 2 {+ continue+ }+ for _, u := range g.URLs {+ groupOf[u] = g.Template+ }+ }++ entry := urls[0]+ plan := []string{entry}+ seen := map[string]bool{entry: true}+ picked := map[string]int{}+ if t, ok := groupOf[entry]; ok {+ picked[t] = 1+ }++ for _, u := range urls {+ if seen[u] || groupOf[u] != "" {+ continue+ }+ seen[u] = true+ plan = append(plan, u)+ }++ for _, g := range groups {+ if len(g.URLs) < 2 {+ continue+ }+ members := append([]string(nil), g.URLs...)+ sort.Strings(members)+ for _, u := range members {+ if sampleSize > 0 && picked[g.Template] >= sampleSize {+ break+ }+ if seen[u] {+ continue+ }+ seen[u] = true+ plan = append(plan, u)+ picked[g.Template]+++ }+ }+ return plan+}diff --git a/internal/audit/sample_test.go b/internal/audit/sample_test.gonew file mode 100644index 00000000..2dfcd445--- /dev/null+++ b/internal/audit/sample_test.go@@ -0,0 +1,133 @@+package audit++import (+ "reflect"+ "testing"+)++var fixtureSiteURLs = []string{+ "http://fixtures/audit-site/index.html",+ "http://fixtures/audit-site/broken-assets.html",+ "http://fixtures/audit-site/console-errors.html",+ "http://fixtures/audit-site/a11y-issues.html",+ "http://fixtures/audit-site/clean.html",+ "http://fixtures/audit-site/forms.html",+ "http://fixtures/audit-site/cookie-echo.html",+ "http://fixtures/audit-site/products/p1.html",+ "http://fixtures/audit-site/products/p2.html",+ "http://fixtures/audit-site/products/p3.html",+ "http://fixtures/audit-site/products/p4.html",+ "http://fixtures/audit-site/products/p5.html",+}++func TestGroupURLsCollapsesProductTemplates(t *testing.T) {+ groups := GroupURLs(fixtureSiteURLs)++ var products *PageGroup+ multi := 0+ for i := range groups {+ if len(groups[i].URLs) >= 2 {+ multi+++ products = &groups[i]+ }+ }+ if multi != 1 {+ t.Fatalf("template groups = %d, want 1 (products only)", multi)+ }+ if len(products.URLs) != 5 {+ t.Errorf("products group size = %d, want 5", len(products.URLs))+ }+ if products.Template != "http://fixtures/audit-site/products/p#.html" {+ t.Errorf("products template = %q", products.Template)+ }+}++func TestGroupURLsKeepsDistinctPagesApart(t *testing.T) {+ groups := GroupURLs([]string{+ "http://x/index.html",+ "http://x/clean.html",+ "http://x/forms.html",+ })+ if len(groups) != 3 {+ t.Errorf("groups = %d, want 3 distinct (letters differ, not digits)", len(groups))+ }+}++func TestSamplePagesDeterministicPicks(t *testing.T) {+ first := SamplePages(fixtureSiteURLs, 2, nil)+ for range 10 {+ if again := SamplePages(fixtureSiteURLs, 2, nil); !reflect.DeepEqual(first, again) {+ t.Fatalf("sampling not deterministic:\n%v\n%v", first, again)+ }+ }++ products := 0+ for _, u := range first {+ if u == "http://fixtures/audit-site/products/p1.html" || u == "http://fixtures/audit-site/products/p2.html" {+ products+++ }+ }+ if products != 2 {+ t.Errorf("expected the 2 lexically-first product pages, got plan %v", first)+ }+ if len(first) != 9 {+ t.Errorf("plan size = %d, want 9 (7 non-group + 2 sampled)", len(first))+ }+}++func TestSamplePagesHomepageFirst(t *testing.T) {+ plan := SamplePages(fixtureSiteURLs, 2, nil)+ if plan[0] != "http://fixtures/audit-site/index.html" {+ t.Errorf("plan[0] = %q, want homepage", plan[0])+ }++ shuffled := []string{+ "http://fixtures/audit-site/products/p3.html",+ "http://fixtures/audit-site/index.html",+ "http://fixtures/audit-site/products/p1.html",+ }+ plan = SamplePages(shuffled, 1, nil)+ if plan[0] != "http://fixtures/audit-site/products/p3.html" {+ t.Errorf("entry URL must stay first even when grouped, got %v", plan)+ }+ if len(plan) != 2 {+ t.Errorf("plan = %v, want entry + index (entry fills the group quota)", plan)+ }+}++func TestSamplePagesTemplatePagesLast(t *testing.T) {+ plan := SamplePages(fixtureSiteURLs, 2, nil)+ sawProduct := false+ for _, u := range plan[1:] {+ isProduct := templateKey(u) == "http://fixtures/audit-site/products/p#.html"+ if sawProduct && !isProduct {+ t.Errorf("ungrouped page %q after template pages: %v", u, plan)+ }+ if isProduct {+ sawProduct = true+ }+ }+}++func TestSamplePagesNoCapKeepsAll(t *testing.T) {+ plan := SamplePages(fixtureSiteURLs, 0, nil)+ if len(plan) != len(fixtureSiteURLs) {+ t.Errorf("plan size = %d, want %d (no cap)", len(plan), len(fixtureSiteURLs))+ }+}++func TestSamplePagesExternalGroups(t *testing.T) {+ urls := []string{"http://x/home", "http://x/shoes", "http://x/hats"}+ external := []PageGroup{{Template: "catalog", URLs: []string{"http://x/shoes", "http://x/hats"}}}+ plan := SamplePages(urls, 1, external)+ want := []string{"http://x/home", "http://x/hats"}+ if !reflect.DeepEqual(plan, want) {+ t.Errorf("plan = %v, want %v (external group sampled)", plan, want)+ }+}++func TestSamplePagesEmpty(t *testing.T) {+ if plan := SamplePages(nil, 2, nil); plan != nil {+ t.Errorf("SamplePages(nil) = %v", plan)+ }+}diff --git a/tests/e2e/scenarios/api/audit-sampling-extended.sh b/tests/e2e/scenarios/api/audit-sampling-extended.shnew file mode 100755index 00000000..faf93484--- /dev/null+++ b/tests/e2e/scenarios/api/audit-sampling-extended.sh@@ -0,0 +1,51 @@+#!/bin/bash+# audit-sampling-extended.sh — POST /audit template-group sampling.++GROUP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+source "${GROUP_DIR}/../../helpers/api.sh"++SAMPLING_BODY="{\"sitemapUrl\":\"${FIXTURES_URL}/audit-site/sitemap.xml\",\"sampleSize\":2,\"options\":{\"screenshot\":false}}"++# ─────────────────────────────────────────────────────────────────+start_test "sampleSize=2 keeps all non-group pages plus 2 products"++pt_post /audit -d "$SAMPLING_BODY"+assert_ok "sampled sitemap audit"++assert_json_length "$RESULT" '.pages' 9 "9 pages (7 non-group + 2 sampled products)"++PRODUCT_COUNT=$(echo "$RESULT" | jq '[.pages[].url | select(contains("products/"))] | length')+if [ "$PRODUCT_COUNT" -eq 2 ]; then+ pass_assert "exactly 2 products/* pages"+else+ fail_assert "exactly 2 products/* pages (got: $PRODUCT_COUNT)"+fi++for page in index.html broken-assets.html console-errors.html a11y-issues.html clean.html forms.html cookie-echo.html; do+ if echo "$RESULT" | jq -e --arg page "$page" '.pages[] | select(.url | endswith($page))' >/dev/null 2>&1; then+ pass_assert "non-group page $page present"+ else+ fail_assert "non-group page $page present"+ fi+done++assert_json_contains "$RESULT" '.pages[0].url' "index.html" "homepage first in page order"++end_test++# ─────────────────────────────────────────────────────────────────+start_test "sampling is reproducible across runs"++FIRST_SET=$(echo "$RESULT" | jq -S '[.pages[].url] | sort')++pt_post /audit -d "$SAMPLING_BODY"+assert_ok "second sampled audit"+SECOND_SET=$(echo "$RESULT" | jq -S '[.pages[].url] | sort')++if [ "$FIRST_SET" = "$SECOND_SET" ]; then+ pass_assert "identical page URL set across runs"+else+ fail_assert "URL sets differ: $FIRST_SET vs $SECOND_SET"+fi++end_test