browser-testing

VERIFY your changes work. Measure CLS, detect theme flicker, test visual stability, check performance. Use BEFORE and AFTER making changes to confirm fixes....

Security Scan

The skill's code, instructions, and requirements are consistent with a browser-based visual-stability and performance testing tool — nothing in the bundle appears to do hidden exfiltration or unrelated work, though it does require a Node/Playwright runtime and will visit target URLs and write screenshots to /tmp.

Purpose & Capability

The name/description match the included scripts (measure.ts, measure-cls.ts, detect-flicker.ts). The SKILL.md asserts Playwright is pre-installed, but the registry metadata lists no required binaries; in practice the scripts need Node, npx/ts-node (or precompiled JS) and Playwright and the PNG library (pngjs). This mismatch (no declared runtime dependency) is a minor incoherence but explainable.

Instruction Scope

Instructions are narrowly focused: run the provided TypeScript scripts against a URL to measure network timings, CLS, and theme flicker. The scripts launch Chromium via Playwright, capture CDP metrics, and save screenshots to /tmp. They do not read unrelated files or environment variables, nor do they transmit results to external endpoints. Caveat: they will navigate arbitrary URLs you provide — running them against untrusted targets can touch internal services (SSRF-like risk depending on your environment) and capture screenshots of whatever the page serves.

Install Mechanism

There is no install spec (instruction-only). The code files are included and intended to be run with npx ts-node or an existing Node+Playwright setup. This is low-risk for the skill bundle itself; note that running npx ts-node may pull packages at runtime if not already installed.

Credentials

The skill requests no environment variables or credentials and its actions (browser automation, screen capture, CDP metrics) are proportional to the stated purpose. No unexpected secrets or unrelated credentials are requested.

Persistence & Privilege

always is false, agent invocation is normal, and the skill does not attempt to persist configuration or modify other skills. It writes temporary screenshot files to /tmp, which is expected for this use case.

Assessment

This skill appears to be what it says: scripts that run Playwright to measure performance, CLS, and detect theme flicker. Before running: ensure you have a trusted Node environment (Node, ts-node or compiled JS) and Playwright installed or be prepared for npx to install runtime packages. Only run these scripts against URLs you trust (they will load and render the page and save screenshots to /tmp). Review the included TypeScript if you want to confirm no additional telemetry; avoid pointing it at production endpoints carrying sensitive data. If you need the tool in CI, consider converting the TypeScript to a pinned package or build artifact so you control exactly what runs.

Performance Measurement with Playwright CDP

Diagnose performance issues by measuring actual load times and network activity.

Playwright is pre-installed. Just use the measurement script.

Quick Start

A measure.ts script is included in this skill's directory. Find it and run:

# Measure a page (outputs JSON with waterfall data)
npx ts-node <path-to-this-skill>/measure.ts http://localhost:3000

# Measure an API endpoint
npx ts-node <path-to-this-skill>/measure.ts http://localhost:3000/api/products

The script is in the same directory as this SKILL.md file.

Understanding the Output

The script outputs JSON with:

{
  "url": "http://localhost:3000",
  "totalMs": 1523,
  "requests": [
    { "url": "http://localhost:3000/", "ms": 45.2 },
    { "url": "http://localhost:3000/api/products", "ms": 512.3 },
    { "url": "http://localhost:3000/api/featured", "ms": 301.1 }
  ],
  "metrics": {
    "JSHeapUsedSize": 4521984,
    "LayoutCount": 12,
    "ScriptDuration": 0.234
  }
}

Reading the Waterfall

The requests array shows network timing. Look for sequential patterns:

BAD (sequential - each waits for previous):
  /api/products    |████████|                        512ms
  /api/featured             |██████|                 301ms  (starts AFTER products)
  /api/categories                  |████|            201ms  (starts AFTER featured)
  Total: 1014ms

GOOD (parallel - all start together):
  /api/products    |████████|                        512ms
  /api/featured    |██████|                          301ms  (starts SAME TIME)
  /api/categories  |████|                            201ms  (starts SAME TIME)
  Total: 512ms (just the slowest one)

