Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

feat: add pinchtab audit command and multi-page POST /audit runner

Luigi Agosti58d96c498476
diff --git a/cmd/pinchtab/cmd_audit.go b/cmd/pinchtab/cmd_audit.go
new file mode 100644
index 00000000..b030db50
--- /dev/null
+++ b/cmd/pinchtab/cmd_audit.go
@@ -0,0 +1,28 @@
+package main
+
+import (
+ browseractions "github.com/pinchtab/pinchtab/internal/cli/actions"
+ "github.com/spf13/cobra"
+)
+
+var auditCmd = &cobra.Command{
+ Use: "audit <url>",
+ Short: "Run a browser-level site audit",
+ Long: `Audit one or more pages with full browser enrichment: screenshots,
+console logs, network requests and broken assets, interactive elements,
+accessibility score, and timing metrics.
+
+The argument is a page URL, or a sitemap URL with --sitemap (pages are then
+discovered from it). With --output-dir the report is written to
+<dir>/report.json and screenshots to <dir>/screenshots/; --json prints the
+full report to stdout.
+
+Pages that fail to load do not fail the run: the command still exits 0 and
+the failing page's report entry carries an "error" field.`,
+ Args: cobra.ExactArgs(1),
+ Run: func(cmd *cobra.Command, args []string) {
+ runCLI(func(rt cliRuntime) {
+ browseractions.Audit(rt.client, rt.base, rt.token, cmd, args[0])
+ })
+ },
+}
diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.go
index c24ec6b7..c2bff8ef 100644
--- a/cmd/pinchtab/cmd_cli_register.go
+++ b/cmd/pinchtab/cmd_cli_register.go
@@ -25,7 +25,7 @@ func browserRootCommands() []*cobra.Command {
downloadCmd, uploadCmd, findCmd, selectCmd, checkCmd, uncheckCmd, networkCmd, waitCmd,
keyboardCmd, keydownCmd, keyupCmd, scrollintoviewCmd, dialogCmd, consoleCmd, errorsCmd,
clipboardCmd, cacheCmd, cookiesCmd, setCmd, storageCmd, stateCmd, closeCmd, handoffCmd,
- resumeCmd, handoffStatusCmd, recordCmd,
+ resumeCmd, handoffStatusCmd, recordCmd, auditCmd,
}
}
@@ -355,6 +355,14 @@ func configureBrowserFlags() {
errorsCmd.Flags().Bool("clear", false, "Clear error logs")
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().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")
+ auditCmd.Flags().Int("concurrency", 0, "Pages audited in parallel (default 2, max 8)")
+ auditCmd.Flags().Bool("json", false, "Print the full report JSON to stdout")
+
addTabFlag(consoleCmd, errorsCmd)
}
diff --git a/internal/audit/run.go b/internal/audit/run.go
new file mode 100644
index 00000000..2029a4af
--- /dev/null
+++ b/internal/audit/run.go
@@ -0,0 +1,173 @@
+package audit
+
+import (
+ "encoding/xml"
+ "errors"
+ "fmt"
+ "sync"
+ "time"
+)
+
+// DefaultConcurrency is the number of pages audited in parallel when the
+// caller does not choose one; MaxConcurrency caps what a caller may request
+// (each worker drives its own browser tab).
+const (
+ DefaultConcurrency = 2
+ MaxConcurrency = 8
+)
+
+// 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 int
+ // Concurrency is the number of pages audited in parallel, clamped to
+ // [1, MaxConcurrency].
+ Concurrency int
+ // Page selects the collectors for every page.
+ Page PageOptions
+}
+
+// SitemapFetcher discovers page URLs from a sitemap URL. Isolated behind a
+// function type so a richer discovery (e.g. seaportal.FlattenSitemap) can be
+// swapped in.
+type SitemapFetcher func(sitemapURL string) ([]string, error)
+
+// PageAuditor audits a single URL. Failures must come back as a PageAudit
+// with the Error field set, never as a panic.
+type PageAuditor func(url string, opts PageOptions) PageAudit
+
+// PlanURLs dedupes the URL list preserving first-occurrence order, so the
+// entry URL stays first. Empty strings are dropped.
+func PlanURLs(urls []string) []string {
+ seen := make(map[string]bool, len(urls))
+ plan := make([]string, 0, len(urls))
+ for _, u := range urls {
+ if u == "" || seen[u] {
+ continue
+ }
+ seen[u] = true
+ plan = append(plan, u)
+ }
+ return plan
+}
+
+type sitemapURLSet struct {
+ URLs []struct {
+ Loc string `xml:"loc"`
+ } `xml:"url"`
+}
+
+// ParseSitemap extracts the <loc> URLs from a sitemap.xml document.
+func ParseSitemap(data []byte) ([]string, error) {
+ var set sitemapURLSet
+ if err := xml.Unmarshal(data, &set); err != nil {
+ return nil, fmt.Errorf("parse sitemap: %w", err)
+ }
+ urls := make([]string, 0, len(set.URLs))
+ for _, u := range set.URLs {
+ if u.Loc != "" {
+ urls = append(urls, u.Loc)
+ }
+ }
+ return urls, nil
+}
+
+// clampConcurrency normalizes a requested concurrency into [1, MaxConcurrency].
+func clampConcurrency(n int) int {
+ switch {
+ case n < 1:
+ return DefaultConcurrency
+ case n > MaxConcurrency:
+ return MaxConcurrency
+ default:
+ return n
+ }
+}
+
+// RunAudit audits every planned URL and assembles the versioned AuditReport.
+// The entry URL (first in the plan) is always audited first, synchronously;
+// the rest run with bounded concurrency. Page failures are report data, not
+// errors — RunAudit only errors when there is nothing to audit.
+func RunAudit(input AuditInput, opts RunOptions, discover SitemapFetcher, auditPage PageAuditor) (AuditReport, error) {
+ urls := input.URLs
+ if len(urls) == 0 && input.SitemapURL != "" {
+ if discover == nil {
+ return AuditReport{}, errors.New("sitemap input requires a sitemap fetcher")
+ }
+ discovered, err := discover(input.SitemapURL)
+ if err != nil {
+ return AuditReport{}, fmt.Errorf("sitemap discovery: %w", err)
+ }
+ urls = discovered
+ }
+
+ plan := PlanURLs(urls)
+ if opts.SampleSize > 0 && len(plan) > opts.SampleSize {
+ plan = plan[:opts.SampleSize]
+ }
+ if len(plan) == 0 {
+ return AuditReport{}, errors.New("no URLs to audit")
+ }
+
+ concurrency := clampConcurrency(opts.Concurrency)
+ results := make([]PageAudit, len(plan))
+ results[0] = auditPage(plan[0], opts.Page)
+
+ sem := make(chan struct{}, concurrency)
+ var wg sync.WaitGroup
+ for i := 1; i < len(plan); i++ {
+ wg.Add(1)
+ go func(i int) {
+ defer wg.Done()
+ sem <- struct{}{}
+ defer func() { <-sem }()
+ results[i] = auditPage(plan[i], opts.Page)
+ }(i)
+ }
+ wg.Wait()
+
+ report := NewAuditReport()
+ report.GeneratedAt = time.Now().UTC()
+ report.Input = input
+ report.Options = AuditOptions{
+ SampleSize: opts.SampleSize,
+ Screenshot: opts.Page.Screenshot,
+ NetworkMonitor: opts.Page.Network,
+ Concurrency: concurrency,
+ }
+ report.Pages = make([]PageResult, len(results))
+ for i, pa := range results {
+ report.Pages[i] = pa.ToPageResult()
+ }
+ report.SummaryScore = summaryScore(results)
+ return report, nil
+}
+
+// ToPageResult converts a single-page audit into the report page shape.
+func (pa PageAudit) ToPageResult() PageResult {
+ return PageResult{
+ URL: pa.URL,
+ Title: pa.Title,
+ Error: pa.Error,
+ Screenshot: pa.Screenshot,
+ Browser: pa.BrowserPageData,
+ }
+}
+
+// summaryScore is the mean accessibility score across pages that were
+// audited without error, 0 when none were.
+func summaryScore(results []PageAudit) int {
+ sum, n := 0, 0
+ for _, pa := range results {
+ if pa.Error != "" {
+ continue
+ }
+ sum += pa.AccessibilityScore
+ n++
+ }
+ if n == 0 {
+ return 0
+ }
+ return sum / n
+}
diff --git a/internal/audit/run_test.go b/internal/audit/run_test.go
new file mode 100644
index 00000000..a346a646
--- /dev/null
+++ b/internal/audit/run_test.go
@@ -0,0 +1,216 @@
+package audit
+
+import (
+ "errors"
+ "reflect"
+ "sync"
+ "sync/atomic"
+ "testing"
+)
+
+func TestPlanURLs(t *testing.T) {
+ got := PlanURLs([]string{"a", "b", "a", "", "c", "b"})
+ want := []string{"a", "b", "c"}
+ if !reflect.DeepEqual(got, want) {
+ t.Errorf("PlanURLs = %v, want %v", got, want)
+ }
+ if got := PlanURLs(nil); len(got) != 0 {
+ t.Errorf("PlanURLs(nil) = %v", got)
+ }
+}
+
+func TestParseSitemap(t *testing.T) {
+ data := []byte(`<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+ <url><loc>http://fixtures/a.html</loc></url>
+ <url><loc>http://fixtures/b.html</loc></url>
+ <url><loc></loc></url>
+</urlset>`)
+ got, err := ParseSitemap(data)
+ if err != nil {
+ t.Fatalf("ParseSitemap: %v", err)
+ }
+ want := []string{"http://fixtures/a.html", "http://fixtures/b.html"}
+ if !reflect.DeepEqual(got, want) {
+ t.Errorf("ParseSitemap = %v, want %v", got, want)
+ }
+
+ if _, err := ParseSitemap([]byte("not xml at all <")); err == nil {
+ t.Error("ParseSitemap should error on malformed XML")
+ }
+}
+
+func fakeAuditor() (PageAuditor, *[]string, *sync.Mutex) {
+ var mu sync.Mutex
+ var calls []string
+ return func(url string, opts PageOptions) PageAudit {
+ mu.Lock()
+ calls = append(calls, url)
+ mu.Unlock()
+ return PageAudit{URL: url, BrowserPageData: BrowserPageData{AccessibilityScore: 100}}
+ }, &calls, &mu
+}
+
+func TestRunAuditOrderingAndDedupe(t *testing.T) {
+ auditor, calls, _ := fakeAuditor()
+ report, err := RunAudit(
+ AuditInput{URLs: []string{"http://x/home", "http://x/a", "http://x/home", "http://x/b"}},
+ RunOptions{Concurrency: 1},
+ nil, auditor,
+ )
+ if err != nil {
+ t.Fatalf("RunAudit: %v", err)
+ }
+ if report.SchemaVersion != SchemaVersion {
+ t.Errorf("SchemaVersion = %q", report.SchemaVersion)
+ }
+ if (*calls)[0] != "http://x/home" {
+ t.Errorf("entry URL not audited first: %v", *calls)
+ }
+ var urls []string
+ for _, p := range report.Pages {
+ urls = append(urls, p.URL)
+ }
+ want := []string{"http://x/home", "http://x/a", "http://x/b"}
+ if !reflect.DeepEqual(urls, want) {
+ t.Errorf("page order = %v, want %v", urls, want)
+ }
+ if report.SummaryScore != 100 {
+ t.Errorf("SummaryScore = %d, want 100", report.SummaryScore)
+ }
+}
+
+func TestRunAuditEntryFirstSynchronously(t *testing.T) {
+ var entryDone atomic.Bool
+ auditor := func(url string, opts PageOptions) PageAudit {
+ if url == "http://x/entry" {
+ entryDone.Store(true)
+ } else if !entryDone.Load() {
+ t.Errorf("page %s started before entry finished", url)
+ }
+ return PageAudit{URL: url}
+ }
+ if _, err := RunAudit(
+ AuditInput{URLs: []string{"http://x/entry", "http://x/a", "http://x/b", "http://x/c"}},
+ RunOptions{Concurrency: 4},
+ nil, auditor,
+ ); err != nil {
+ t.Fatalf("RunAudit: %v", err)
+ }
+}
+
+func TestRunAuditConcurrencyBound(t *testing.T) {
+ var active, peak atomic.Int32
+ auditor := func(url string, opts PageOptions) PageAudit {
+ cur := active.Add(1)
+ for {
+ p := peak.Load()
+ if cur <= p || peak.CompareAndSwap(p, cur) {
+ break
+ }
+ }
+ defer active.Add(-1)
+ return PageAudit{URL: url}
+ }
+ var urls []string
+ for i := range 20 {
+ urls = append(urls, "http://x/p"+string(rune('a'+i)))
+ }
+ report, err := RunAudit(AuditInput{URLs: urls}, RunOptions{Concurrency: 3}, nil, auditor)
+ if err != nil {
+ t.Fatalf("RunAudit: %v", err)
+ }
+ if len(report.Pages) != 20 {
+ t.Errorf("pages = %d, want 20", len(report.Pages))
+ }
+ if peak.Load() > 3 {
+ t.Errorf("peak concurrency = %d, want <= 3", peak.Load())
+ }
+ if report.Options.Concurrency != 3 {
+ t.Errorf("Options.Concurrency = %d", report.Options.Concurrency)
+ }
+}
+
+func TestRunAuditConcurrencyYieldsSameURLSet(t *testing.T) {
+ urls := []string{"http://x/1", "http://x/2", "http://x/3", "http://x/4", "http://x/5"}
+ pageSet := func(concurrency int) map[string]bool {
+ auditor, _, _ := fakeAuditor()
+ report, err := RunAudit(AuditInput{URLs: urls}, RunOptions{Concurrency: concurrency}, nil, auditor)
+ if err != nil {
+ t.Fatalf("RunAudit(concurrency=%d): %v", concurrency, err)
+ }
+ set := map[string]bool{}
+ for _, p := range report.Pages {
+ set[p.URL] = true
+ }
+ return set
+ }
+ if !reflect.DeepEqual(pageSet(1), pageSet(3)) {
+ t.Error("concurrency 1 and 3 yield different URL sets")
+ }
+}
+
+func TestRunAuditSitemapMode(t *testing.T) {
+ auditor, _, _ := fakeAuditor()
+ discover := func(sitemapURL string) ([]string, error) {
+ if sitemapURL != "http://x/sitemap.xml" {
+ t.Errorf("sitemapURL = %q", sitemapURL)
+ }
+ return []string{"http://x/a", "http://x/b"}, nil
+ }
+ report, err := RunAudit(AuditInput{SitemapURL: "http://x/sitemap.xml"}, RunOptions{}, discover, auditor)
+ if err != nil {
+ t.Fatalf("RunAudit: %v", err)
+ }
+ if len(report.Pages) != 2 {
+ t.Errorf("pages = %d, want 2", len(report.Pages))
+ }
+
+ if _, err := RunAudit(AuditInput{SitemapURL: "http://x/sitemap.xml"}, RunOptions{}, func(string) ([]string, error) {
+ return nil, errors.New("fetch failed")
+ }, auditor); err == nil {
+ t.Error("RunAudit should surface sitemap fetch errors")
+ }
+}
+
+func TestRunAuditSampleSizeAndEmpty(t *testing.T) {
+ auditor, _, _ := fakeAuditor()
+ report, err := RunAudit(
+ AuditInput{URLs: []string{"http://x/1", "http://x/2", "http://x/3"}},
+ RunOptions{SampleSize: 2},
+ nil, auditor,
+ )
+ if err != nil {
+ t.Fatalf("RunAudit: %v", err)
+ }
+ if len(report.Pages) != 2 {
+ t.Errorf("pages = %d, want 2 (sample size)", len(report.Pages))
+ }
+
+ if _, err := RunAudit(AuditInput{}, RunOptions{}, nil, auditor); err == nil {
+ t.Error("RunAudit with no input should error")
+ }
+}
+
+func TestRunAuditErrorsAreData(t *testing.T) {
+ auditor := func(url string, opts PageOptions) PageAudit {
+ if url == "http://x/down" {
+ return NewPageAuditError(url, errors.New("connection refused"))
+ }
+ return PageAudit{URL: url, BrowserPageData: BrowserPageData{AccessibilityScore: 80}}
+ }
+ report, err := RunAudit(
+ AuditInput{URLs: []string{"http://x/up", "http://x/down"}},
+ RunOptions{},
+ nil, auditor,
+ )
+ if err != nil {
+ t.Fatalf("RunAudit: %v", err)
+ }
+ if report.Pages[1].Error != "connection refused" {
+ t.Errorf("failed page Error = %q", report.Pages[1].Error)
+ }
+ if report.SummaryScore != 80 {
+ t.Errorf("SummaryScore = %d, want 80 (failed pages excluded)", report.SummaryScore)
+ }
+}
diff --git a/internal/audit/types.go b/internal/audit/types.go
index 5976976d..b9f508b3 100644
--- a/internal/audit/types.go
+++ b/internal/audit/types.go
@@ -162,6 +162,11 @@ type PageResult struct {
Title string `json:"title,omitempty"`
// StatusCode is the HTTP status of the page navigation, when known.
StatusCode int `json:"statusCode,omitempty"`
+ // Error describes a navigation or collection failure; empty on success.
+ Error string `json:"error,omitempty"`
+ // Screenshot is the base64-encoded PNG when captured inline; consumers
+ // writing artifacts move it to Browser.ScreenshotPath.
+ Screenshot string `json:"screenshot,omitempty"`
// Seaportal holds SeaPortal per-page summary fields passed through
// verbatim when the input was a SeaPortal results file.
Seaportal map[string]any `json:"seaportal,omitempty"`
diff --git a/internal/cli/actions/actions_audit.go b/internal/cli/actions/actions_audit.go
new file mode 100644
index 00000000..8c704add
--- /dev/null
+++ b/internal/cli/actions/actions_audit.go
@@ -0,0 +1,135 @@
+package actions
+
+import (
+ "encoding/base64"
+ "encoding/json"
+ "fmt"
+ "net/http"
+ "os"
+ "path/filepath"
+ "time"
+
+ "github.com/pinchtab/pinchtab/internal/cli/apiclient"
+ "github.com/spf13/cobra"
+)
+
+// auditTimeout bounds a whole multi-page audit run; well above the default
+// per-request client timeout, which a site audit easily exceeds.
+const auditTimeout = 10 * time.Minute
+
+// Audit runs a multi-page site audit via POST /audit and writes artifacts.
+func Audit(client *http.Client, base, token string, cmd *cobra.Command, target string) {
+ body := map[string]any{}
+ if v, _ := cmd.Flags().GetBool("sitemap"); v {
+ body["sitemapUrl"] = target
+ } else {
+ body["urls"] = []string{target}
+ }
+
+ screenshot, _ := cmd.Flags().GetBool("screenshot")
+ network, _ := cmd.Flags().GetBool("network-monitor")
+ body["options"] = map[string]any{"screenshot": screenshot, "network": network}
+ if v, _ := cmd.Flags().GetInt("concurrency"); v > 0 {
+ body["concurrency"] = v
+ }
+ if v, _ := cmd.Flags().GetInt("sample-size"); v > 0 {
+ body["sampleSize"] = v
+ }
+
+ longClient := &http.Client{Transport: client.Transport, Timeout: auditTimeout}
+ raw := apiclient.DoPostRaw(longClient, base, token, "/audit", body)
+
+ var report map[string]any
+ if err := json.Unmarshal(raw, &report); err != nil {
+ fmt.Fprintf(os.Stderr, "parse audit report: %v\n", err)
+ os.Exit(1)
+ }
+
+ if dir, _ := cmd.Flags().GetString("output-dir"); dir != "" {
+ if err := writeAuditArtifacts(dir, report); err != nil {
+ fmt.Fprintf(os.Stderr, "write artifacts: %v\n", err)
+ os.Exit(1)
+ }
+ fmt.Fprintf(os.Stderr, "report written to %s\n", filepath.Join(dir, "report.json"))
+ }
+
+ if v, _ := cmd.Flags().GetBool("json"); v {
+ out, _ := json.MarshalIndent(report, "", " ")
+ fmt.Println(string(out))
+ return
+ }
+ printAuditSummary(report)
+}
+
+// writeAuditArtifacts writes report.json and screenshots/ under dir. Inline
+// base64 screenshots are moved to files and each page's browser entry gets
+// the relative screenshotPath instead.
+func writeAuditArtifacts(dir string, report map[string]any) error {
+ shotsDir := filepath.Join(dir, "screenshots")
+ if err := os.MkdirAll(shotsDir, 0o755); err != nil {
+ return err
+ }
+
+ pages, _ := report["pages"].([]any)
+ for i, p := range pages {
+ page, ok := p.(map[string]any)
+ if !ok {
+ continue
+ }
+ b64, _ := page["screenshot"].(string)
+ if b64 == "" {
+ continue
+ }
+ data, err := base64.StdEncoding.DecodeString(b64)
+ if err != nil {
+ continue
+ }
+ relPath := filepath.Join("screenshots", fmt.Sprintf("page-%03d.png", i+1))
+ if err := os.WriteFile(filepath.Join(dir, relPath), data, 0o644); err != nil {
+ return err
+ }
+ delete(page, "screenshot")
+ if browser, ok := page["browser"].(map[string]any); ok {
+ browser["screenshotPath"] = relPath
+ }
+ }
+
+ out, err := json.MarshalIndent(report, "", " ")
+ if err != nil {
+ return err
+ }
+ return os.WriteFile(filepath.Join(dir, "report.json"), out, 0o644)
+}
+
+func printAuditSummary(report map[string]any) {
+ pages, _ := report["pages"].([]any)
+ failed := 0
+ broken := 0
+ for _, p := range pages {
+ page, ok := p.(map[string]any)
+ if !ok {
+ continue
+ }
+ if e, _ := page["error"].(string); e != "" {
+ failed++
+ }
+ if browser, ok := page["browser"].(map[string]any); ok {
+ if assets, ok := browser["brokenAssets"].([]any); ok {
+ broken += len(assets)
+ }
+ }
+ }
+ fmt.Printf("Audited %d page(s) · summary score %v · %d broken asset(s) · %d failed page(s)\n",
+ len(pages), report["summaryScore"], broken, failed)
+ for _, p := range pages {
+ page, ok := p.(map[string]any)
+ if !ok {
+ continue
+ }
+ status := "ok"
+ if e, _ := page["error"].(string); e != "" {
+ status = "error: " + e
+ }
+ fmt.Printf(" %s · %s\n", page["url"], status)
+ }
+}
diff --git a/internal/handlers/audit.go b/internal/handlers/audit.go
new file mode 100644
index 00000000..3cfd10eb
--- /dev/null
+++ b/internal/handlers/audit.go
@@ -0,0 +1,92 @@
+package handlers
+
+import (
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "time"
+
+ "github.com/pinchtab/pinchtab/internal/audit"
+ "github.com/pinchtab/pinchtab/internal/config"
+ "github.com/pinchtab/pinchtab/internal/httpx"
+)
+
+const maxSitemapBytes = 5 << 20
+
+type auditRequest struct {
+ URLs []string `json:"urls"`
+ SitemapURL string `json:"sitemapUrl"`
+ Options *auditPageOptionsBody `json:"options"`
+ Concurrency int `json:"concurrency"`
+ SampleSize int `json:"sampleSize"`
+}
+
+// @Endpoint POST /audit
+func (h *Handlers) HandleAudit(w http.ResponseWriter, r *http.Request) {
+ var req auditRequest
+ if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, maxBodySize)).Decode(&req); err != nil {
+ httpx.Error(w, 400, fmt.Errorf("decode: %w", err))
+ return
+ }
+ if len(req.URLs) == 0 && req.SitemapURL == "" {
+ httpx.Error(w, 400, fmt.Errorf("urls or sitemapUrl required"))
+ return
+ }
+
+ routing, ok := h.resolveNavigateBrowser(w, r, "", "")
+ if !ok {
+ return
+ }
+ if !h.ensureBrowserOrRespond(w, routing.EffectiveCfg) {
+ return
+ }
+
+ auditor := func(url string, opts audit.PageOptions) audit.PageAudit {
+ targets, err := h.validateAuditTarget(url, routing.EffectiveCfg)
+ if err != nil {
+ return audit.NewPageAuditError(url, err)
+ }
+ return h.auditPage(r.Context(), url, opts, routing.EffectiveCfg, targets)
+ }
+
+ report, err := audit.RunAudit(
+ audit.AuditInput{URLs: req.URLs, SitemapURL: req.SitemapURL},
+ audit.RunOptions{
+ SampleSize: req.SampleSize,
+ Concurrency: req.Concurrency,
+ Page: req.Options.pageOptions(),
+ },
+ h.fetchSitemap(routing.EffectiveCfg),
+ auditor,
+ )
+ if err != nil {
+ httpx.Error(w, 400, err)
+ return
+ }
+ httpx.JSON(w, 200, report)
+}
+
+// fetchSitemap returns a SitemapFetcher that applies the same URL/IDPI/SSRF
+// validation as page navigation before fetching over plain HTTP.
+func (h *Handlers) fetchSitemap(cfg *config.RuntimeConfig) audit.SitemapFetcher {
+ return func(sitemapURL string) ([]string, error) {
+ if _, err := h.validateAuditTarget(sitemapURL, cfg); err != nil {
+ return nil, err
+ }
+ client := &http.Client{Timeout: 15 * time.Second}
+ resp, err := client.Get(sitemapURL)
+ if err != nil {
+ return nil, fmt.Errorf("fetch sitemap: %w", err)
+ }
+ defer func() { _ = resp.Body.Close() }()
+ if resp.StatusCode != http.StatusOK {
+ return nil, fmt.Errorf("fetch sitemap: HTTP %d", resp.StatusCode)
+ }
+ data, err := io.ReadAll(io.LimitReader(resp.Body, maxSitemapBytes))
+ if err != nil {
+ return nil, fmt.Errorf("read sitemap: %w", err)
+ }
+ return audit.ParseSitemap(data)
+ }
+}
diff --git a/internal/handlers/audit_page.go b/internal/handlers/audit_page.go
index 6627ed77..085886ae 100644
--- a/internal/handlers/audit_page.go
+++ b/internal/handlers/audit_page.go
@@ -11,26 +11,27 @@ import (
"github.com/pinchtab/pinchtab/internal/audit"
"github.com/pinchtab/pinchtab/internal/bridge"
"github.com/pinchtab/pinchtab/internal/bridge/observe"
+ "github.com/pinchtab/pinchtab/internal/config"
"github.com/pinchtab/pinchtab/internal/httpx"
+ "github.com/pinchtab/pinchtab/internal/navguard"
)
const auditCollectTimeout = 60 * time.Second
-type auditPageRequest struct {
- URL string `json:"url"`
- Options *struct {
- Screenshot *bool `json:"screenshot"`
- Network *bool `json:"network"`
- Console *bool `json:"console"`
- A11y *bool `json:"a11y"`
- Timing *bool `json:"timing"`
- Elements *bool `json:"elements"`
- } `json:"options"`
+// auditPageOptionsBody is the JSON options shape shared by POST /audit/page
+// and POST /audit. Unset fields keep their defaults (all collectors on).
+type auditPageOptionsBody struct {
+ Screenshot *bool `json:"screenshot"`
+ Network *bool `json:"network"`
+ Console *bool `json:"console"`
+ A11y *bool `json:"a11y"`
+ Timing *bool `json:"timing"`
+ Elements *bool `json:"elements"`
}
-func (req auditPageRequest) pageOptions() audit.PageOptions {
+func (o *auditPageOptionsBody) pageOptions() audit.PageOptions {
opts := audit.DefaultPageOptions()
- if req.Options == nil {
+ if o == nil {
return opts
}
apply := func(dst *bool, src *bool) {
@@ -38,15 +39,20 @@ func (req auditPageRequest) pageOptions() audit.PageOptions {
*dst = *src
}
}
- apply(&opts.Screenshot, req.Options.Screenshot)
- apply(&opts.Network, req.Options.Network)
- apply(&opts.Console, req.Options.Console)
- apply(&opts.A11y, req.Options.A11y)
- apply(&opts.Timing, req.Options.Timing)
- apply(&opts.Elements, req.Options.Elements)
+ apply(&opts.Screenshot, o.Screenshot)
+ apply(&opts.Network, o.Network)
+ apply(&opts.Console, o.Console)
+ apply(&opts.A11y, o.A11y)
+ apply(&opts.Timing, o.Timing)
+ apply(&opts.Elements, o.Elements)
return opts
}
+type auditPageRequest struct {
+ URL string `json:"url"`
+ Options *auditPageOptionsBody `json:"options"`
+}
+
// @Endpoint POST /audit/page
func (h *Handlers) HandleAuditPage(w http.ResponseWriter, r *http.Request) {
var req auditPageRequest
@@ -72,14 +78,43 @@ func (h *Handlers) HandleAuditPage(w http.ResponseWriter, r *http.Request) {
return
}
+ httpx.JSON(w, 200, h.auditPage(r.Context(), req.URL, req.Options.pageOptions(), routing.EffectiveCfg, targets))
+}
+
+// validateAuditTarget is the non-writing sibling of validateNavigateTargets
+// for batch audits: the same URL/IDPI/SSRF validation, but failures come back
+// as errors so the caller can turn them into per-page report entries.
+func (h *Handlers) validateAuditTarget(url string, cfg *config.RuntimeConfig) (navTargets, error) {
+ allowFile := cfg != nil && cfg.AllowFileScheme
+ if err := validateNavigateURL(url, allowFile); err != nil {
+ return navTargets{}, err
+ }
+ domainResult := h.IDPIGuard.CheckDomain(url)
+ if domainResult.Blocked {
+ return navTargets{}, fmt.Errorf("navigation blocked by IDPI: %s", domainResult.Reason)
+ }
+ if allowFile && navguard.IsFileURL(url) {
+ return navTargets{target: &validatedNavigateTarget{AllowInternal: true}, trustedCIDRs: buildNavigateTrustedProxyCIDRs(cfg)}, nil
+ }
+ target, err := validateNavigateTarget(url, h.IDPIGuard.DomainAllowed(url), parseCIDRs(cfg.TrustedResolveCIDRs))
+ if err != nil {
+ return navTargets{}, err
+ }
+ return navTargets{target: target, trustedCIDRs: buildNavigateTrustedProxyCIDRs(cfg)}, nil
+}
+
+// auditPage navigates a fresh tab to url and assembles the single-page
+// audit. Per-page failures are data, not crashes: navigation errors come
+// back as a structured entry with the error field set. The tab is always
+// closed before returning.
+func (h *Handlers) auditPage(clientCtx context.Context, url string, opts audit.PageOptions, cfg *config.RuntimeConfig, targets navTargets) audit.PageAudit {
tabID, tabCtx, _, err := h.Bridge.CreateTab("")
if err != nil {
- httpx.Error(w, 500, fmt.Errorf("new tab: %w", err))
- return
+ return audit.NewPageAuditError(url, fmt.Errorf("new tab: %w", err))
}
defer func() { _ = h.Bridge.CloseTab(tabID) }()
- navTimeout := routing.EffectiveCfg.NavigateTimeout
+ navTimeout := cfg.NavigateTimeout
if navTimeout <= 0 {
navTimeout = 30 * time.Second
}
@@ -88,28 +123,23 @@ func (h *Handlers) HandleAuditPage(w http.ResponseWriter, r *http.Request) {
navGuard, err := installNavigateRuntimeGuardWithBridge(h.Bridge, navCtx, navCancel, targets.target, targets.trustedCIDRs)
if err != nil {
- httpx.Error(w, 500, fmt.Errorf("navigation guard: %w", err))
- return
+ return audit.NewPageAuditError(url, fmt.Errorf("navigation guard: %w", err))
}
- // Per-page failures are data, not crashes: navigation errors come back
- // as a structured entry with the error field set, never a 5xx.
- if _, navErr := h.Bridge.Navigate(navCtx, req.URL, bridge.NavigateParams{MaxRedirects: routing.EffectiveCfg.MaxRedirects}); navErr != nil {
+ if _, navErr := h.Bridge.Navigate(navCtx, url, bridge.NavigateParams{MaxRedirects: cfg.MaxRedirects}); navErr != nil {
if navGuard != nil {
if blockedErr := navGuard.blocked(); blockedErr != nil {
navErr = blockedErr
}
}
- httpx.JSON(w, 200, audit.NewPageAuditError(req.URL, navErr))
- return
+ return audit.NewPageAuditError(url, navErr)
}
// Chrome renders net-level failures (connection refused, DNS) as an
// error page without failing the navigation; detect it and report the
// underlying net error from the network capture as page data.
if cur, urlErr := h.Bridge.CurrentURL(navCtx); urlErr == nil && strings.HasPrefix(cur, "chrome-error://") {
- httpx.JSON(w, 200, audit.NewPageAuditError(req.URL, h.documentNetError(tabID, req.URL)))
- return
+ return audit.NewPageAuditError(url, h.documentNetError(tabID, url))
}
// Paint metrics only fire on visible pages.
@@ -117,13 +147,12 @@ func (h *Handlers) HandleAuditPage(w http.ResponseWriter, r *http.Request) {
cCtx, cCancel := context.WithTimeout(tabCtx, auditCollectTimeout)
defer cCancel()
- go httpx.CancelOnClientDone(r.Context(), cCancel)
+ go httpx.CancelOnClientDone(clientCtx, cCancel)
// Let late subresources (async fetches, images) land before collecting.
_, _ = observe.WaitForQuietWindow(cCtx, 500*time.Millisecond, 5*time.Second)
- pageAudit := audit.EnrichPage(req.URL, req.pageOptions(), h.auditCollectors(cCtx, tabID))
- httpx.JSON(w, 200, pageAudit)
+ return audit.EnrichPage(url, opts, h.auditCollectors(cCtx, tabID))
}
// documentNetError recovers the document request's net error from the
diff --git a/internal/handlers/handlers.go b/internal/handlers/handlers.go
index efef1762..d45c2dff 100644
--- a/internal/handlers/handlers.go
+++ b/internal/handlers/handlers.go
@@ -323,6 +323,7 @@ func (h *Handlers) bridgeBindings() []routeBinding {
{pattern: "GET /timing", root: h.HandleTiming, tab: h.HandleTabTiming},
{pattern: "GET /a11y/audit", root: h.HandleA11yAudit, tab: h.HandleTabA11yAudit},
{pattern: "POST /audit/page", root: h.HandleAuditPage},
+ {pattern: "POST /audit", root: h.HandleAudit},
{pattern: "GET /network", root: h.HandleNetwork, tab: h.HandleTabNetwork},
{pattern: "GET /network/stream", root: h.HandleNetworkStream, tab: h.HandleTabNetworkStream},
{pattern: "GET /network/export", root: h.HandleNetworkExport, tab: h.HandleTabNetworkExport},
diff --git a/internal/routes/routes.go b/internal/routes/routes.go
index 845386c8..2bcb3b46 100644
--- a/internal/routes/routes.go
+++ b/internal/routes/routes.go
@@ -125,6 +125,7 @@ var coreEndpoints = []Endpoint{
{"GET", "/timing", "Page timing and Core Web Vitals", CapNone, true},
{"GET", "/a11y/audit", "Accessibility findings and score", CapNone, true},
{"POST", "/audit/page", "Audit a single page with browser enrichment", CapNone, false},
+ {"POST", "/audit", "Run a multi-page site audit", CapNone, false},
{"GET", "/network", "Network log", CapNone, true},
{"GET", "/network/stream", "Network SSE stream", CapNone, true},
diff --git a/tests/e2e/scenarios/api/audit-basic.sh b/tests/e2e/scenarios/api/audit-basic.sh
new file mode 100755
index 00000000..1004c94a
--- /dev/null
+++ b/tests/e2e/scenarios/api/audit-basic.sh
@@ -0,0 +1,81 @@
+#!/bin/bash
+# audit-basic.sh — POST /audit multi-page site audit runs.
+
+GROUP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${GROUP_DIR}/../../helpers/api.sh"
+
+# ─────────────────────────────────────────────────────────────────
+start_test "url-list run returns a versioned AuditReport"
+
+pt_post /audit -d "{\"urls\":[\"${FIXTURES_URL}/audit-site/index.html\",\"${FIXTURES_URL}/audit-site/clean.html\"]}"
+assert_ok "audit two pages"
+assert_json_exists "$RESULT" '.schemaVersion' "has schemaVersion"
+assert_json_exists "$RESULT" '.generatedAt' "has generatedAt"
+assert_json_length "$RESULT" '.pages' 2 "two page entries"
+assert_json_contains "$RESULT" '.pages[0].url' "index.html" "entry URL first"
+assert_json_exists "$RESULT" '.summaryScore' "has summaryScore"
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "sitemap mode discovers and audits >=10 pages"
+
+pt_post /audit -d "{\"sitemapUrl\":\"${FIXTURES_URL}/audit-site/sitemap.xml\",\"options\":{\"screenshot\":false},\"concurrency\":3}"
+assert_ok "audit from sitemap"
+assert_json_length_gte "$RESULT" '.pages' 10 "at least 10 pages audited"
+
+FAILED=$(echo "$RESULT" | jq '[.pages[] | select(.error)] | length')
+if [ "$FAILED" -eq 0 ]; then
+ pass_assert "no page entry has an error"
+else
+ fail_assert "no page entry has an error (got $FAILED: $(echo "$RESULT" | jq -c '[.pages[] | select(.error) | {url, error}]'))"
+fi
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "concurrency 3 and 1 audit the same URL set"
+
+BODY_URLS="[\"${FIXTURES_URL}/audit-site/index.html\",\"${FIXTURES_URL}/audit-site/clean.html\",\"${FIXTURES_URL}/audit-site/products/p1.html\",\"${FIXTURES_URL}/audit-site/products/p2.html\",\"${FIXTURES_URL}/audit-site/products/p3.html\"]"
+
+pt_post /audit -d "{\"urls\":${BODY_URLS},\"options\":{\"screenshot\":false},\"concurrency\":1}"
+assert_ok "audit with concurrency 1"
+SET_ONE=$(echo "$RESULT" | jq -S '[.pages[].url] | sort')
+
+pt_post /audit -d "{\"urls\":${BODY_URLS},\"options\":{\"screenshot\":false},\"concurrency\":3}"
+assert_ok "audit with concurrency 3"
+SET_THREE=$(echo "$RESULT" | jq -S '[.pages[].url] | sort')
+
+if [ "$SET_ONE" = "$SET_THREE" ]; then
+ pass_assert "same page URL set for concurrency 1 and 3"
+else
+ fail_assert "URL sets differ: $SET_ONE vs $SET_THREE"
+fi
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "run with one unreachable URL completes with error entry"
+
+pt_post /audit -d "{\"urls\":[\"${FIXTURES_URL}/audit-site/clean.html\",\"http://fixtures:9/down.html\"],\"options\":{\"screenshot\":false}}"
+assert_ok "mixed run returns 200"
+assert_json_length "$RESULT" '.pages' 2 "both pages present"
+
+CLEAN_ERR=$(echo "$RESULT" | jq -r '.pages[0].error // empty')
+if [ -z "$CLEAN_ERR" ]; then
+ pass_assert "reachable page has no error"
+else
+ fail_assert "reachable page has no error (got: $CLEAN_ERR)"
+fi
+
+DOWN_ERR=$(echo "$RESULT" | jq -r '.pages[1].error // empty')
+if [ -n "$DOWN_ERR" ]; then
+ pass_assert "unreachable page carries error ($DOWN_ERR)"
+else
+ fail_assert "unreachable page carries error"
+fi
+
+pt_get /health
+assert_ok "server healthy after mixed run"
+
+end_test
diff --git a/tests/e2e/scenarios/cli/audit-cli-basic.sh b/tests/e2e/scenarios/cli/audit-cli-basic.sh
new file mode 100755
index 00000000..8dddd1ea
--- /dev/null
+++ b/tests/e2e/scenarios/cli/audit-cli-basic.sh
@@ -0,0 +1,74 @@
+#!/bin/bash
+# audit-cli-basic.sh — pinchtab audit CLI happy path.
+
+GROUP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${GROUP_DIR}/../../helpers/cli.sh"
+
+OUT_DIR=$(mktemp -d /tmp/audit-cli.XXXXXX)
+
+# ─────────────────────────────────────────────────────────────────
+start_test "pinchtab audit <url> --output-dir writes report and screenshots"
+
+pt_ok audit "${FIXTURES_URL}/audit-site/index.html" --output-dir "$OUT_DIR"
+
+REPORT="$OUT_DIR/report.json"
+if [ -f "$REPORT" ]; then
+ pass_assert "report.json exists"
+else
+ fail_assert "report.json exists"
+fi
+
+if jq -e '.schemaVersion' "$REPORT" >/dev/null 2>&1; then
+ pass_assert "schemaVersion set ($(jq -r '.schemaVersion' "$REPORT"))"
+else
+ fail_assert "schemaVersion set"
+fi
+
+if jq -e '.pages | length == 1' "$REPORT" >/dev/null 2>&1; then
+ pass_assert "one page entry"
+else
+ fail_assert "one page entry (got: $(jq '.pages | length' "$REPORT"))"
+fi
+
+if jq -e '.pages[0].browser.screenshotPath' "$REPORT" >/dev/null 2>&1; then
+ pass_assert "page entry has screenshotPath"
+else
+ fail_assert "page entry has screenshotPath"
+fi
+
+PNG_COUNT=$(ls "$OUT_DIR/screenshots/"*.png 2>/dev/null | wc -l | tr -d ' ')
+if [ "$PNG_COUNT" -ge 1 ]; then
+ pass_assert "screenshots/*.png exist ($PNG_COUNT)"
+else
+ fail_assert "screenshots/*.png exist"
+fi
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "pinchtab audit --sitemap audits >=10 discovered pages"
+
+pt_ok audit "${FIXTURES_URL}/audit-site/sitemap.xml" --sitemap --screenshot=false --concurrency 3 --json
+PAGE_COUNT=$(echo "$PT_OUT" | jq '.pages | length' 2>/dev/null)
+if [ "${PAGE_COUNT:-0}" -ge 10 ] 2>/dev/null; then
+ pass_assert "audited $PAGE_COUNT pages from sitemap"
+else
+ fail_assert "audited >=10 pages from sitemap (got: $PAGE_COUNT)"
+fi
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "run with unreachable URL still exits 0 with error entry"
+
+pt_ok audit "http://fixtures:9/down.html" --screenshot=false --json
+ERR=$(echo "$PT_OUT" | jq -r '.pages[0].error // empty' 2>/dev/null)
+if [ -n "$ERR" ]; then
+ pass_assert "page entry carries error ($ERR)"
+else
+ fail_assert "page entry carries error"
+fi
+
+end_test
+
+rm -rf "$OUT_DIR"