proffesor-for-testing__agentic-qe/docs/api/trajectory-learning.md

Trajectory Learning Guide

Package: @agentic-qe/v3/adapters Source: /v3/src/adapters/trajectory-adapter.ts Integration: QEReasoningBank with HNSW indexing

Overview

The Trajectory Learning system captures browser automation sequences (trajectories) and feeds them into the QEReasoningBank for pattern learning and similarity matching. This enables the system to learn from successful test executions and suggest similar patterns for new scenarios.

---

Concepts

Trajectory

A trajectory is a sequence of browser actions with their results, timestamps, and outcome:

interface BrowserTrajectory {
  trajectoryId: string;        // Unique identifier
  workflowType: string;        // e.g., "login-flow", "checkout"
  initialUrl: string;          // Starting URL
  steps: TrajectoryStep[];     // Sequence of actions
  outcome: 'success' | 'failure';
  duration: number;            // Total duration (ms)
  metadata?: {
    viewport?: Viewport;
    userAgent?: string;
    timestamp: number;
  };
}

interface TrajectoryStep {
  stepId: string;
  action: string;              // 'navigate', 'click', 'fill', etc.
  selector?: string;           // Target element
  value?: any;                 // Input value
  result: 'success' | 'failure';
  duration: number;            // Step duration (ms)
  screenshot?: string;         // Optional screenshot path
  error?: string;              // Error message if failed
}

Pattern Types

Browser trajectories are stored as QE patterns with specialized types:

• browser-trajectory: Complete action sequence
• visual-workflow: Workflow with visual validation steps
• security-scan: Security-validated browsing pattern
• viewport-strategy: Multi-viewport testing pattern

---

Class: TrajectoryAdapter

Constructor

class TrajectoryAdapter {
  constructor(
    private readonly reasoningBank: QEReasoningBank,
    private readonly config?: TrajectoryAdapterConfig
  );
}

Configuration:

interface TrajectoryAdapterConfig {
  // Enable HNSW vector indexing
  enableHNSW?: boolean;        // Default: true

  // Maximum trajectories to store
  maxTrajectories?: number;    // Default: 10000

  // Retention period (days)
  ttlDays?: number;            // Default: 30

  // Similarity threshold (0-1)
  similarityThreshold?: number; // Default: 0.8

  // Vector embedding dimension
  embeddingDim?: number;       // Default: 384 (MiniLM)
}

---

Methods

startTrajectory()

Begin tracking a new browser trajectory.

async startTrajectory(
  context: BrowserContext
): Promise<string>

Parameters:

interface BrowserContext {
  workflowType: string;        // Type of workflow
  initialUrl: string;          // Starting URL
  viewport?: Viewport;         // Viewport configuration
  userAgent?: string;          // Browser user agent
}

Returns: Trajectory ID (string)

Example:

const adapter = new TrajectoryAdapter(reasoningBank);

const trajectoryId = await adapter.startTrajectory({
  workflowType: 'login-flow',
  initialUrl: 'https://example.com/login',
  viewport: { width: 1920, height: 1080 },
});

console.log('Started trajectory:', trajectoryId);

---

recordStep()

Record a step in the current trajectory.

async recordStep(
  trajectoryId: string,
  step: TrajectoryStep
): Promise<void>

Example:

await adapter.recordStep(trajectoryId, {
  stepId: 'step-1',
  action: 'fill',
  selector: '#username',
  value: 'user@example.com',
  result: 'success',
  duration: 150,
});

await adapter.recordStep(trajectoryId, {
  stepId: 'step-2',
  action: 'click',
  selector: 'button[type="submit"]',
  result: 'success',
  duration: 500,
});

---

completeTrajectory()

Complete a trajectory and store it in the ReasoningBank.

async completeTrajectory(
  trajectoryId: string,
  outcome: TrajectoryOutcome
): Promise<Result<string, Error>>

Parameters:

interface TrajectoryOutcome {
  success: boolean;            // Overall success
  error?: string;              // Error message if failed
  metrics?: {
    totalDuration: number;
    successfulSteps: number;
    failedSteps: number;
  };
}

