proffesor-for-testing__agentic-qe/docs/plans/goap-agent-browser-integration.md

GOAP: agent-browser Integration for AQE v3

Version: 1.0.0 Created: 2026-01-19 Status: Ready for Execution Estimated Effort: 2-3 weeks Prerequisites: Vibium integration (almost complete)

---

1. Executive Summary

This GOAP plan integrates agent-browser from Vercel Labs as a complementary browser automation tool alongside the existing Vibium integration. agent-browser provides capabilities Vibium lacks:

Capability	Vibium	agent-browser
MCP Tools	7 tools	70+ CLI commands
Element Selection	CSS selectors	Snapshot refs (@e1, @e2)
Multi-Session	No	Yes (isolated browsers)
Network Interception	No	Yes (route, mock, abort)
Device Emulation	Viewport only	Full device profiles
Video Recording	No	Trace recording
Auth State Persistence	No	Yes (state save/load)
Context Efficiency	Full DOM	93% less context (claimed)

---

2. World State Analysis

2.1 Current State (Initial World)

WorldState:
  # Existing Browser Infrastructure
  vibiumIntegrated: true              # Almost complete in parallel terminal
  vibiumClientWrapper: true
  vibiumTypes: true
  unifiedBrowserInterface: false      # No common interface yet

  # agent-browser Specific
  agentBrowserInstalled: false
  agentBrowserClientWrapper: false
  snapshotParserExists: false
  sessionManagerExists: false
  commandExecutorExists: false

  # Unified Browser Features
  browserClientFactory: false         # Select vibium vs agent-browser
  commonBrowserTypes: false           # Shared interfaces
  gracefulFallback: false             # Fallback when tool unavailable

  # Domain Integration
  visualAccessibilityUsesAgentBrowser: false
  testExecutionUsesAgentBrowser: false
  multiViewportWithRefs: false
  e2eWithDeterministicSelection: false

  # Advanced Capabilities
  networkInterceptionCapable: false
  deviceEmulationCapable: false
  authStatePersistence: false
  traceRecordingCapable: false

2.2 Goal State (Target World)

WorldState:
  # Existing (Unchanged)
  vibiumIntegrated: true
  vibiumClientWrapper: true
  vibiumTypes: true

  # Unified Browser Interface
  unifiedBrowserInterface: true
  browserClientFactory: true
  commonBrowserTypes: true
  gracefulFallback: true

  # agent-browser Integration
  agentBrowserInstalled: true
  agentBrowserClientWrapper: true
  snapshotParserExists: true
  sessionManagerExists: true
  commandExecutorExists: true

  # Domain Integration
  visualAccessibilityUsesAgentBrowser: true
  testExecutionUsesAgentBrowser: true
  multiViewportWithRefs: true
  e2eWithDeterministicSelection: true

  # Advanced Capabilities
  networkInterceptionCapable: true
  deviceEmulationCapable: true
  authStatePersistence: true
  traceRecordingCapable: true

2.3 Gap Analysis

Area	Gap	Impact	Priority
Unified Interface	No common BrowserClient interface	High - prevents tool switching	P0
Snapshot Parsing	Cannot use deterministic refs	High - key differentiator	P0
Session Management	No parallel browser isolation	Medium - limits parallel E2E	P1
Network Mocking	Cannot mock API responses	Medium - better E2E testing	P1
Device Emulation	Limited viewport testing	Low - Vibium has basic support	P2

---

3. Goal Definition

3.1 Primary Goals

Goal ID	Description	Success Criteria
G1	Unified BrowserClient Interface	Both Vibium and agent-browser implement IBrowserClient
G2	agent-browser Client Wrapper	TypeScript wrapper in v3/src/integrations/browser/agent-browser/
G3	Snapshot Ref Parser	Parse snapshot output to extract refs (@e1, @e2)
G4	Multi-Session Management	Run isolated browser sessions in parallel
G5	Domain Integration	visual-accessibility and test-execution use agent-browser
G6	Graceful Fallback	Auto-fallback to Vibium if agent-browser unavailable

3.2 Success Metrics

interface IntegrationMetrics {
  // Phase 1: Core Integration
  cliCommandsCovered: 20;           // Most-used commands wrapped
  snapshotParsingAccuracy: 99.9;    // % refs correctly parsed
  sessionIsolation: true;           // Sessions don't leak state