Key Metrics

Metric	What it means	Red flag
totalMs	Total page load time	> 1000ms
JSHeapUsedSize	Memory used by JS	Growing over time
LayoutCount	Layout recalculations	> 50 per page
ScriptDuration	Time in JS execution	> 0.5s

What to Look For

Symptom	Likely Cause	Fix
Requests in sequence	Sequential await statements	Use Promise.all()
Same URL requested twice	Fetch before cache check	Check cache first
Long time before response starts	Blocking operation before sending	Make it async/non-blocking
High LayoutCount	Components re-rendering	Add React.memo, useMemo

Measuring API Endpoints Directly

For quick API timing without browser overhead:

async function measureAPI(url: string) {
  const start = Date.now();
  const response = await fetch(url);
  const elapsed = Date.now() - start;
  return { url, time_ms: elapsed, status: response.status };
}

// Example
const endpoints = [
  'http://localhost:3000/api/products',
  'http://localhost:3000/api/products?cache=false',
  'http://localhost:3000/api/checkout',
];

for (const endpoint of endpoints) {
  const result = await measureAPI(endpoint);
  console.log(`${endpoint}: ${result.time_ms}ms`);
}

How the Measurement Script Works

The script uses Chrome DevTools Protocol (CDP) to intercept browser internals:

1. Network.requestWillBeSent - Event fired when request starts, we record timestamp
2. Network.responseReceived - Event fired when response arrives, we calculate duration
3. Performance.getMetrics - Returns Chrome's internal counters (memory, layout, script time)

This gives you the same data as Chrome DevTools Network tab, but programmatically.

Visual Stability Measurement

Measure CLS (Cumulative Layout Shift)

npx ts-node <path-to-this-skill>/measure-cls.ts http://localhost:3000

Output:

{
  "url": "http://localhost:3000",
  "cls": 0.42,
  "rating": "poor",
  "shifts": [
    {
      "value": 0.15,
      "hadRecentInput": false,
      "sources": [
        {"nodeId": 42, "previousRect": {...}, "currentRect": {...}}
      ]
    }
  ]
}

CLS Thresholds

CLS Score	Rating	Action
< 0.1	Good	No action needed
0.1 - 0.25	Needs Improvement	Review shift sources
> 0.25	Poor	Fix immediately

Detect Theme Flicker

npx ts-node <path-to-this-skill>/detect-flicker.ts http://localhost:3000

Detects if dark theme flashes white before loading. Sets localStorage theme before navigation and checks background color at first paint.

Accurate CLS Measurement

CLS only measures shifts within the viewport. Content that loads below the fold doesn't contribute until you scroll. For accurate measurement:

Recommended testing sequence:

1. Load page
2. Wait 3 seconds (let late-loading content appear)
3. Scroll to bottom
4. Wait 2 seconds
5. Trigger 1-2 UI actions (theme toggle, filter click, etc.)
6. Wait 2 seconds
7. Read final CLS

# Basic measurement (may miss shifts from late content)
npx ts-node <path-to-this-skill>/measure-cls.ts http://localhost:3000

# With scrolling (catches more shifts)
npx ts-node <path-to-this-skill>/measure-cls.ts http://localhost:3000 --scroll

Why measurements vary:

• Production vs development builds have different timing
• Viewport size affects what's "in view" during shifts
• setTimeout delays vary slightly between runs
• Network conditions affect when content loads

The relative difference (before/after fix) matters more than absolute values.

Common CLS Causes

Shift Source	Likely Cause	Fix
<img> elements	Missing width/height	Add dimensions or use next/image
Theme wrapper	Hydration flicker	Use inline script before React
Skeleton loaders	Size mismatch	Match skeleton to final content size
Dynamic banners	No reserved space	Add min-height to container
Late-loading sidebars	Content appears and pushes main content	Reserve space with CSS or show placeholder
Pagination/results bars	UI element appears after data loads	Show immediately with loading state
Font loading	Custom fonts cause text reflow	Use font-display: swap or preload fonts