Returns: Pattern ID in ReasoningBank

Example:

const result = await adapter.completeTrajectory(trajectoryId, {
  success: true,
  metrics: {
    totalDuration: 5000,
    successfulSteps: 5,
    failedSteps: 0,
  },
});

if (result.ok) {
  console.log('Trajectory stored as pattern:', result.value);
}

---

findSimilarSuccessful()

Find similar successful trajectories for a given context.

async findSimilarSuccessful(
  context: BrowserContext,
  options?: SimilaritySearchOptions
): Promise<BrowserTrajectory[]>

Parameters:

interface SimilaritySearchOptions {
  topK?: number;               // Number of results (default: 5)
  minSimilarity?: number;      // Minimum similarity (default: 0.8)
  workflowType?: string;       // Filter by workflow type
  timeWindow?: number;         // Only recent trajectories (days)
}

Returns: Array of similar successful trajectories, sorted by similarity

Example:

const similar = await adapter.findSimilarSuccessful({
  workflowType: 'login-flow',
  initialUrl: 'https://example.com/login',
}, {
  topK: 3,
  minSimilarity: 0.85,
  timeWindow: 7, // Last 7 days
});

for (const trajectory of similar) {
  console.log('Similar trajectory:', trajectory.trajectoryId);
  console.log('Success rate:', trajectory.metadata.successRate);
  console.log('Steps:', trajectory.steps.map(s => s.action));
}

---

extractActionSequences()

Extract reusable action sequences from multiple trajectories.

async extractActionSequences(
  trajectories: BrowserTrajectory[]
): Promise<ActionSequence[]>

Returns:

interface ActionSequence {
  pattern: string;             // Action pattern (e.g., "fill -> click -> wait")
  frequency: number;           // How often it appears
  successRate: number;         // Success rate (0-1)
  examples: TrajectoryStep[][];// Example step sequences
}

Example:

const trajectories = await adapter.getAllTrajectories({
  workflowType: 'login-flow',
  successOnly: true,
});

const sequences = await adapter.extractActionSequences(trajectories);

for (const seq of sequences) {
  console.log('Pattern:', seq.pattern);
  console.log('Frequency:', seq.frequency);
  console.log('Success rate:', seq.successRate);
}

// Output:
// Pattern: "fill -> fill -> click"
// Frequency: 15
// Success rate: 0.93

---

getTrajectoryStats()

Get statistics about stored trajectories.

async getTrajectoryStats(): Promise<TrajectoryStats>

Returns:

interface TrajectoryStats {
  total: number;
  successful: number;
  failed: number;
  byWorkflowType: Record<string, number>;
  avgDuration: number;
  avgStepsPerTrajectory: number;
  storageSize: number;         // Bytes
}

Example:

const stats = await adapter.getTrajectoryStats();

console.log('Total trajectories:', stats.total);
console.log('Success rate:', stats.successful / stats.total);
console.log('Avg duration:', stats.avgDuration, 'ms');
console.log('Storage:', (stats.storageSize / 1024 / 1024).toFixed(2), 'MB');

---

Integration with QEReasoningBank

Pattern Storage

Trajectories are converted to QE patterns and stored with HNSW vector indexing:

// Internal conversion (handled by TrajectoryAdapter)
const pattern: CreateQEPatternOptions = {
  patternType: 'browser-trajectory',
  name: `${trajectory.workflowType}-${trajectory.trajectoryId}`,
  description: `Browser trajectory for ${trajectory.workflowType}`,
  template: {
    type: 'trajectory',
    content: JSON.stringify(trajectory.steps),
    variables: [],
  },
  context: {
    tags: ['browser', 'trajectory', trajectory.workflowType],
    browserContext: {
      initialUrl: trajectory.initialUrl,
      workflowType: trajectory.workflowType,
    },
    metrics: {
      successRate: trajectory.outcome === 'success' ? 1.0 : 0.0,
      usageCount: 1,
      avgDuration: trajectory.duration,
    },
  },
};