  // Phase 2: Domain Integration
  viewportsWithRefs: 5;             // mobile, tablet, desktop, wide, 4k
  e2eTestsWithRefs: 10;             // Sample tests using refs
  fallbackReliability: 99.5;        // % successful fallback to Vibium

  // Phase 3: Advanced Features
  networkMockingCoverage: 80;       // % of API mocking scenarios
  deviceProfiles: 15;               // iPhone, Pixel, iPad, etc.
  authStateReuse: true;             // Login once, reuse across tests
}

---

4. Action Library

4.1 Phase 1: Core Integration (Week 1)

Action: AB1.1 - Create Common Browser Types

id: AB1.1
name: CreateCommonBrowserTypes
description: Define unified IBrowserClient interface and common types
preconditions:
  - vibiumTypes: true
  - commonBrowserTypes: false
effects:
  - commonBrowserTypes: true
cost: 2
estimatedHours: 4
agentType: coder
model: haiku
parallelizable: true

Target File: v3/src/integrations/browser/types.ts

// Core interface both tools implement
export interface IBrowserClient {
  // Lifecycle
  launch(options?: BrowserLaunchOptions): Promise<Result<BrowserSession, BrowserError>>;
  quit(): Promise<Result<void, BrowserError>>;
  isAvailable(): Promise<boolean>;

  // Navigation
  navigate(url: string, options?: NavigateOptions): Promise<Result<NavigateResult, BrowserError>>;
  reload(): Promise<Result<void, BrowserError>>;
  goBack(): Promise<Result<void, BrowserError>>;

  // Element Interaction (abstract - implementations differ)
  click(target: ElementTarget): Promise<Result<void, BrowserError>>;
  fill(target: ElementTarget, text: string): Promise<Result<void, BrowserError>>;
  getText(target: ElementTarget): Promise<Result<string, BrowserError>>;

  // Screenshots
  screenshot(options?: ScreenshotOptions): Promise<Result<ScreenshotResult, BrowserError>>;

  // Accessibility
  checkAccessibility(options?: A11yOptions): Promise<Result<A11yResult, BrowserError>>;
}

// Unified element targeting
export type ElementTarget =
  | { type: 'ref'; value: string }      // @e1, @e2 (agent-browser)
  | { type: 'css'; value: string }      // CSS selector
  | { type: 'xpath'; value: string }    // XPath
  | { type: 'text'; value: string };    // Text content

// Browser tool preference
export type BrowserToolPreference = 'agent-browser' | 'vibium' | 'auto';

---

Action: AB1.2 - Create agent-browser Command Executor

id: AB1.2
name: CreateCommandExecutor
description: TypeScript wrapper for agent-browser CLI commands
preconditions:
  - commonBrowserTypes: true
  - commandExecutorExists: false
effects:
  - commandExecutorExists: true
cost: 4
estimatedHours: 8
agentType: coder
model: sonnet
parallelizable: false
dependencies: [AB1.1]

Target File: v3/src/integrations/browser/agent-browser/command-executor.ts

export class AgentBrowserCommandExecutor {
  constructor(
    private readonly sessionName?: string,
    private readonly config?: CommandExecutorConfig
  ) {}

  // Execute CLI command with output capture
  async execute(command: string, args: string[]): Promise<CommandResult>;

  // Typed command wrappers
  async open(url: string): Promise<Result<void, BrowserError>>;
  async click(target: string): Promise<Result<void, BrowserError>>;
  async fill(target: string, text: string): Promise<Result<void, BrowserError>>;
  async snapshot(options?: SnapshotOptions): Promise<Result<SnapshotResult, BrowserError>>;
  async screenshot(path?: string): Promise<Result<ScreenshotResult, BrowserError>>;
  async eval(js: string): Promise<Result<unknown, BrowserError>>;

  // Session-scoped commands automatically include --session flag
}

---

Action: AB1.3 - Create Snapshot Parser

id: AB1.3
name: CreateSnapshotParser
description: Parse snapshot output to extract element refs and structure
preconditions:
  - commandExecutorExists: true
  - snapshotParserExists: false
effects:
  - snapshotParserExists: true
cost: 3
estimatedHours: 6
agentType: coder
model: sonnet
parallelizable: true
dependencies: [AB1.2]

Target File: v3/src/integrations/browser/agent-browser/snapshot-parser.ts

