feat: add custom HTTP headers support (#17)

* feat(helpers): add env-based HTTP header injection

* feat(run): expose header utility in wrapper

* docs(skill): document custom headers feature

* docs: add headers API reference

* chore: bump version to 4.1.0

Author: lackeyjb

.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
       "name": "playwright-skill",
       "source": "./",
       "description": "Claude Code Skill for general-purpose browser automation with Playwright. Claude autonomously writes and executes custom automation for testing pages, validating UX, and any browser task.",
-      "version": "3.1.0",
+      "version": "4.1.0",
       "author": {
         "name": "lackeyjb"
       },

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-skill",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "description": "Claude Code Skill for general-purpose browser automation with Playwright. Auto-detects dev servers, writes clean test scripts to /tmp, and autonomously handles any browser automation task.",
   "author": {
     "name": "lackeyjb"

API_REFERENCE.md

@@ -408,6 +408,29 @@ await page.route('**/api/**', route => {
 await page.route('**/*.{png,jpg,jpeg,gif}', route => route.abort());
 ```
 
+### Custom Headers via Environment Variables
+
+The skill supports automatic header injection via environment variables:
+
+```bash
+# Single header (simple)
+PW_HEADER_NAME=X-Automated-By PW_HEADER_VALUE=playwright-skill
+
+# Multiple headers (JSON)
+PW_EXTRA_HEADERS='{"X-Automated-By":"playwright-skill","X-Request-ID":"123"}'
+```
+
+These headers are automatically applied to all requests when using:
+- `helpers.createContext(browser)` - headers merged automatically
+- `getContextOptionsWithHeaders(options)` - utility injected by run.js wrapper
+
+**Precedence (highest to lowest):**
+1. Headers passed directly in `options.extraHTTPHeaders`
+2. Environment variable headers
+3. Playwright defaults
+
+**Use case:** Identify automated traffic so your backend can return LLM-optimized responses (e.g., plain text errors instead of styled HTML).
+
 ## Visual Testing
 
 ### Screenshots

skills/playwright-skill/SKILL.md

@@ -323,6 +323,45 @@ const data = await helpers.extractTableData(page, 'table.results');
 
 See `lib/helpers.js` for full list.
 
+## Custom HTTP Headers
+
+Configure custom headers for all HTTP requests via environment variables. Useful for:
+- Identifying automated traffic to your backend
+- Getting LLM-optimized responses (e.g., plain text errors instead of styled HTML)
+- Adding authentication tokens globally
+
+### Configuration
+
+**Single header (common case):**
+```bash
+PW_HEADER_NAME=X-Automated-By PW_HEADER_VALUE=playwright-skill \
+  cd $SKILL_DIR && node run.js /tmp/my-script.js
+```
+
+**Multiple headers (JSON format):**
+```bash
+PW_EXTRA_HEADERS='{"X-Automated-By":"playwright-skill","X-Debug":"true"}' \
+  cd $SKILL_DIR && node run.js /tmp/my-script.js
+```
+
+### How It Works
+
+Headers are automatically applied when using `helpers.createContext()`:
+
+```javascript
+const context = await helpers.createContext(browser);
+const page = await context.newPage();
+// All requests from this page include your custom headers
+```
+
+For scripts using raw Playwright API, use the injected `getContextOptionsWithHeaders()`:
+
+```javascript
+const context = await browser.newContext(
+  getContextOptionsWithHeaders({ viewport: { width: 1920, height: 1080 } })
+);
+```
+
 ## Advanced Usage
 
 For comprehensive Playwright API documentation, see [API_REFERENCE.md](API_REFERENCE.md):
@@ -339,6 +378,7 @@ For comprehensive Playwright API documentation, see [API_REFERENCE.md](API_REFER
 ## Tips
 
 - **CRITICAL: Detect servers FIRST** - Always run `detectDevServers()` before writing test code for localhost testing
+- **Custom headers** - Use `PW_HEADER_NAME`/`PW_HEADER_VALUE` env vars to identify automated traffic to your backend
 - **Use /tmp for test files** - Write to `/tmp/playwright-test-*.js`, never to skill directory or user's project
 - **Parameterize URLs** - Put detected/provided URL in a `TARGET_URL` constant at the top of every script
 - **DEFAULT: Visible browser** - Always use `headless: false` unless user explicitly asks for headless mode

skills/playwright-skill/lib/helpers.js

@@ -3,6 +3,38 @@
 
 const { chromium, firefox, webkit } = require('playwright');
 
+/**
+ * Parse extra HTTP headers from environment variables.
+ * Supports two formats:
+ * - PW_HEADER_NAME + PW_HEADER_VALUE: Single header (simple, common case)
+ * - PW_EXTRA_HEADERS: JSON object for multiple headers (advanced)
+ * Single header format takes precedence if both are set.
+ * @returns {Object|null} Headers object or null if none configured
+ */
+function getExtraHeadersFromEnv() {
+  const headerName = process.env.PW_HEADER_NAME;
+  const headerValue = process.env.PW_HEADER_VALUE;
+
+  if (headerName && headerValue) {
+    return { [headerName]: headerValue };
+  }
+
+  const headersJson = process.env.PW_EXTRA_HEADERS;
+  if (headersJson) {
+    try {
+      const parsed = JSON.parse(headersJson);
+      if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+        return parsed;
+      }
+      console.warn('PW_EXTRA_HEADERS must be a JSON object, ignoring...');
+    } catch (e) {
+      console.warn('Failed to parse PW_EXTRA_HEADERS as JSON:', e.message);
+    }
+  }
+
+  return null;
+}
+
 /**
  * Launch browser with standard configuration
  * @param {string} browserType - 'chromium', 'firefox', or 'webkit'
@@ -313,6 +345,14 @@ async function retryWithBackoff(fn, maxRetries = 3, initialDelay = 1000) {
  * @param {Object} options - Context options
  */
 async function createContext(browser, options = {}) {
+  const envHeaders = getExtraHeadersFromEnv();
+
+  // Merge environment headers with any passed in options
+  const mergedHeaders = {
+    ...envHeaders,
+    ...options.extraHTTPHeaders
+  };
+
   const defaultOptions = {
     viewport: { width: 1280, height: 720 },
     userAgent: options.mobile
@@ -321,7 +361,9 @@ async function createContext(browser, options = {}) {
     permissions: options.permissions || [],
     geolocation: options.geolocation,
     locale: options.locale || 'en-US',
-    timezoneId: options.timezoneId || 'America/New_York'
+    timezoneId: options.timezoneId || 'America/New_York',
+    // Only include extraHTTPHeaders if we have any
+    ...(Object.keys(mergedHeaders).length > 0 && { extraHTTPHeaders: mergedHeaders })
   };
 
   return await browser.newContext({ ...defaultOptions, ...options });
@@ -394,5 +436,6 @@ module.exports = {
   handleCookieBanner,
   retryWithBackoff,
   createContext,
-  detectDevServers
+  detectDevServers,
+  getExtraHeadersFromEnv
 };

skills/playwright-skill/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-skill",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "description": "General-purpose browser automation with Playwright for Claude Code with auto-detection and smart test management",
   "author": "lackeyjb",
   "main": "run.js",
@@ -17,7 +17,7 @@
     "general-purpose"
   ],
   "dependencies": {
-    "playwright": "^1.48.0"
+    "playwright": "^1.57.0"
   },
   "engines": {
     "node": ">=14.0.0"

skills/playwright-skill/run.js

@@ -122,6 +122,26 @@ function wrapCodeIfNeeded(code) {
 const { chromium, firefox, webkit, devices } = require('playwright');
 const helpers = require('./lib/helpers');
 
+// Extra headers from environment variables (if configured)
+const __extraHeaders = helpers.getExtraHeadersFromEnv();
+
+/**
+ * Utility to merge environment headers into context options.
+ * Use when creating contexts with raw Playwright API instead of helpers.createContext().
+ * @param {Object} options - Context options
+ * @returns {Object} Options with extraHTTPHeaders merged in
+ */
+function getContextOptionsWithHeaders(options = {}) {
+  if (!__extraHeaders) return options;
+  return {
+    ...options,
+    extraHTTPHeaders: {
+      ...__extraHeaders,
+      ...(options.extraHTTPHeaders || {})
+    }
+  };
+}
+
 (async () => {
   try {
     ${code}