await reasoningBank.storePattern(pattern);

Similarity Matching

The adapter uses HNSW indexing for fast similarity search (<100ms p95):

// Generate embedding for current context
const contextEmbedding = await embedder.embed(
  `${context.workflowType} ${context.initialUrl}`
);

// Search for similar patterns
const similar = await reasoningBank.searchPatterns({
  embedding: contextEmbedding,
  topK: 5,
  threshold: 0.8,
  filters: {
    patternType: 'browser-trajectory',
    'context.browserContext.workflowType': context.workflowType,
  },
});

---

Practical Examples

Example 1: Learning from Login Flows

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

const bank = new QEReasoningBank();
const adapter = new TrajectoryAdapter(bank);

// Test different login implementations
const sites = [
  'https://example1.com/login',
  'https://example2.com/login',
  'https://example3.com/signin',
];

for (const site of sites) {
  const trajId = await adapter.startTrajectory({
    workflowType: 'login-flow',
    initialUrl: site,
  });

  // Execute login steps
  await adapter.recordStep(trajId, {
    stepId: '1',
    action: 'fill',
    selector: 'input[name="email"]',
    value: 'user@example.com',
    result: 'success',
    duration: 100,
  });

  await adapter.recordStep(trajId, {
    stepId: '2',
    action: 'fill',
    selector: 'input[name="password"]',
    value: 'password',
    result: 'success',
    duration: 80,
  });

  await adapter.recordStep(trajId, {
    stepId: '3',
    action: 'click',
    selector: 'button[type="submit"]',
    result: 'success',
    duration: 500,
  });

  await adapter.completeTrajectory(trajId, { success: true });
}

// Now find similar patterns for a new site
const suggestions = await adapter.findSimilarSuccessful({
  workflowType: 'login-flow',
  initialUrl: 'https://newsite.com/login',
}, {
  topK: 3,
});

console.log('Suggested approach based on similar sites:');
for (const traj of suggestions) {
  console.log('Steps:', traj.steps.map(s => `${s.action}(${s.selector})`));
}

---

Example 2: Detecting Common Patterns

// Collect many trajectories
const trajectories = await adapter.getAllTrajectories({
  workflowType: 'checkout-flow',
  successOnly: true,
  limit: 100,
});

// Extract common sequences
const sequences = await adapter.extractActionSequences(trajectories);

// Identify most reliable patterns
const reliable = sequences.filter(seq => seq.successRate > 0.95);

console.log('Highly reliable patterns:');
for (const pattern of reliable) {
  console.log(`${pattern.pattern} - ${pattern.frequency} times, ${(pattern.successRate * 100).toFixed(1)}% success`);
}

// Output:
// fill -> fill -> click - 87 times, 97.2% success
// navigate -> waitFor -> fill - 65 times, 95.8% success

---

Example 3: Adaptive Test Generation

async function generateAdaptiveTest(url: string, workflowType: string) {
  const adapter = new TrajectoryAdapter(bank);

  // Find similar successful trajectories
  const similar = await adapter.findSimilarSuccessful({
    workflowType,
    initialUrl: url,
  }, {
    topK: 5,
    minSimilarity: 0.85,
  });

  if (similar.length === 0) {
    console.log('No similar trajectories found, using default approach');
    return defaultTest(url, workflowType);
  }

  // Use most successful trajectory as template
  const best = similar.sort((a, b) =>
    b.metadata.successRate - a.metadata.successRate
  )[0];

  console.log(`Using trajectory ${best.trajectoryId} as template (${(best.metadata.successRate * 100).toFixed(1)}% success rate)`);

  // Generate test based on trajectory steps
  const test = {
    name: `${workflowType} test for ${url}`,
    steps: best.steps.map(step => ({
      action: step.action,
      selector: step.selector,
      value: step.value,
    })),
  };

  return test;
}

// Usage
const test = await generateAdaptiveTest(
  'https://newapp.com/checkout',
  'checkout-flow'
);