export interface SnapshotElement {
  ref: string;                    // @e1, @e2, etc.
  role: string;                   // button, textbox, heading, etc.
  name?: string;                  // Accessible name
  text?: string;                  // Text content
  attributes: Record<string, string>;
  children: SnapshotElement[];
  depth: number;
}

export interface ParsedSnapshot {
  url: string;
  title: string;
  elements: SnapshotElement[];
  interactiveElements: SnapshotElement[];
  refMap: Map<string, SnapshotElement>;  // Quick lookup by ref
  timestamp: Date;
}

export class SnapshotParser {
  // Parse raw snapshot output
  parse(snapshotOutput: string): ParsedSnapshot;

  // Find element by ref
  findByRef(snapshot: ParsedSnapshot, ref: string): SnapshotElement | null;

  // Find elements by role
  findByRole(snapshot: ParsedSnapshot, role: string): SnapshotElement[];

  // Find elements by text content
  findByText(snapshot: ParsedSnapshot, text: string, exact?: boolean): SnapshotElement[];

  // Generate CSS selector from ref (for Vibium fallback)
  refToCssSelector(snapshot: ParsedSnapshot, ref: string): string | null;
}

---

Action: AB1.4 - Create Session Manager

id: AB1.4
name: CreateSessionManager
description: Manage multiple isolated browser sessions
preconditions:
  - commandExecutorExists: true
  - sessionManagerExists: false
effects:
  - sessionManagerExists: true
cost: 3
estimatedHours: 6
agentType: coder
model: sonnet
parallelizable: true
dependencies: [AB1.2]

Target File: v3/src/integrations/browser/agent-browser/session-manager.ts

export interface BrowserSessionInfo {
  name: string;
  createdAt: Date;
  lastActivity: Date;
  currentUrl?: string;
  status: 'active' | 'idle' | 'closed';
}

export class AgentBrowserSessionManager {
  private sessions: Map<string, BrowserSessionInfo>;

  // Create new isolated session
  async createSession(name?: string): Promise<Result<BrowserSessionInfo, BrowserError>>;

  // Get or create session
  async getOrCreateSession(name: string): Promise<Result<BrowserSessionInfo, BrowserError>>;

  // Close specific session
  async closeSession(name: string): Promise<Result<void, BrowserError>>;

  // Close all sessions
  async closeAllSessions(): Promise<Result<void, BrowserError>>;

  // List active sessions
  listSessions(): BrowserSessionInfo[];

  // Get executor for specific session
  getExecutor(sessionName: string): AgentBrowserCommandExecutor;
}

---

Action: AB1.5 - Create agent-browser Client Wrapper

id: AB1.5
name: CreateAgentBrowserClient
description: Full client implementing IBrowserClient interface
preconditions:
  - commandExecutorExists: true
  - snapshotParserExists: true
  - sessionManagerExists: true
  - agentBrowserClientWrapper: false
effects:
  - agentBrowserClientWrapper: true
cost: 5
estimatedHours: 10
agentType: coder
model: sonnet
parallelizable: false
dependencies: [AB1.2, AB1.3, AB1.4]

Target File: v3/src/integrations/browser/agent-browser/client.ts

export class AgentBrowserClient implements IBrowserClient {
  private executor: AgentBrowserCommandExecutor;
  private sessionManager: AgentBrowserSessionManager;
  private snapshotParser: SnapshotParser;
  private currentSnapshot: ParsedSnapshot | null = null;

  constructor(config?: AgentBrowserConfig) {}

  // IBrowserClient implementation
  async launch(options?: BrowserLaunchOptions): Promise<Result<BrowserSession, BrowserError>>;
  async quit(): Promise<Result<void, BrowserError>>;
  async isAvailable(): Promise<boolean>;

  async navigate(url: string, options?: NavigateOptions): Promise<Result<NavigateResult, BrowserError>>;

  // Element interaction with ref support
  async click(target: ElementTarget): Promise<Result<void, BrowserError>>;
  async fill(target: ElementTarget, text: string): Promise<Result<void, BrowserError>>;
  async getText(target: ElementTarget): Promise<Result<string, BrowserError>>;

  // agent-browser specific features
  async getSnapshot(options?: SnapshotOptions): Promise<Result<ParsedSnapshot, BrowserError>>;
  async findInteractiveElements(): Promise<Result<SnapshotElement[], BrowserError>>;

