agentic-loop 3.1.5 → 3.2.0

package/ralph/browser-verify/verify.ts

@@ -1,450 +0,0 @@
-#!/usr/bin/env npx tsx
-/**
- * browser-verify.ts - Real browser verification for Ralph
- *
- * Uses Playwright to actually load pages and verify they work.
- * Much more reliable than asking Claude to "imagine" what a page looks like.
- *
- * Usage:
- *   npx tsx browser-verify.ts <url> [options]
- *
- * Options:
- *   --selectors '["#app", ".header"]'  - Required elements (CSS selectors)
- *   --screenshot <path>                 - Save screenshot to path
- *   --timeout <ms>                      - Page load timeout (default: 30000)
- *   --headless                          - Run headless (default: true)
- *   --check-console                     - Fail on console errors (default: true)
- *   --check-network                     - Fail on failed network requests (default: true)
- *   --viewport <width>x<height>         - Viewport size (default: 1280x720)
- *   --mobile                            - Use mobile viewport (375x667)
- *   --auth-cookie <json>                - Set auth cookie before loading
- *
- * Output: JSON to stdout
- *   { "pass": true/false, "errors": [], "warnings": [], "screenshot": "path" }
- */
-
-import { chromium, Browser, Page, ConsoleMessage } from 'playwright';
-
-interface AuthLogin {
-  loginUrl: string;
-  usernameSelector: string;
-  passwordSelector: string;
-  submitSelector: string;
-  username: string;
-  password: string;
-  successIndicator?: string; // Selector or URL pattern to confirm login worked
-}
-
-interface VerifyOptions {
-  url: string;
-  selectors: string[];
-  screenshot?: string;
-  timeout: number;
-  headless: boolean;
-  checkConsole: boolean;
-  checkNetwork: boolean;
-  viewport: { width: number; height: number };
-  authCookie?: { name: string; value: string; domain: string };
-  authLogin?: AuthLogin;
-}
-
-interface VerifyResult {
-  pass: boolean;
-  errors: string[];
-  warnings: string[];
-  screenshot?: string;
-  title?: string;
-  elementsFound: string[];
-  elementsMissing: string[];
-  consoleErrors: string[];
-  networkErrors: string[];
-  loadTime: number;
-}
-
-async function parseArgs(): Promise<VerifyOptions> {
-  const args = process.argv.slice(2);
-
-  if (args.length === 0 || args[0] === '--help') {
-    console.error(`
-Usage: npx tsx browser-verify.ts <url> [options]
-
-Options:
-  --selectors '["#app", ".btn"]'  Required elements (JSON array)
-  --screenshot <path>             Save screenshot
-  --timeout <ms>                  Load timeout (default: 30000)
-  --headless                      Run headless (default: true)
-  --no-headless                   Show browser window
-  --check-console                 Fail on console errors (default: true)
-  --no-check-console              Ignore console errors
-  --check-network                 Fail on network errors (default: true)
-  --no-check-network              Ignore network errors
-  --viewport <W>x<H>              Viewport size (default: 1280x720)
-  --mobile                        Mobile viewport (375x667)
-  --auth-cookie '<json>'          Set auth cookie
-  --auth-login '<json>'           Login before verifying (see below)
-
-Auth Login JSON format:
-  {
-    "loginUrl": "http://localhost:3000/login",
-    "usernameSelector": "input[name='email']",
-    "passwordSelector": "input[name='password']",
-    "submitSelector": "button[type='submit']",
-    "username": "test@test.local",
-    "password": "testpass123",
-    "successIndicator": "/dashboard"  // URL pattern or selector
-  }
-`);
-    process.exit(1);
-  }
-
-  const url = args[0];
-  const options: VerifyOptions = {
-    url,
-    selectors: [],
-    timeout: 30000,
-    headless: true,
-    checkConsole: true,
-    checkNetwork: true,
-    viewport: { width: 1280, height: 720 },
-  };
-
-  for (let i = 1; i < args.length; i++) {
-    const arg = args[i];
-
-    switch (arg) {
-      case '--selectors':
-        try {
-          options.selectors = JSON.parse(args[++i]);
-        } catch {
-          console.error('Invalid --selectors JSON');
-          process.exit(1);
-        }
-        break;
-      case '--screenshot':
-        options.screenshot = args[++i];
-        break;
-      case '--timeout':
-        options.timeout = parseInt(args[++i], 10);
-        break;
-      case '--headless':
-        options.headless = true;
-        break;
-      case '--no-headless':
-        options.headless = false;
-        break;
-      case '--check-console':
-        options.checkConsole = true;
-        break;
-      case '--no-check-console':
-        options.checkConsole = false;
-        break;
-      case '--check-network':
-        options.checkNetwork = true;
-        break;
-      case '--no-check-network':
-        options.checkNetwork = false;
-        break;
-      case '--viewport':
-        const [w, h] = args[++i].split('x').map(Number);
-        options.viewport = { width: w, height: h };
-        break;
-      case '--mobile':
-        options.viewport = { width: 375, height: 667 };
-        break;
-      case '--auth-cookie':
-        try {
-          options.authCookie = JSON.parse(args[++i]);
-        } catch {
-          console.error('Invalid --auth-cookie JSON');
-          process.exit(1);
-        }
-        break;
-      case '--auth-login':
-        try {
-          options.authLogin = JSON.parse(args[++i]);
-        } catch {
-          console.error('Invalid --auth-login JSON');
-          process.exit(1);
-        }
-        break;
-    }
-  }
-
-  return options;
-}
-
-async function performLogin(page: Page, auth: AuthLogin, timeout: number): Promise<{ success: boolean; error?: string }> {
-  try {
-    // Navigate to login page
-    await page.goto(auth.loginUrl, {
-      timeout,
-      waitUntil: 'networkidle',
-    });
-
-    // Wait for and fill username
-    await page.waitForSelector(auth.usernameSelector, { timeout: 10000 });
-    await page.fill(auth.usernameSelector, auth.username);
-
-    // Fill password
-    await page.waitForSelector(auth.passwordSelector, { timeout: 5000 });
-    await page.fill(auth.passwordSelector, auth.password);
-
-    // Click submit
-    await page.waitForSelector(auth.submitSelector, { timeout: 5000 });
-    await page.click(auth.submitSelector);
-
-    // Wait for login to complete
-    if (auth.successIndicator) {
-      if (auth.successIndicator.startsWith('/') || auth.successIndicator.startsWith('http')) {
-        // It's a URL pattern - wait for navigation
-        await page.waitForURL(`**${auth.successIndicator}*`, { timeout: 15000 });
-      } else {
-        // It's a selector - wait for element
-        await page.waitForSelector(auth.successIndicator, { timeout: 15000 });
-      }
-    } else {
-      // No indicator - just wait for navigation away from login page
-      await page.waitForFunction(
-        (loginUrl) => !window.location.href.includes(loginUrl),
-        auth.loginUrl,
-        { timeout: 15000 }
-      );
-    }
-
-    return { success: true };
-  } catch (err: any) {
-    return { success: false, error: `Login failed: ${err.message}` };
-  }
-}
-
-async function verify(options: VerifyOptions): Promise<VerifyResult> {
-  const result: VerifyResult = {
-    pass: true,
-    errors: [],
-    warnings: [],
-    elementsFound: [],
-    elementsMissing: [],
-    consoleErrors: [],
-    networkErrors: [],
-    loadTime: 0,
-  };
-
-  let browser: Browser | null = null;
-  let page: Page | null = null;
-
-  try {
-    // Launch browser
-    browser = await chromium.launch({
-      headless: options.headless,
-    });
-
-    const context = await browser.newContext({
-      viewport: options.viewport,
-    });
-
-    // Set auth cookie if provided
-    if (options.authCookie) {
-      await context.addCookies([{
-        name: options.authCookie.name,
-        value: options.authCookie.value,
-        domain: options.authCookie.domain,
-        path: '/',
-      }]);
-    }
-
-    page = await context.newPage();
-
-    // Perform login if auth credentials provided
-    if (options.authLogin) {
-      const loginResult = await performLogin(page, options.authLogin, options.timeout);
-      if (!loginResult.success) {
-        result.errors.push(loginResult.error || 'Login failed');
-        result.pass = false;
-        return result;
-      }
-      result.warnings.push('Logged in as ' + options.authLogin.username);
-    }
-
-    // Collect console errors
-    const consoleErrors: string[] = [];
-    page.on('console', (msg: ConsoleMessage) => {
-      const type = msg.type();
-      const text = msg.text();
-
-      // Capture actual console.error calls
-      if (type === 'error') {
-        // Only ignore truly benign noise (favicons, devtools)
-        if (!text.includes('favicon') && !text.includes('DevTools')) {
-          consoleErrors.push(text);
-        }
-      }
-
-      // Also capture logs/warnings that indicate errors (e.g., custom loggers)
-      if ((type === 'log' || type === 'warning') &&
-          (text.includes('_error') || text.includes('Error:') || text.includes('ERROR'))) {
-        // Ignore known non-critical patterns
-        if (!text.includes('ResizeObserver')) {
-          consoleErrors.push(`[${type}] ${text}`);
-        }
-      }
-    });
-
-    // Collect network errors
-    const networkErrors: string[] = [];
-    page.on('requestfailed', (request) => {
-      const failure = request.failure();
-      if (failure) {
-        networkErrors.push(`${request.method()} ${request.url()}: ${failure.errorText}`);
-      }
-    });
-
-    // Track failed responses (4xx, 5xx)
-    page.on('response', (response) => {
-      const status = response.status();
-      if (status >= 400) {
-        const url = response.url();
-        // Ignore favicon and some common 404s
-        if (!url.includes('favicon') && !url.includes('hot-update')) {
-          networkErrors.push(`${response.request().method()} ${url}: ${status}`);
-        }
-      }
-    });
-
-    // Navigate to page
-    const startTime = Date.now();
-
-    try {
-      await page.goto(options.url, {
-        timeout: options.timeout,
-        waitUntil: 'networkidle',
-      });
-    } catch (err: any) {
-      if (err.message.includes('net::ERR_CONNECTION_REFUSED')) {
-        result.errors.push(`Cannot connect to ${options.url} - is the server running?`);
-        result.pass = false;
-        return result;
-      }
-      throw err;
-    }
-
-    result.loadTime = Date.now() - startTime;
-
-    // Get page title
-    result.title = await page.title();
-    if (!result.title) {
-      result.warnings.push('Page has no title');
-    }
-
-    // Check for error page indicators
-    const bodyText = await page.textContent('body') || '';
-    const errorPatterns = [
-      /something went wrong/i,
-      /error occurred/i,
-      /500 internal server/i,
-      /503 service unavailable/i,
-      /404 not found/i,
-      /oops!/i,
-      /application error/i,
-      /unhandled runtime error/i,
-    ];
-
-    for (const pattern of errorPatterns) {
-      if (pattern.test(bodyText)) {
-        result.errors.push(`Page contains error text: "${bodyText.match(pattern)?.[0]}"`);
-        result.pass = false;
-      }
-    }
-
-    // Check required selectors
-    for (const selector of options.selectors) {
-      try {
-        const element = await page.$(selector);
-        if (element) {
-          result.elementsFound.push(selector);
-        } else {
-          result.elementsMissing.push(selector);
-          result.errors.push(`Required element not found: ${selector}`);
-          result.pass = false;
-        }
-      } catch (err: any) {
-        result.elementsMissing.push(selector);
-        result.errors.push(`Error checking selector "${selector}": ${err.message}`);
-        result.pass = false;
-      }
-    }
-
-    // Check console errors
-    result.consoleErrors = consoleErrors;
-    if (options.checkConsole && consoleErrors.length > 0) {
-      result.errors.push(`${consoleErrors.length} console error(s) detected`);
-      result.pass = false;
-    }
-
-    // Check network errors
-    result.networkErrors = networkErrors;
-    if (options.checkNetwork && networkErrors.length > 0) {
-      // Filter out truly benign 404s (static resources)
-      const criticalErrors = networkErrors.filter(e =>
-        !e.includes('favicon') &&
-        !e.includes('.map') &&
-        !e.includes('hot-update') &&
-        !e.includes('.woff') &&
-        !e.includes('.ttf') &&
-        !e.includes('.png') &&
-        !e.includes('.jpg') &&
-        !e.includes('.svg') &&
-        !e.includes('.ico')
-      );
-      if (criticalErrors.length > 0) {
-        // Show actual URLs so Claude knows what to fix
-        result.errors.push(`Network errors (fix these):`);
-        criticalErrors.slice(0, 5).forEach(e => result.errors.push(`  ${e}`));
-        result.pass = false;
-      }
-    }
-
-    // Take screenshot
-    if (options.screenshot) {
-      await page.screenshot({
-        path: options.screenshot,
-        fullPage: true,
-      });
-      result.screenshot = options.screenshot;
-    }
-
-  } catch (err: any) {
-    result.errors.push(`Browser error: ${err.message}`);
-    result.pass = false;
-  } finally {
-    if (browser) {
-      await browser.close();
-    }
-  }
-
-  return result;
-}
-
-async function main() {
-  const options = await parseArgs();
-  const result = await verify(options);
-
-  // Output JSON result
-  console.log(JSON.stringify(result, null, 2));
-
-  // Exit with appropriate code
-  process.exit(result.pass ? 0 : 1);
-}
-
-main().catch((err) => {
-  console.error(JSON.stringify({
-    pass: false,
-    errors: [`Fatal error: ${err.message}`],
-    warnings: [],
-    elementsFound: [],
-    elementsMissing: [],
-    consoleErrors: [],
-    networkErrors: [],
-    loadTime: 0,
-  }, null, 2));
-  process.exit(1);
-});

