proffesor-for-testing__agentic-qe/docs/integration/claude-flow-browser.md

@claude-flow/browser Integration Guide

Version: 1.0.0 Status: Integration Complete Strategy: COMPLEMENT (Strategic Import)

Executive Summary

This document describes the integration of high-value components from @claude-flow/browser v3.0.0-alpha.2 into AQE v3. The integration adopts a COMPLEMENT strategy: keeping the existing AgentBrowserClient as the foundation while strategically importing security scanner, workflow templates, trajectory learning, and swarm coordination capabilities.

Key Benefits

• Security-First Testing: URL validation, phishing detection, and PII scanning for browser automation
• Workflow Templates: 9 pre-built workflow templates for common testing scenarios
• Trajectory Learning: Browser action sequences feed into QEReasoningBank for pattern learning
• Parallel Viewport Testing: Multi-session coordination for 3x+ speedup on visual regression tests

---

Installation

The @claude-flow/browser package is an optional peer dependency. AQE v3 provides fallback implementations for all features.

# Install as optional dependency
npm install --save-optional @claude-flow/browser@^3.0.0

# Verify installation
npm list @claude-flow/browser

If the package is not installed, AQE v3 will:

• Use basic URL validation instead of full security scanner
• Allow manual workflow definitions instead of templates
• Disable trajectory learning (falls back to standard pattern storage)
• Run viewport tests sequentially instead of in parallel

---

Quick Start

Security Scanning

import { BrowserSecurityScanner } from '@agentic-qe/v3/domains/visual-accessibility';

const scanner = new BrowserSecurityScanner();
await scanner.initialize();

// Validate URL before testing
const urlResult = await scanner.validateUrl('https://example.com');
if (urlResult.ok) {
  console.log('URL is safe:', urlResult.value.safe);
  console.log('Security score:', urlResult.value.score);
}

// Scan page content for PII
const piiResult = await scanner.scanForPII(pageContent);
if (piiResult.ok && piiResult.value.hasPII) {
  console.log('PII detected:', piiResult.value.detectedTypes);
}

Workflow Templates

import { WorkflowLoader } from '@agentic-qe/v3/workflows/browser';

const loader = new WorkflowLoader();

// Load and execute pre-built workflow
const workflow = await loader.load('visual-regression', {
  urls: ['https://example.com'],
  baselineDir: './baselines',
});

const result = await workflow.execute();

Trajectory Learning

import { TrajectoryAdapter } from '@agentic-qe/v3/adapters';
import { QEReasoningBank } from '@agentic-qe/v3/learning-optimization';

const adapter = new TrajectoryAdapter(reasoningBank);

// Start tracking browser trajectory
const trajectoryId = await adapter.startTrajectory({
  workflowType: 'login-flow',
  initialUrl: 'https://example.com/login',
});

// Record steps
await adapter.recordStep(trajectoryId, {
  action: 'fill',
  selector: '#username',
  value: 'user@example.com',
});

// Complete and store for learning
await adapter.completeTrajectory(trajectoryId, { success: true });

Parallel Viewport Testing

import { BrowserSwarmCoordinator } from '@agentic-qe/v3/domains/visual-accessibility';

const swarm = new BrowserSwarmCoordinator();

// Initialize with standard viewports
await swarm.initialize([
  { width: 320, height: 568, name: 'iPhone SE' },
  { width: 1920, height: 1080, name: 'Desktop' },
]);

// Capture across all viewports in parallel
const screenshots = await swarm.captureAllViewports('https://example.com');

// 3x+ faster than sequential execution
for (const [viewport, screenshot] of screenshots) {
  console.log(`${viewport.name}: ${screenshot.ok ? 'captured' : 'failed'}`);
}

---

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        AQE v3 Core                              │
│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────┐│
│  │ Test Execution   │  │Visual-Accessibility│ │Learning-Opt   ││
│  │   Domain         │  │     Domain         │  │   Domain      ││
│  └──────────────────┘  └──────────────────┘  └───────────────┘│
│           │                     │                      │        │
│           └─────────────────────┼──────────────────────┘        │
│                                 │                               │
└─────────────────────────────────┼───────────────────────────────┘
                                  │
                    ┌─────────────┴──────────────┐
                    │  Integration Layer         │
                    │  (Result<T,E> Adapters)    │
                    └─────────────┬──────────────┘
                                  │
        ┌─────────────────────────┴─────────────────────────┐
        │                                                     │