  // Network interception
  async mockRoute(urlPattern: string, response: MockResponse): Promise<Result<void, BrowserError>>;
  async abortRoute(urlPattern: string): Promise<Result<void, BrowserError>>;

  // Device emulation
  async setDevice(deviceName: string): Promise<Result<void, BrowserError>>;
  async setViewport(width: number, height: number): Promise<Result<void, BrowserError>>;

  // Auth state persistence
  async saveState(path: string): Promise<Result<void, BrowserError>>;
  async loadState(path: string): Promise<Result<void, BrowserError>>;

  // Trace recording
  async startTrace(): Promise<Result<void, BrowserError>>;
  async stopTrace(outputPath: string): Promise<Result<string, BrowserError>>;
}

---

Action: AB1.6 - Create Browser Client Factory

id: AB1.6
name: CreateBrowserClientFactory
description: Factory to select and create browser client based on preference
preconditions:
  - agentBrowserClientWrapper: true
  - vibiumClientWrapper: true
  - browserClientFactory: false
effects:
  - browserClientFactory: true
  - unifiedBrowserInterface: true
  - gracefulFallback: true
cost: 3
estimatedHours: 6
agentType: coder
model: sonnet
parallelizable: false
dependencies: [AB1.5]

Target File: v3/src/integrations/browser/client-factory.ts

export interface BrowserClientFactoryConfig {
  preference: BrowserToolPreference;
  fallbackEnabled: boolean;
  agentBrowserConfig?: AgentBrowserConfig;
  vibiumConfig?: VibiumConfig;
}

export class BrowserClientFactory {
  private static instance: BrowserClientFactory | null = null;

  static getInstance(config?: BrowserClientFactoryConfig): BrowserClientFactory;

  // Create client based on preference with fallback
  async createClient(
    preference?: BrowserToolPreference
  ): Promise<Result<IBrowserClient, BrowserError>>;

  // Check which tools are available
  async checkAvailability(): Promise<{
    agentBrowser: boolean;
    vibium: boolean;
  }>;

  // Get recommended tool for specific use case
  getRecommendedTool(useCase: BrowserUseCase): BrowserToolPreference;
}

export type BrowserUseCase =
  | 'e2e-testing'          // Prefer agent-browser (refs, session isolation)
  | 'visual-regression'    // Prefer vibium (simpler screenshot API)
  | 'accessibility'        // Either (both support a11y)
  | 'api-mocking'          // agent-browser only (network interception)
  | 'responsive-testing'   // agent-browser (device emulation)
  | 'auth-testing';        // agent-browser (state persistence)

---

4.2 Phase 2: Domain Integration (Week 2)

Action: AB2.1 - Integrate with visual-accessibility Domain

id: AB2.1
name: IntegrateVisualAccessibility
description: Update visual-accessibility services to use agent-browser
preconditions:
  - browserClientFactory: true
  - visualAccessibilityUsesAgentBrowser: false
effects:
  - visualAccessibilityUsesAgentBrowser: true
  - multiViewportWithRefs: true
cost: 4
estimatedHours: 8
agentType: coder
model: sonnet
parallelizable: true
dependencies: [AB1.6]

Updates to:

• v3/src/domains/visual-accessibility/services/viewport-capture.ts
• v3/src/domains/visual-accessibility/services/accessibility-tester.ts

// Enhanced viewport capture with device emulation
class ViewportCaptureService {
  constructor(
    private readonly memory: MemoryBackend,
    private readonly browserFactory: BrowserClientFactory
  ) {}

  // Use agent-browser device emulation for accurate viewport simulation
  async captureWithDeviceEmulation(
    url: string,
    devices: string[]  // ['iPhone 14', 'iPad Pro', 'Pixel 7']
  ): Promise<Result<MultiViewportCaptureResult, Error>>;
}

---

Action: AB2.2 - Integrate with test-execution Domain

id: AB2.2
name: IntegrateTestExecution
description: Update E2E runner to use agent-browser refs
preconditions:
  - browserClientFactory: true
  - testExecutionUsesAgentBrowser: false
effects:
  - testExecutionUsesAgentBrowser: true
  - e2eWithDeterministicSelection: true
cost: 5
estimatedHours: 10
agentType: coder
model: sonnet
parallelizable: true
dependencies: [AB1.6]

Updates to:

• v3/src/domains/test-execution/services/e2e-runner.ts
• v3/src/domains/test-execution/types/e2e-step.types.ts