---

Performance Considerations

Memory Usage

Storage Size	Trajectories	Memory Usage
1K	100	~50 MB
10K (default)	1,000	~500 MB
100K	10,000	~5 GB

Recommendation: For long-running systems, configure retention:

const adapter = new TrajectoryAdapter(bank, {
  maxTrajectories: 5000,
  ttlDays: 7,  // Only keep last 7 days
});

Search Performance

Operation	Latency (p95)	Method
Start trajectory	<5ms	In-memory
Record step	<10ms	In-memory
Complete trajectory	<50ms	Write to DB
Find similar (HNSW)	<100ms	Vector search
Find similar (linear)	<250ms	Brute-force

Optimization: HNSW indexing provides 2.5x speedup for similarity search.

---

Learning Feedback

Recording Outcome

// After executing a test based on trajectory suggestion
const suggested = await adapter.findSimilarSuccessful(context);
const trajectoryId = suggested[0].trajectoryId;

// Test succeeded - positive feedback
await adapter.recordFeedback(trajectoryId, {
  useful: true,
  context,
  outcome: 'success',
});

// Test failed - negative feedback
await adapter.recordFeedback(trajectoryId, {
  useful: false,
  context,
  outcome: 'failure',
  reason: 'Selector changed, pattern outdated',
});

Adaptive Scoring

The system adjusts pattern scores based on feedback:

interface FeedbackMetrics {
  totalSuggestions: number;    // How many times suggested
  successfulUses: number;      // How many times worked
  failedUses: number;          // How many times failed
  confidenceScore: number;     // Current confidence (0-1)
  lastUpdated: number;         // Timestamp
}

// Score decays over time for unused patterns
// Score increases with successful reuse
// Score decreases with failed reuse

---

Debugging

Trajectory Visualization

// Get detailed trajectory information
const trajectory = await adapter.getTrajectory(trajectoryId);

console.log('Trajectory:', trajectory.trajectoryId);
console.log('Workflow:', trajectory.workflowType);
console.log('Duration:', trajectory.duration, 'ms');
console.log('Steps:');

for (const step of trajectory.steps) {
  const icon = step.result === 'success' ? '✓' : '✗';
  console.log(`  ${icon} ${step.action} ${step.selector} (${step.duration}ms)`);
}

Pattern Analysis

// Analyze pattern effectiveness
const analysis = await adapter.analyzePattern(patternId);

console.log('Pattern effectiveness:');
console.log('  Total uses:', analysis.totalUses);
console.log('  Success rate:', (analysis.successRate * 100).toFixed(1), '%');
console.log('  Avg duration:', analysis.avgDuration, 'ms');
console.log('  Confidence:', (analysis.confidence * 100).toFixed(1), '%');
console.log('  Similar patterns:', analysis.similarPatterns.length);

---

Testing

import { describe, it, expect } from 'vitest';
import { TrajectoryAdapter } from './trajectory-adapter';
import { QEReasoningBank } from '../learning-optimization';

describe('TrajectoryAdapter', () => {
  it('should store and retrieve trajectories', async () => {
    const bank = new QEReasoningBank();
    const adapter = new TrajectoryAdapter(bank);

    const trajId = await adapter.startTrajectory({
      workflowType: 'test-flow',
      initialUrl: 'https://example.com',
    });

    await adapter.recordStep(trajId, {
      stepId: '1',
      action: 'click',
      selector: '#button',
      result: 'success',
      duration: 100,
    });

    const result = await adapter.completeTrajectory(trajId, {
      success: true,
    });

    expect(result.ok).toBe(true);

    const similar = await adapter.findSimilarSuccessful({
      workflowType: 'test-flow',
      initialUrl: 'https://example.com',
    });

    expect(similar).toHaveLength(1);
    expect(similar[0].trajectoryId).toBe(trajId);
  });
});

---

See Also

• Main Integration Guide
• QEReasoningBank Documentation
• Workflow Templates
• Pattern Learning Guide