testchimp-runner-core 0.0.33 → 0.0.35

package/plandocs/journey-id-tracking-addendum.md

@@ -0,0 +1,227 @@
+# Journey ID Tracking for Prompt-Based Explorations
+
+## Journey Identification Strategy
+
+### Test-Based Journeys
+- **Journey ID**: Test ID (from the test being executed)
+- **Journey Name**: Test name (from test metadata)
+- Journeys already exist in the database
+
+### Prompt-Based Journeys
+- **Journey ID**: UUID generated by AppExplorer when creating the journey
+- **Journey Name**: Derived from the journey focus prompt
+- Journeys must be created and stored before execution
+
+---
+
+## Implementation Changes to AppExplorer
+
+### Add Journey Creation Methods
+
+**File**: `scriptservice/workers/app-explorer.ts`
+
+Add helper methods for creating prompt-based journeys:
+
+```typescript
+/**
+ * Generate a descriptive journey name from the focus prompt
+ */
+private generateJourneyName(journeyFocusPrompt: string): string {
+  // Convert prompt to concise journey name
+  // Examples:
+  //   "Explore Dashboard and test all widgets" → "Dashboard Widgets Exploration"
+  //   "Navigate to Settings and test user profile" → "Settings User Profile Test"
+  
+  // Simple implementation: truncate and clean
+  let name = journeyFocusPrompt
+    .replace(/^(Explore|Test|Navigate to|Check|Verify)\s+/i, '')  // Remove action verbs
+    .substring(0, 80)  // Limit length
+    .trim();
+  
+  // Capitalize first letter
+  name = name.charAt(0).toUpperCase() + name.slice(1);
+  
+  return name;
+}
+
+/**
+ * Create and store a prompt-based journey in database
+ * Uses scriptservice's own journey service (ORM/repository layer)
+ */
+private async createPromptBasedJourney(
+  journeyId: string,
+  journeyName: string,
+  journeyFocusPrompt: string
+): Promise<void> {
+  try {
+    // Use scriptservice's journey service (ORM/repository)
+    // Import: import { saveJourney } from '../services/journey-service';
+    // (or whatever the actual journey service method is called in scriptservice)
+    
+    await saveJourney({
+      id: journeyId,
+      name: journeyName,
+      description: journeyFocusPrompt,  // Store the full prompt as description
+      projectId: this.task.projectId,
+      type: 'PROMPT_BASED_EXPLORATION',  // Type already exists in schema
+      explorationId: this.explorationId,  // Link to parent exploration
+      createdAt: new Date()
+    });
+    
+    logger.info(`Created prompt-based journey: ${journeyId} - ${journeyName}`);
+  } catch (error) {
+    logger.error(`Failed to create journey ${journeyId}: ${error}`);
+    throw error;
+  }
+}
+```
+
+### Update runSinglePromptBasedJourney
+
+```typescript
+/**
+ * Execute a single prompt-based journey with given focus
+ */
+private async runSinglePromptBasedJourney(
+  journeyFocusPrompt: string,
+  testDataPrompt?: string
+): Promise<void> {
+  // Generate journey ID and name for prompt-based journey
+  const journeyId = uuidv4();  // NEW: Generate UUID for this journey
+  const journeyName = this.generateJourneyName(journeyFocusPrompt);  // NEW: Derive name from prompt
+  
+  logger.info(`Creating prompt-based journey: ${journeyId} - ${journeyName}`);
+  
+  // Create and store journey in database via journey service
+  await this.createPromptBasedJourney(journeyId, journeyName, journeyFocusPrompt);
+  
+  // Create journey task
+  const task: JourneyTask = {
+    invocationId: uuidv4(),
+    invocationBatchId: this.explorationId,
+    projectId: this.task.projectId,
+    appReleaseId: this.config.webappReleaseVersion ?? "default",
+    autohealEnabled: false,
+    sessionRecordApiKey: this.task.sessionRecordApiKey,
+    ingressEndpoint: await ConfigService.get('test_service_endpoint'),
+    enableTestchimpSdkOnExec: false,
+    urlRegexToCapture: ".*",
+    playwrightConfig: this.config.playwrightConfig,
+    creditBudget: this.getCreditsForNextJourney(),
+    bugCaptureSettings: this.config.bugCaptureSettings,
+    viewportConfig: this.config.viewportConfig,
+    
+    // NEW: Journey identification for prompt-based
+    testId: journeyId,         // Use generated journey ID (as testId for compatibility)
+    testName: {                // Use generated journey name
+      suite: 'Prompt-Based Exploration',
+      name: journeyName
+    },
+    
+    // Enable journey exploration mode with focused prompt
+    journeyExplorationMode: {
+      enabled: true,
+      journeyFocusPrompt,       // Journey-specific focus
+      testDataPrompt
+    }
+  };
+  
+  // Use JourneyRunner (handles both test-based and prompt-based)
+  const runner = new JourneyRunner(
+    task,
+    this.onBugsDiscovered.bind(this),
+    this.onScreenStateVisited.bind(this),
+    // ... all other callbacks
+  );
+  
+  await runner.run();
+}
+```
+
+---
+
+## Database Schema (No Changes Needed)
+
+### Journey Entity
+
+The journey table **already supports** both test-based and prompt-based journeys (from agentservice implementation). We're simply reusing the existing structure:
+
+```typescript
+interface Journey {
+  id: string;                      // UUID (test ID for test-based, generated for prompt-based)
+  name: string;                    // Human-readable name
+  description?: string;            // Full prompt for prompt-based, test description for test-based
+  projectId: string;
+  type: 'TEST_BASED' | 'PROMPT_BASED_EXPLORATION';  // Already exists
+  createdAt: Date;
+  explorationId?: string;          // Link to parent exploration
+  // ... other existing fields
+}
+```
+
+**No schema changes required** - we'll use existing journey service (ORM/repository) that scriptservice already has.
+
+---
+
+## Flow Comparison
+
+### Test-Based Journey Flow
+
+```
+AppExplorer (test-based)
+  ↓
+  Select test from test tree
+  ↓
+  Create JourneyTask with:
+    - testId: <existing test ID>
+    - testName: <existing test name>
+    - journeyExplorationMode: disabled
+  ↓
+  JourneyRunner executes test steps
+```
+
+### Prompt-Based Journey Flow
+
+```
+AppExplorer (prompt-based)
+  ↓
+  LLM generates journey focus prompt
+  ↓
+  Generate journeyId (UUID)
+  Generate journeyName from prompt
+  ↓
+  Create & store journey via journey service (ORM)
+  ↓
+  Create JourneyTask with:
+    - testId: <generated journey ID>
+    - testName: <generated journey name>
+    - journeyExplorationMode: enabled
+    - journeyFocusPrompt: <specific focus>
+  ↓
+  JourneyRunner executes autonomously via orchestrator
+```
+
+---
+
+## Benefits of This Approach
+
+1. **Unified Tracking**: Both test-based and prompt-based journeys use the same journey table and reporting infrastructure
+2. **Traceability**: Each prompt-based journey has a unique ID for bug tracking, screen state linking, execution history
+3. **Naming Consistency**: Generated journey names are descriptive and help understand exploration progress
+4. **No Schema Changes**: Reuses existing journey infrastructure - same table, same ORM service
+5. **No Cross-Service Imports**: Uses scriptservice's own journey service (ORM layer) - no dependencies on agentservice (Python)
+6. **Consolidation**: Moves prompt-based exploration from agentservice to scriptservice using runner-core orchestrator
+7. **Code Deduplication**: Removes browser-use dependency, uses same orchestrator for both test-based and prompt-based modes
+
+---
+
+## Example Journey Names Generated
+
+| Journey Focus Prompt | Generated Journey Name |
+|---------------------|----------------------|
+| "Explore Dashboard and test all widgets" | "Dashboard and test all widgets" |
+| "Navigate to Settings and test user profile management" | "Settings and test user profile management" |
+| "Test all menu options in the navigation bar" | "all menu options in the navigation bar" |
+| "Explore admin panel features and permissions" | "admin panel features and permissions" |
+
+(The `generateJourneyName` method can be enhanced with better NLP to create more concise names)