// Add ref-based step execution
interface E2EStep {
  type: E2EStepType;
  // Support both selector and ref targets
  target?: string;           // CSS selector
  ref?: string;              // @e1, @e2 (preferred for agent-browser)
  // ...
}

// E2E runner with snapshot-based element finding
class E2ETestRunnerService {
  // Take snapshot before interaction for deterministic selection
  private async executeStepWithSnapshot(
    step: E2EStep,
    context: StepExecutionContext
  ): Promise<StepExecutionData>;

  // Use refs when available, fall back to selectors
  private resolveTarget(step: E2EStep, snapshot?: ParsedSnapshot): ElementTarget;
}

---

Action: AB2.3 - Add Network Mocking Support

id: AB2.3
name: AddNetworkMocking
description: Add API mocking capabilities for E2E tests
preconditions:
  - testExecutionUsesAgentBrowser: true
  - networkInterceptionCapable: false
effects:
  - networkInterceptionCapable: true
cost: 3
estimatedHours: 6
agentType: coder
model: sonnet
parallelizable: true
dependencies: [AB2.2]

New File: v3/src/domains/test-execution/services/network-mocker.ts

export interface NetworkMock {
  urlPattern: string;
  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | '*';
  response: MockResponse;
}

export interface MockResponse {
  status?: number;
  headers?: Record<string, string>;
  body?: unknown;
}

export class NetworkMockingService {
  constructor(private readonly client: AgentBrowserClient) {}

  // Set up mocks before test
  async setupMocks(mocks: NetworkMock[]): Promise<void>;

  // Clear all mocks
  async clearMocks(): Promise<void>;

  // Verify mock was called
  async verifyMockCalled(urlPattern: string): Promise<boolean>;
}

---

Action: AB2.4 - Add Auth State Persistence

id: AB2.4
name: AddAuthStatePersistence
description: Enable login state reuse across test runs
preconditions:
  - testExecutionUsesAgentBrowser: true
  - authStatePersistence: false
effects:
  - authStatePersistence: true
cost: 2
estimatedHours: 4
agentType: coder
model: haiku
parallelizable: true
dependencies: [AB2.2]

New File: v3/src/domains/test-execution/services/auth-state-manager.ts

export class AuthStateManager {
  private readonly stateDir = '.agentic-qe/browser-state';

  // Save authenticated state after login
  async saveAuthState(name: string, client: AgentBrowserClient): Promise<void>;

  // Load state before test to skip login
  async loadAuthState(name: string, client: AgentBrowserClient): Promise<boolean>;

  // Check if state exists and is valid
  async hasValidState(name: string): Promise<boolean>;

  // Clear expired states
  async cleanupExpiredStates(maxAgeMs?: number): Promise<void>;
}

---

4.3 Phase 3: Testing & Documentation (Week 3)

Action: AB3.1 - Write Integration Tests

id: AB3.1
name: WriteIntegrationTests
description: Test agent-browser integration with real browser
preconditions:
  - browserClientFactory: true
  - testExecutionUsesAgentBrowser: true
effects:
  - agentBrowserInstalled: true  # Tests require installation
cost: 4
estimatedHours: 8
agentType: tester
model: sonnet
parallelizable: false
dependencies: [AB2.2]

Target Files:

• v3/tests/integration/browser/agent-browser-client.test.ts
• v3/tests/integration/browser/snapshot-parser.test.ts
• v3/tests/integration/browser/session-manager.test.ts
• v3/tests/integration/browser/client-factory.test.ts

---

Action: AB3.2 - Write Unit Tests

id: AB3.2
name: WriteUnitTests
description: Unit tests for parser, executor, and types
preconditions:
  - snapshotParserExists: true
  - commandExecutorExists: true
effects:
  - (validation milestone)
cost: 3
estimatedHours: 6
agentType: tester
model: haiku
parallelizable: true
dependencies: [AB1.3, AB1.2]

Target Files:

• v3/tests/unit/integrations/browser/snapshot-parser.test.ts
• v3/tests/unit/integrations/browser/command-executor.test.ts
• v3/tests/unit/integrations/browser/types.test.ts

---

Action: AB3.3 - Create Documentation

id: AB3.3
name: CreateDocumentation
description: Document browser integration usage and patterns
preconditions:
  - browserClientFactory: true