package/ralph/playwright.sh

@@ -1,238 +0,0 @@
-#!/usr/bin/env bash
-# shellcheck shell=bash
-# playwright.sh - Playwright test integration for ralph
-
-# Ensure Playwright is installed and configured
-ensure_playwright() {
-  # Check if playwright config exists
-  if [[ ! -f "playwright.config.ts" ]] && [[ ! -f "playwright.config.js" ]]; then
-    print_info "Playwright not configured, initializing..."
-
-    # Check if npx is available
-    if ! command -v npx &>/dev/null; then
-      print_error "npx not found - cannot install Playwright"
-      return 1
-    fi
-
-    # Install Playwright package and browsers
-    npm install playwright 2>/dev/null && npx playwright install chromium 2>/dev/null || {
-      print_warning "Could not install Playwright - run: npm install playwright && npx playwright install chromium"
-    }
-
-    # Create minimal config if it doesn't exist
-    if [[ ! -f "playwright.config.ts" ]] && [[ ! -f "playwright.config.js" ]]; then
-      print_info "Creating playwright.config.ts..."
-      cat > playwright.config.ts << 'EOF'
-import { defineConfig, devices } from '@playwright/test';
-
-export default defineConfig({
-  testDir: './tests/e2e',
-  fullyParallel: true,
-  forbidOnly: !!process.env.CI,
-  retries: process.env.CI ? 2 : 0,
-  workers: process.env.CI ? 1 : undefined,
-  reporter: 'html',
-  use: {
-    baseURL: process.env.BASE_URL || 'http://localhost:3000',
-    trace: 'on-first-retry',
-    screenshot: 'only-on-failure',
-  },
-  projects: [
-    {
-      name: 'chromium',
-      use: { ...devices['Desktop Chrome'] },
-    },
-    {
-      name: 'mobile',
-      use: { ...devices['iPhone 13'] },
-    },
-  ],
-});
-EOF
-    fi
-
-    # Create test directory
-    mkdir -p tests/e2e
-
-    print_success "Playwright initialized"
-  fi
-
-  return 0
-}
-
-# Find test file for a story - uses explicit config or story-level testFile
-find_story_test_file() {
-  local story="$1"
-  local test_dir="$2"
-
-  # 1. Check story for explicit testFile path (preferred)
-  local explicit_file
-  explicit_file=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .testFile // empty' "$RALPH_DIR/prd.json" 2>/dev/null)
-  if [[ -n "$explicit_file" && -f "$explicit_file" ]]; then
-    echo "$explicit_file"
-    return 0
-  fi
-
-  # 2. Check config.json for e2e test directory pattern
-  local config_test_dir
-  config_test_dir=$(get_config '.playwright.testDir' "")
-  if [[ -n "$config_test_dir" ]]; then
-    test_dir="$config_test_dir"
-  fi
-
-  # 3. Standard naming: {testDir}/{story-id}.spec.ts
-  if [[ -f "${test_dir}/${story}.spec.ts" ]]; then
-    echo "${test_dir}/${story}.spec.ts"
-    return 0
-  fi
-  if [[ -f "${test_dir}/${story}.spec.js" ]]; then
-    echo "${test_dir}/${story}.spec.js"
-    return 0
-  fi
-
-  # 4. Slug-based naming from story title
-  local story_slug
-  story_slug=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .title // ""' "$RALPH_DIR/prd.json" 2>/dev/null | \
-    tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//' | sed 's/-$//')
-
-  if [[ -n "$story_slug" && -f "${test_dir}/${story_slug}.spec.ts" ]]; then
-    echo "${test_dir}/${story_slug}.spec.ts"
-    return 0
-  fi
-
-  return 1
-}
-
-# Run Playwright tests for a specific story or all tests
-run_playwright_tests() {
-  local story="$1"
-
-  # Check if Playwright is enabled in config
-  local pw_enabled
-  pw_enabled=$(get_config '.playwright.enabled' "true")
-  if [[ "$pw_enabled" == "false" ]]; then
-    echo "    (Playwright disabled in config, skipping)"
-    return 0
-  fi
-
-  # Ensure Playwright is set up
-  if ! ensure_playwright; then
-    return 1
-  fi
-
-  # Check if npx is available
-  if ! command -v npx &>/dev/null; then
-    print_error "npx not found - cannot run Playwright"
-    return 1
-  fi
-
-  # Get test directory from config or use default
-  local test_dir
-  test_dir=$(get_config '.playwright.testDir' "tests/e2e")
-
-  # Find the test file for this story
-  local test_file
-  test_file=$(find_story_test_file "$story" "$test_dir")
-
-  local log_file
-  log_file=$(create_temp_file ".log") || return 1
-
-  echo -n "  Running Playwright tests... "
-
-  if [[ -n "$test_file" && -f "$test_file" ]]; then
-    # Run story-specific test
-    echo -n "(${test_file##*/}) "
-    if npx playwright test "$test_file" --reporter=line > "$log_file" 2>&1; then
-      print_success "passed"
-      rm -f "$log_file"
-      return 0
-    fi
-  else
-    # No story-specific test - check if e2e was expected
-    local e2e_required
-    e2e_required=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .e2e // false' "$RALPH_DIR/prd.json" 2>/dev/null)
-
-    if [[ "$e2e_required" == "true" ]]; then
-      # Show where we looked and how to fix
-      print_warning "missing (e2e: true but no test file found)"
-      echo ""
-      echo "    Looked for: ${test_dir}/${story}.spec.ts"
-      echo ""
-      echo "    Fix options:"
-      echo "    1. Add 'testFile' to story: \"testFile\": \"apps/web/tests/e2e/my-test.spec.ts\""
-      echo "    2. Set testDir in .ralph/config.json: \"playwright\": {\"testDir\": \"apps/web/tests/e2e\"}"
-      echo "    3. Name test file: ${test_dir}/${story}.spec.ts"
-      rm -f "$log_file"
-      return 1  # Fail if e2e was expected but not created
-    fi
-
-    # Check if any tests exist to run
-    if [[ -z "$(find "$test_dir" -name '*.spec.ts' -o -name '*.spec.js' 2>/dev/null | head -1)" ]]; then
-      echo "skipped (not required for this story)"
-      rm -f "$log_file"
-      return 0
-    fi
-
-    # Run all tests
-    if npx playwright test --reporter=line > "$log_file" 2>&1; then
-      print_success "passed"
-      rm -f "$log_file"
-      return 0
-    fi
-  fi
-
-  # Tests failed
-  print_error "failed"
-  echo ""
-  echo "  Playwright output (last $MAX_LOG_LINES lines):"
-  tail -"$MAX_LOG_LINES" "$log_file" | sed 's/^/    /'
-
-  # Save failure for context
-  cp "$log_file" "$RALPH_DIR/last_playwright_failure.log"
-
-  rm -f "$log_file"
-  return 1
-}
-
-# Run Playwright with accessibility checks
-run_playwright_a11y() {
-  local story="$1"
-  local url="$2"
-
-  # Check if @axe-core/playwright is available
-  if ! npm list @axe-core/playwright &>/dev/null 2>&1; then
-    print_info "Installing @axe-core/playwright for accessibility testing..."
-    npm install -D @axe-core/playwright 2>/dev/null || {
-      print_warning "Could not install axe-core, skipping a11y tests"
-      return 0
-    }
-  fi
-
-  # a11y tests are typically part of the Playwright tests
-  # This function can be extended to run standalone a11y audits
-  return 0
-}
-
-# Run Playwright at specific viewport (for mobile testing)
-run_playwright_mobile() {
-  local story="$1"
-
-  local log_file
-  log_file=$(create_temp_file ".log") || return 1
-
-  echo -n "  Running mobile viewport tests... "
-
-  # Run tests with mobile project
-  if npx playwright test --project=mobile --reporter=line > "$log_file" 2>&1; then
-    print_success "passed"
-    rm -f "$log_file"
-    return 0
-  else
-    print_error "failed"
-    echo ""
-    echo "  Mobile test output:"
-    tail -"$MAX_OUTPUT_PREVIEW_LINES" "$log_file" | sed 's/^/    /'
-    rm -f "$log_file"
-    return 1
-  fi
-}