playwright-e2e-mcp 0.4.1 → 0.5.0

package/dist/tools/audit-performance.d.ts

@@ -0,0 +1,333 @@
+/**
+ * Tool 13 — audit-performance: load a page in a real browser and return the
+ * lab Web Vitals (LCP, CLS, TBT, INP during `actions`, FCP, TTFB) rated
+ * against Google's thresholds or the caller's budgets, what each one is
+ * caused by (the LCP element and the elements that shifted, as verified
+ * Playwright locators; long tasks; render-blocking and heavy requests) and a
+ * budget check to paste into a spec.
+ *
+ * It takes the same page state as inspect-page (storageState, headers,
+ * actions, routes), so signed-in dashboards and later steps of a flow can be
+ * measured, and it can emulate a mid-range phone on a slow 4G network.
+ * Lab numbers vary between loads, so `runs` reports the median.
+ */
+import { z } from 'zod';
+import type { ToolContext, ToolResponse } from '../types/index.js';
+import { type BrowserScriptData, type NetworkProfile, type PerformanceScan } from './shared.js';
+/**
+ * Lighthouse's mobile preset: a mid-range phone (4x slower CPU) on slow 4G
+ * (150 ms RTT and 1.6 Mbps, with DevTools' packet-level adjustment).
+ */
+export declare const MOBILE_PROFILE: {
+    cpuThrottle: number;
+    network: NetworkProfile;
+    viewport: {
+        width: number;
+        height: number;
+    };
+};
+export type MetricId = 'lcp' | 'cls' | 'inp' | 'tbt' | 'fcp' | 'ttfb';
+interface MetricSpec {
+    id: MetricId;
+    label: string;
+    /** "good" ceiling and "poor" floor (Google's Web Vitals / Lighthouse). */
+    good: number;
+    poor: number;
+    unit: 'ms' | 'score';
+}
+export declare const METRICS: readonly MetricSpec[];
+declare const budgetsShape: z.ZodObject<{
+    lcpMs: z.ZodOptional<z.ZodNumber>;
+    cls: z.ZodOptional<z.ZodNumber>;
+    inpMs: z.ZodOptional<z.ZodNumber>;
+    tbtMs: z.ZodOptional<z.ZodNumber>;
+    fcpMs: z.ZodOptional<z.ZodNumber>;
+    ttfbMs: z.ZodOptional<z.ZodNumber>;
+    transferKb: z.ZodOptional<z.ZodNumber>;
+    requests: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const auditPerformanceInput: z.ZodObject<{
+    storageState: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            check: "check";
+            click: "click";
+            dblclick: "dblclick";
+            fill: "fill";
+            goto: "goto";
+            hover: "hover";
+            press: "press";
+            select: "select";
+            uncheck: "uncheck";
+            wait: "wait";
+        }>;
+        locator: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        ms: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    routes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        method: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodNumber>;
+        json: z.ZodOptional<z.ZodUnknown>;
+        body: z.ZodOptional<z.ZodString>;
+        contentType: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        abort: z.ZodOptional<z.ZodBoolean>;
+        delayMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    har: z.ZodOptional<z.ZodObject<{
+        path: z.ZodString;
+        mode: z.ZodOptional<z.ZodEnum<{
+            record: "record";
+            replay: "replay";
+        }>>;
+        url: z.ZodOptional<z.ZodString>;
+        notFound: z.ZodOptional<z.ZodEnum<{
+            abort: "abort";
+            fallback: "fallback";
+        }>>;
+    }, z.core.$strip>>;
+    browser: z.ZodOptional<z.ZodEnum<{
+        chromium: "chromium";
+        firefox: "firefox";
+        webkit: "webkit";
+    }>>;
+    url: z.ZodString;
+    projectRoot: z.ZodOptional<z.ZodString>;
+    throttle: z.ZodOptional<z.ZodEnum<{
+        mobile: "mobile";
+        none: "none";
+    }>>;
+    cpuSlowdown: z.ZodOptional<z.ZodNumber>;
+    runs: z.ZodOptional<z.ZodNumber>;
+    budgets: z.ZodOptional<z.ZodObject<{
+        lcpMs: z.ZodOptional<z.ZodNumber>;
+        cls: z.ZodOptional<z.ZodNumber>;
+        inpMs: z.ZodOptional<z.ZodNumber>;
+        tbtMs: z.ZodOptional<z.ZodNumber>;
+        fcpMs: z.ZodOptional<z.ZodNumber>;
+        ttfbMs: z.ZodOptional<z.ZodNumber>;
+        transferKb: z.ZodOptional<z.ZodNumber>;
+        requests: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    waitFor: z.ZodOptional<z.ZodString>;
+    waitUntil: z.ZodOptional<z.ZodEnum<{
+        domcontentloaded: "domcontentloaded";
+        load: "load";
+        networkidle: "networkidle";
+    }>>;
+    settleMs: z.ZodOptional<z.ZodNumber>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type AuditPerformanceInput = z.infer<typeof auditPerformanceInput>;
+export type PerformanceBudgets = z.infer<typeof budgetsShape>;
+export declare const auditPerformanceSchema: z.ZodObject<{
+    storageState: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            check: "check";
+            click: "click";
+            dblclick: "dblclick";
+            fill: "fill";
+            goto: "goto";
+            hover: "hover";
+            press: "press";
+            select: "select";
+            uncheck: "uncheck";
+            wait: "wait";
+        }>;
+        locator: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        ms: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    routes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        method: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodNumber>;
+        json: z.ZodOptional<z.ZodUnknown>;
+        body: z.ZodOptional<z.ZodString>;
+        contentType: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        abort: z.ZodOptional<z.ZodBoolean>;
+        delayMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    har: z.ZodOptional<z.ZodObject<{
+        path: z.ZodString;
+        mode: z.ZodOptional<z.ZodEnum<{
+            record: "record";
+            replay: "replay";
+        }>>;
+        url: z.ZodOptional<z.ZodString>;
+        notFound: z.ZodOptional<z.ZodEnum<{
+            abort: "abort";
+            fallback: "fallback";
+        }>>;
+    }, z.core.$strip>>;
+    browser: z.ZodOptional<z.ZodEnum<{
+        chromium: "chromium";
+        firefox: "firefox";
+        webkit: "webkit";
+    }>>;
+    url: z.ZodString;
+    projectRoot: z.ZodOptional<z.ZodString>;
+    throttle: z.ZodOptional<z.ZodEnum<{
+        mobile: "mobile";
+        none: "none";
+    }>>;
+    cpuSlowdown: z.ZodOptional<z.ZodNumber>;
+    runs: z.ZodOptional<z.ZodNumber>;
+    budgets: z.ZodOptional<z.ZodObject<{
+        lcpMs: z.ZodOptional<z.ZodNumber>;
+        cls: z.ZodOptional<z.ZodNumber>;
+        inpMs: z.ZodOptional<z.ZodNumber>;
+        tbtMs: z.ZodOptional<z.ZodNumber>;
+        fcpMs: z.ZodOptional<z.ZodNumber>;
+        ttfbMs: z.ZodOptional<z.ZodNumber>;
+        transferKb: z.ZodOptional<z.ZodNumber>;
+        requests: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    waitFor: z.ZodOptional<z.ZodString>;
+    waitUntil: z.ZodOptional<z.ZodEnum<{
+        domcontentloaded: "domcontentloaded";
+        load: "load";
+        networkidle: "networkidle";
+    }>>;
+    settleMs: z.ZodOptional<z.ZodNumber>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type Rating = 'good' | 'needs-improvement' | 'poor';
+export declare function rate(id: MetricId, value: number): Rating;
+export declare function metricValue(scan: PerformanceScan, id: MetricId): number | undefined;
+export declare function formatMs(ms: number): string;
+export declare function formatBytes(bytes: number): string;
+/**
+ * Combine several runs: every number is the median of the runs that
+ * measured it, and the details (LCP element, resources) come from the run
+ * whose LCP is closest to that median.
+ */
+export declare function mergeRuns(runs: BrowserScriptData[]): {
+    data: BrowserScriptData;
+    spread?: {
+        lcp: [number, number];
+    };
+};
+interface MetricRow {
+    spec: MetricSpec;
+    value?: number;
+    rating?: Rating;
+    budget?: number;
+    overBudget: boolean;
+}
+export declare function metricRows(scan: PerformanceScan, budgets?: PerformanceBudgets): MetricRow[];
+/** Concrete causes and fixes for the metrics that are not good. */
+export declare function perfFindings(data: BrowserScriptData): string[];
+export declare function budgetCheck(url: string, budgets: PerformanceBudgets | undefined): string;
+export declare function renderPerformance(url: string, data: BrowserScriptData, options: {
+    budgets?: PerformanceBudgets;
+    profile: string;
+    runs: number;
+    spread?: {
+        lcp: [number, number];
+    };
+    stateLine?: string;
+    routeLines?: string[];
+}): string;
+export declare const auditPerformanceTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        storageState: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            type: z.ZodEnum<{
+                check: "check";
+                click: "click";
+                dblclick: "dblclick";
+                fill: "fill";
+                goto: "goto";
+                hover: "hover";
+                press: "press";
+                select: "select";
+                uncheck: "uncheck";
+                wait: "wait";
+            }>;
+            locator: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodString>;
+            url: z.ZodOptional<z.ZodString>;
+            ms: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>;
+        routes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            url: z.ZodString;
+            method: z.ZodOptional<z.ZodString>;
+            status: z.ZodOptional<z.ZodNumber>;
+            json: z.ZodOptional<z.ZodUnknown>;
+            body: z.ZodOptional<z.ZodString>;
+            contentType: z.ZodOptional<z.ZodString>;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            abort: z.ZodOptional<z.ZodBoolean>;
+            delayMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>;
+        viewport: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+        har: z.ZodOptional<z.ZodObject<{
+            path: z.ZodString;
+            mode: z.ZodOptional<z.ZodEnum<{
+                record: "record";
+                replay: "replay";
+            }>>;
+            url: z.ZodOptional<z.ZodString>;
+            notFound: z.ZodOptional<z.ZodEnum<{
+                abort: "abort";
+                fallback: "fallback";
+            }>>;
+        }, z.core.$strip>>;
+        browser: z.ZodOptional<z.ZodEnum<{
+            chromium: "chromium";
+            firefox: "firefox";
+            webkit: "webkit";
+        }>>;
+        url: z.ZodString;
+        projectRoot: z.ZodOptional<z.ZodString>;
+        throttle: z.ZodOptional<z.ZodEnum<{
+            mobile: "mobile";
+            none: "none";
+        }>>;
+        cpuSlowdown: z.ZodOptional<z.ZodNumber>;
+        runs: z.ZodOptional<z.ZodNumber>;
+        budgets: z.ZodOptional<z.ZodObject<{
+            lcpMs: z.ZodOptional<z.ZodNumber>;
+            cls: z.ZodOptional<z.ZodNumber>;
+            inpMs: z.ZodOptional<z.ZodNumber>;
+            tbtMs: z.ZodOptional<z.ZodNumber>;
+            fcpMs: z.ZodOptional<z.ZodNumber>;
+            ttfbMs: z.ZodOptional<z.ZodNumber>;
+            transferKb: z.ZodOptional<z.ZodNumber>;
+            requests: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        waitFor: z.ZodOptional<z.ZodString>;
+        waitUntil: z.ZodOptional<z.ZodEnum<{
+            domcontentloaded: "domcontentloaded";
+            load: "load";
+            networkidle: "networkidle";
+        }>>;
+        settleMs: z.ZodOptional<z.ZodNumber>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    handler: (args: AuditPerformanceInput, ctx: ToolContext) => Promise<ToolResponse>;
+};
+export {};