effects:
  - (documentation milestone)
cost: 2
estimatedHours: 4
agentType: coder
model: haiku
parallelizable: true
dependencies: [AB1.6]

Target Files:

• v3/docs/integrations/browser-automation.md
• v3/docs/integrations/agent-browser-guide.md

---

5. Dependencies Graph

                        PHASE 1: Core Integration
                        =========================

    AB1.1 ─────────────────────────────────────────────────────────┐
    (Common Types)                                                  │
         │                                                          │
         ▼                                                          │
    AB1.2 ──────────────────────────────────────────────────────┐  │
    (Command Executor)                                           │  │
         │                                                       │  │
         ├─────────────────┬─────────────────┐                  │  │
         │                 │                 │                   │  │
         ▼                 ▼                 ▼                   │  │
    AB1.3             AB1.4             (Vibium Client         │  │
    (Snapshot Parser) (Session Mgr)     already done)          │  │
         │                 │                 │                   │  │
         └─────────────────┼─────────────────┘                   │  │
                           │                                     │  │
                           ▼                                     │  │
                      AB1.5 ◄────────────────────────────────────┘  │
                      (agent-browser Client)                        │
                           │                                        │
                           ▼                                        │
                      AB1.6 ◄───────────────────────────────────────┘
                      (Browser Factory)
                           │
         ┌─────────────────┴─────────────────┐
         │                                   │
         ▼                                   ▼

                        PHASE 2: Domain Integration
                        ==========================

    AB2.1                               AB2.2
    (visual-accessibility)              (test-execution)
         │                                   │
         │                    ┌──────────────┼──────────────┐
         │                    │              │              │
         │                    ▼              ▼              │
         │                AB2.3          AB2.4             │
         │                (Network)      (Auth State)      │
         │                    │              │              │
         └────────────────────┴──────────────┴──────────────┘
                                     │
                                     ▼

                        PHASE 3: Testing & Docs
                        ======================

                      ┌──────────┴──────────┐
                      │                     │
                      ▼                     ▼
                  AB3.1               AB3.2            AB3.3
                  (Integration)       (Unit Tests)    (Docs)

Parallel Execution Groups

Group	Actions	Can Run In Parallel
PG1	AB1.1	Yes (independent)
PG2	AB1.2	After PG1
PG3	AB1.3, AB1.4	Yes (both depend on AB1.2)
PG4	AB2.1, AB2.2	Yes (both depend on AB1.6)
PG5	AB2.3, AB2.4	Yes (both depend on AB2.2)
PG6	AB3.1, AB3.2, AB3.3	Yes (all independent after AB2)

---

6. Agent Assignments

6.1 Claude Flow Agent Mapping

Action	Primary Agent	Model	Rationale
AB1.1	coder	haiku	Simple type definitions
AB1.2	coder	sonnet	Complex CLI wrapper logic
AB1.3	coder	sonnet	Parser with edge cases
AB1.4	coder	sonnet	Concurrency management
AB1.5	coder	sonnet	Full client implementation
AB1.6	coder	sonnet	Factory pattern with fallback
AB2.1	coder	sonnet	Domain integration
AB2.2	coder	sonnet	E2E runner enhancement
AB2.3	coder	sonnet	Network interception
AB2.4	coder	haiku	Simple state management
AB3.1	tester	sonnet	Integration tests
AB3.2	tester	haiku	Unit tests
AB3.3	coder	haiku	Documentation

6.2 AQE v3 Domain Agent Mapping

Action	QE Domain	QE Agents
AB2.1	visual-accessibility	qe-visual-tester, qe-accessibility-tester
AB2.2	test-execution	qe-test-executor, qe-parallel-executor
AB3.1	test-execution	qe-parallel-executor
AB3.2	test-generation	qe-test-architect

6.3 Swarm Configuration

# Phase 1: Core Integration (6 agents)
npx @claude-flow/cli@latest swarm init \
  --topology hierarchical \
  --max-agents 6 \
  --strategy specialized

# Phase 2-3: Domain Integration + Testing (8 agents)
npx @claude-flow/cli@latest swarm init \
  --topology hierarchical-mesh \
  --max-agents 8 \
  --strategy specialized

---

7. Memory Patterns to Store

7.1 Integration Patterns