┌───────┴──────────┐  ┌─────────────────┐  ┌───────────────┴───┐
│ Security Scanner │  │ Workflow        │  │ Trajectory        │
│ - URL validation │  │ Templates       │  │ Adapter           │
│ - Phishing detect│  │ - 9 templates   │  │ - Pattern learning│
│ - PII scanning   │  │ - YAML format   │  │ - HNSW indexing   │
└──────────────────┘  └─────────────────┘  └───────────────────┘
        │
┌───────┴──────────┐
│ Swarm            │
│ Coordinator      │
│ - Parallel exec  │
│ - Resource mgmt  │
└──────────────────┘
        │
┌───────┴──────────────────────────┐
│   @claude-flow/browser           │
│   (Optional Peer Dependency)     │
└──────────────────────────────────┘

---

Component Integration

1. Security Scanner

Location: /v3/src/domains/visual-accessibility/services/browser-security-scanner.ts Docs: Security Scanner API Reference Integration: Pre-capture URL validation in visual testing workflows

Features:

• URL validation (SSRF, open redirect prevention)
• Phishing detection against known patterns
• PII scanning (SSN, email, credit card, API keys)
• XSS prevention via input sanitization

Fallback: Basic URL parsing and regex-based PII detection when package unavailable

2. Workflow Templates

Location: /v3/src/workflows/browser/templates/ Docs: Workflow Templates Reference Integration: Test-execution and visual-accessibility domains

Templates:

1. login-flow.yaml - Authentication testing
2. oauth-flow.yaml - OAuth2/OIDC testing
3. scraping-workflow.yaml - Data extraction patterns
4. visual-regression.yaml - Screenshot comparison
5. form-validation.yaml - Input validation testing
6. navigation-flow.yaml - Multi-page navigation
7. api-integration.yaml - Browser-API hybrid tests
8. performance-audit.yaml - Lighthouse-style audits
9. accessibility-audit.yaml - WCAG compliance

Fallback: Manual workflow definition when templates unavailable

3. Trajectory Learning

Location: /v3/src/adapters/trajectory-adapter.ts Docs: Trajectory Learning Guide Integration: QEReasoningBank pattern storage with HNSW indexing

Features:

• Convert browser trajectories to QE patterns
• Store action sequences with vector embeddings
• Similarity search for successful patterns (<100ms p95)
• Pattern success rate tracking

Fallback: Standard pattern storage without trajectory-specific features

4. Swarm Coordinator

Location: /v3/src/domains/visual-accessibility/services/browser-swarm-coordinator.ts Docs: Swarm Coordination Guide Integration: Multi-viewport parallel testing in visual-accessibility

Features:

• Parallel viewport capture (3x+ speedup)
• Resource pooling and management
• Graceful process cleanup
• Standard viewport configurations

Fallback: Sequential viewport execution when swarm unavailable

---

Configuration

Enable All Features

// v3/src/config/browser-integration.ts
export const browserIntegrationConfig = {
  security: {
    enabled: true,
    validateUrls: true,
    scanPII: true,
    phishingDetection: true,
  },
  workflows: {
    enabled: true,
    templatesDir: './workflows/browser/templates',
  },
  trajectoryLearning: {
    enabled: true,
    storeTrajectories: true,
    hnswEnabled: true,
  },
  swarm: {
    enabled: true,
    maxConcurrentSessions: 5,
    defaultViewports: 'standard', // or custom array
  },
};

Environment Variables

# Enable/disable features
AQE_BROWSER_SECURITY=true
AQE_BROWSER_WORKFLOWS=true
AQE_TRAJECTORY_LEARNING=true
AQE_BROWSER_SWARM=true

# Swarm configuration
AQE_SWARM_MAX_SESSIONS=5
AQE_SWARM_TIMEOUT=30000

# Memory limits for trajectory storage
AQE_TRAJECTORY_MAX_SIZE_MB=500

---

Troubleshooting

Package Not Found

Error: Cannot find module '@claude-flow/browser'

Solution:

1. Install the optional dependency: npm install --save-optional @claude-flow/browser@^3.0.0
2. Or rely on fallback implementations (features will be limited)

Security Scanner False Positives

Error: Legitimate URLs flagged as unsafe

Solution:

// Add URL whitelist
const scanner = new BrowserSecurityScanner({
  whitelist: [
    'https://example.com',
    'https://localhost:*',
  ],
});

Trajectory Storage Memory Issues

Error: Memory usage exceeds threshold

Solution:

// Disable trajectory storage
const config = {
  trajectoryLearning: {
    enabled: false, // Falls back to standard patterns
  },
};

// Or reduce retention
const config = {
  trajectoryLearning: {
    maxTrajectories: 1000, // Default: 10000
    ttlDays: 7,            // Default: 30
  },
};

Swarm Process Cleanup Failure

Error: Browser processes not cleaned up

Solution:

// Enable aggressive cleanup
const swarm = new BrowserSwarmCoordinator({
  cleanupStrategy: 'aggressive',
  cleanupTimeout: 5000, // ms
});

// Or use sequential fallback
const config = {
  swarm: {
    enabled: false, // Falls back to sequential
  },
};

Workflow Template Parse Error

Error: YAML template fails to parse

Solution:

1. Validate YAML syntax: npx yaml-lint workflows/browser/templates/*.yaml
2. Check variable substitution: Ensure all required variables are provided
3. Use manual workflow definition as fallback

---

Performance Benchmarks

Feature	With Integration	Fallback	Speedup
URL Security Scan	50ms p95	5ms p95 (basic validation)	N/A
PII Detection	120ms p95	80ms p95 (regex only)	1.5x slower but more accurate
Viewport Capture (5 viewports)	8s (parallel)	25s (sequential)	3.1x faster
Trajectory Search	85ms p95 (HNSW)	250ms p95 (linear)	2.9x faster

---

Migration from Vibium-Only

If you're currently using only Vibium for browser automation:

// Before (Vibium only)
import { Browser } from 'vibium';

const browser = new Browser();
const screenshot = await browser.screenshot('https://example.com');

// After (with @claude-flow/browser integration)
import { BrowserSecurityScanner } from '@agentic-qe/v3/domains/visual-accessibility';
import { Browser } from 'vibium';

const scanner = new BrowserSecurityScanner();
await scanner.initialize();

// Validate URL first
const urlCheck = await scanner.validateUrl('https://example.com');
if (!urlCheck.ok || !urlCheck.value.safe) {
  throw new Error('Unsafe URL detected');
}

// Then capture
const browser = new Browser();
const screenshot = await browser.screenshot('https://example.com');

// Scan for PII before saving
const piiCheck = await scanner.scanForPII(screenshot.toString());
if (piiCheck.ok && piiCheck.value.hasPII) {
  console.warn('PII detected in screenshot');
}

---

Testing Integration

Unit Tests

# Test adapters
npm run test:unit -- src/adapters/browser-result-adapter.test.ts
npm run test:unit -- src/adapters/trajectory-adapter.test.ts

# Test services
npm run test:unit -- src/domains/visual-accessibility/services/browser-security-scanner.test.ts

Integration Tests

# Full pipeline tests
npm run test:integration -- tests/integration/browser-integration/

# Specific components
npm run test:integration -- tests/integration/browser-integration/security-scanner.integration.test.ts
npm run test:integration -- tests/integration/browser-integration/parallel-viewports.integration.test.ts

---

Security Considerations

1. URL Validation: Always validate URLs before browser operations to prevent SSRF attacks
2. PII Detection: Scan captured content before saving to prevent data exposure
3. Process Isolation: Swarm coordinator isolates browser sessions to prevent cross-contamination
4. Resource Limits: Configure max concurrent sessions to prevent resource exhaustion

---

Related Documentation

• Security Scanner API Reference
• Workflow Templates Reference
• Trajectory Learning Guide
• Swarm Coordination Guide
• Visual-Accessibility Domain
• QEReasoningBank Integration

---

Support

For issues related to:

• Integration bugs: File issue at agentic-qe GitHub
• @claude-flow/browser bugs: File issue at claude-flow GitHub
• Feature requests: Use GitHub Discussions