# Store after successful integration
npx @claude-flow/cli@latest memory store \
  --key "browser-client-factory-pattern" \
  --value "Use BrowserClientFactory for tool selection. Prefer agent-browser for E2E (refs), Vibium for visual (simpler). Auto-fallback when unavailable." \
  --namespace patterns

npx @claude-flow/cli@latest memory store \
  --key "snapshot-ref-workflow" \
  --value "1. Take snapshot with -i flag. 2. Parse to get refs. 3. Use @e1, @e2 for interactions. 4. Re-snapshot after state changes." \
  --namespace patterns

npx @claude-flow/cli@latest memory store \
  --key "browser-session-isolation" \
  --value "Use AgentBrowserSessionManager for parallel E2E tests. Each session has isolated cookies, storage, history. Name sessions by test suite." \
  --namespace patterns

7.2 AQE Learning Patterns

// Store patterns for cross-agent learning
mcp__agentic-qe__memory_store({
  key: "browser-ref-vs-selector",
  value: {
    pattern: "Use refs (@e1) for agent-browser, CSS selectors for Vibium fallback",
    successRate: 0.95,
    context: ["e2e-testing", "element-selection"]
  },
  namespace: "qe-patterns"
});

mcp__agentic-qe__memory_store({
  key: "network-mocking-pattern",
  value: {
    pattern: "Mock API routes before navigation. Use urlPattern matching. Clear mocks after test.",
    tools: ["agent-browser"],
    context: ["api-testing", "e2e-testing"]
  },
  namespace: "qe-patterns"
});

---

8. Milestones

Milestone 1: Core Integration Complete (End of Week 1)

Verification	Command	Expected
agent-browser available	agent-browser --version	Version printed
Types compile	cd v3 && npm run build	No type errors
Snapshot parsing	Unit test	100% refs parsed
Session isolation	Integration test	Sessions don't share state
Client factory works	createBrowserClient('auto')	Returns client

Deliverables:

• v3/src/integrations/browser/ directory complete
• Common types for both tools
• agent-browser client wrapper
• Snapshot parser with ref extraction
• Session manager for parallel execution

Milestone 2: Domain Integration Complete (End of Week 2)

Verification	Command	Expected
Visual with device emu	captureWithDeviceEmulation()	Screenshots at device sizes
E2E with refs	Run test with @e1	Interacts correctly
Network mocking	Mock API, verify	Mock response returned
Auth state reuse	Save then load	Login persisted

Deliverables:

• visual-accessibility uses agent-browser
• test-execution uses refs
• Network mocking service
• Auth state manager

Milestone 3: Testing & Docs Complete (End of Week 3)

Verification	Command	Expected
Integration tests	npm run test:integration -- browser	All pass
Unit tests	npm run test:unit -- browser	All pass
Docs complete	Review	Comprehensive

Deliverables:

• Integration test suite
• Unit test suite
• Documentation in v3/docs/integrations/

---

9. Risk Mitigation

9.1 Technical Risks

Risk	Probability	Impact	Mitigation
agent-browser CLI not installed	Medium	High	Check availability, auto-fallback to Vibium
Snapshot format changes	Low	High	Parser abstraction, version pinning
Session cleanup failures	Medium	Medium	Automatic cleanup on exit, timeout
Chromium download in CI	Medium	Medium	Pre-cache, use --with-deps

9.2 Fallback Strategy

// BrowserClientFactory implements automatic fallback
async createClient(preference: BrowserToolPreference): Promise<Result<IBrowserClient, BrowserError>> {
  const availability = await this.checkAvailability();

  if (preference === 'agent-browser' || preference === 'auto') {
    if (availability.agentBrowser) {
      return ok(new AgentBrowserClient(this.config.agentBrowserConfig));
    }
    if (this.config.fallbackEnabled && availability.vibium) {
      console.warn('[BrowserFactory] agent-browser unavailable, falling back to Vibium');
      return ok(new VibiumClientImpl(this.config.vibiumConfig));
    }
  }

  if (preference === 'vibium' || preference === 'auto') {
    if (availability.vibium) {
      return ok(new VibiumClientImpl(this.config.vibiumConfig));
    }
  }

  return err(new BrowserError('No browser automation tool available'));
}

---

10. File Structure (Planned)

v3/src/integrations/browser/
├── index.ts                         # Unified exports
├── types.ts                         # Common browser types (IBrowserClient)
├── errors.ts                        # Common error types
├── client-factory.ts                # BrowserClientFactory
├── vibium/                          # Existing (almost done)
│   ├── index.ts
│   ├── types.ts
│   ├── client.ts
│   ├── fallback.ts
│   └── feature-flags.ts
└── agent-browser/                   # NEW
    ├── index.ts                     # Public exports
    ├── types.ts                     # agent-browser specific types
    ├── client.ts                    # AgentBrowserClient
    ├── command-executor.ts          # CLI command wrapper
    ├── snapshot-parser.ts           # Parse snapshot refs
    ├── session-manager.ts           # Multi-session handling
    └── feature-flags.ts             # Feature toggles

v3/src/domains/test-execution/services/
├── e2e-runner.ts                    # UPDATE: Add ref support
├── network-mocker.ts                # NEW: API mocking
└── auth-state-manager.ts            # NEW: Auth persistence

v3/src/domains/visual-accessibility/services/
├── viewport-capture.ts              # UPDATE: Add device emulation
└── accessibility-tester.ts          # UPDATE: Use factory

v3/tests/integration/browser/
├── agent-browser-client.test.ts     # NEW
├── snapshot-parser.test.ts          # NEW
├── session-manager.test.ts          # NEW
└── client-factory.test.ts           # NEW

v3/tests/unit/integrations/browser/
├── snapshot-parser.test.ts          # NEW
├── command-executor.test.ts         # NEW
└── types.test.ts                    # NEW

v3/docs/integrations/
├── browser-automation.md            # NEW: Overview
└── agent-browser-guide.md           # NEW: Usage guide

---

11. Execution Commands

Phase 1 Start

# Initialize swarm
npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 6

# Check for similar patterns
npx @claude-flow/cli@latest memory search --query "browser client factory pattern" --namespace patterns

# Route first task
npx @claude-flow/cli@latest hooks route --task "Create common browser types for IBrowserClient interface"

MCP Orchestration

// Initialize QE fleet
mcp__agentic-qe__fleet_init({
  topology: "hierarchical",
  maxAgents: 8,
  enabledDomains: ["test-execution", "visual-accessibility", "test-generation"]
});

// Orchestrate Phase 1
mcp__claude-flow__task_orchestrate({
  task: "Implement agent-browser integration Phase 1: Core types, command executor, snapshot parser, session manager, client wrapper, factory",
  strategy: "adaptive"
});

// Generate tests for new services
mcp__agentic-qe__test_generate_enhanced({
  sourceCode: "v3/src/integrations/browser/agent-browser/client.ts",
  testType: "integration",
  language: "typescript"
});

---

12. References

• agent-browser GitHub
• agent-browser npm
• agent-browser Documentation
• Vibium Integration Plan
• AQE v3 Domain Interface

---

Appendix A: Action Cost Summary

Phase	Actions	Total Cost	Hours
Phase 1	AB1.1-AB1.6	20	40
Phase 2	AB2.1-AB2.4	14	28
Phase 3	AB3.1-AB3.3	9	18
Total	13 actions	43	86

---

Appendix B: State Transition Table

Action	State Changes
AB1.1	commonBrowserTypes: true
AB1.2	commandExecutorExists: true
AB1.3	snapshotParserExists: true
AB1.4	sessionManagerExists: true
AB1.5	agentBrowserClientWrapper: true
AB1.6	browserClientFactory: true, unifiedBrowserInterface: true, gracefulFallback: true
AB2.1	visualAccessibilityUsesAgentBrowser: true, multiViewportWithRefs: true
AB2.2	testExecutionUsesAgentBrowser: true, e2eWithDeterministicSelection: true
AB2.3	networkInterceptionCapable: true
AB2.4	authStatePersistence: true
AB3.1	agentBrowserInstalled: true

---

Appendix C: agent-browser Command Reference

Most-used commands to wrap in TypeScript client:

Command	Purpose	Priority
open <url>	Navigate to URL	P0
snapshot -i	Get interactive elements with refs	P0
click @ref	Click element by ref	P0
fill @ref <text>	Fill input by ref	P0
type @ref <text>	Type into element	P0
get text @ref	Get element text	P0
screenshot	Capture page	P0
eval <js>	Execute JavaScript	P1
set device <name>	Device emulation	P1
network route	Mock network	P1
state save/load	Auth persistence	P1
trace start/stop	Recording	P2

Sources:

• agent-browser GitHub
• agent-browser npm
• agent-browser README