analyze_test_execution_video

Instructions

Implementation Reference

• src/types/api.ts:247-284 (schema)

  Zod input schema definition for the 'analyze_test_execution_video' MCP tool, including all parameters for video analysis configuration.

  export const AnalyzeTestExecutionVideoInputSchema = z.object({
    testId: z.number().int().positive().describe("Test ID from Zebrunner"),
    testRunId: z.number().int().positive().describe("Launch ID / Test Run ID"),
    projectKey: z.string().min(1).optional().describe("Project key (MCP, etc.)"),
    projectId: z.number().int().positive().optional().describe("Project ID (alternative to projectKey)"),
  
    // Video Analysis Options
    extractionMode: z.enum(['failure_focused', 'full_test', 'smart']).default('smart')
      .describe("Frame extraction mode: failure_focused (10 frames around failure), full_test (30 frames throughout), smart (20 frames at key moments)"),
    frameInterval: z.number().int().positive().default(5)
      .describe("Seconds between frames for full_test mode"),
    failureWindowSeconds: z.number().int().positive().default(30)
      .describe("Time window around failure to analyze (seconds)"),
  
    // Test Case Comparison
    compareWithTestCase: z.boolean().default(true)
      .describe("Compare video execution with test case steps"),
    testCaseKey: z.string().optional()
      .describe("Override test case key if different from test metadata"),
  
    // Analysis Depth
    analysisDepth: z.enum(['quick_text_only', 'standard', 'detailed']).default('standard')
      .describe("Analysis depth: quick_text_only (no frames, ~10-20s), standard (8-12 frames for failure+coverage, ~30-60s), detailed (20-30 frames with OCR, ~60-120s)"),
    includeOCR: z.boolean().default(false)
      .describe("Extract text from frames using OCR (slow, adds 2-3s per frame)"),
    analyzeSimilarFailures: z.boolean().default(true)
      .describe("Find similar failures in project (last 30 days, top 10)"),
    includeHistoricalTrends: z.boolean().default(true)
      .describe("Analyze test stability and flakiness (last 30 runs)"),
    includeLogCorrelation: z.boolean().default(true)
      .describe("Correlate frames with log timestamps"),
  
    // Output Format
    format: z.enum(['detailed', 'summary', 'jira']).default('detailed')
      .describe("Output format: detailed (full analysis), summary (condensed), jira (ticket-ready)"),
    generateVideoReport: z.boolean().default(true)
      .describe("Generate timestamped video analysis report")
  });

• src/utils/video-analysis/analyzer.ts:44-323 (helper)

  Main helper function implementing the core video analysis logic: downloads video, extracts frames, parses logs, compares with test cases, analyzes failure, generates predictions and summary.

  async analyzeTestExecutionVideo(params: VideoAnalysisParams): Promise<VideoAnalysisResult> {
    let videoPath: string | undefined;
    
    try {
      if (this.debug) {
        console.log('[VideoAnalyzer] Starting video analysis for test:', params.testId);
      }
  
      // Step 1: Fetch test details and determine project
      const { test, projectId, projectKey } = await this.fetchTestDetails(
        params.testId,
        params.testRunId,
        params.projectKey,
        params.projectId
      );
  
      if (this.debug) {
        console.log(`[VideoAnalyzer] Test: ${test.name}, Project: ${projectKey} (${projectId})`);
      }
  
      // Step 2: Get video URL and download video
      const videoInfo = await this.downloader.getVideoUrlFromTestSessions(
        params.testId,
        params.testRunId,
        projectId
      );
  
      if (!videoInfo) {
        throw new Error('No video found for this test execution');
      }
  
      const downloadResult = await this.downloader.downloadVideo(
        videoInfo.videoUrl,
        params.testId,
        videoInfo.sessionId
      );
  
      if (!downloadResult.success || !downloadResult.localPath) {
        throw new Error(downloadResult.error || 'Failed to download video');
      }
  
      videoPath = downloadResult.localPath;
  
      if (this.debug) {
        console.log(`[VideoAnalyzer] Video downloaded: ${downloadResult.duration}s, ${downloadResult.resolution}`);
      }
  
      // Step 3: Determine frame extraction strategy based on video duration
      // Note: Video length ≠ test execution time (video may start late, end early, have gaps)
      // So we extract frames throughout the video + extra at the end (where failures typically occur)
      
      let frames: any[] = [];
      
      // Determine frame extraction settings based on analysis depth
      const { shouldExtractFrames, extractionMode, includeOCR, minFrames, maxFrames } = this.getFrameExtractionSettings(params.analysisDepth);
      
      let frameExtractionError: string | undefined;
      
      if (shouldExtractFrames) {
        try {
          const videoDuration = downloadResult.duration || 0;
          
          if (this.debug) {
            console.error(`[VideoAnalyzer] Starting frame extraction: mode=smart_distributed, minFrames=${minFrames}, maxFrames=${maxFrames}, duration=${videoDuration}s`);
            console.error(`[VideoAnalyzer] Note: Extracting frames throughout video + extra frames in last 30s (where failures typically occur)`);
          }
          
          // Use test timing as hints only (not for exact frame timestamps)
          const testDurationHint = this.calculateTestDurationHint(test);
          
          frames = await this.extractor.extractFrames(
            videoPath,
            videoDuration,
            'smart', // Always use smart mode (distributed + end-focused)
            undefined, // Don't pass calculated failure timestamp - let it use end of video
            30, // Always extract extra frames in last 30 seconds
            params.frameInterval,
            includeOCR || params.includeOCR  // Allow manual override
          );
  
          // Limit frames based on analysis depth (max)
          if (frames.length > maxFrames) {
            if (this.debug) {
              console.error(`[VideoAnalyzer] Limiting frames from ${frames.length} to ${maxFrames} for ${params.analysisDepth} mode`);
            }
            frames = frames.slice(0, maxFrames);
          }
  
          if (this.debug) {
            console.error(`[VideoAnalyzer] ✅ Extracted ${frames.length} frames (${params.analysisDepth} mode)`);
          }
  
          // Enforce minimum frames for visual analysis
          if (frames.length < minFrames && minFrames > 0) {
            frameExtractionError = `Frame extraction produced only ${frames.length} frames (minimum required: ${minFrames}). Possible causes: video too short, extraction failed, or FFmpeg issues.`;
            console.error(`[VideoAnalyzer] ⚠️  ${frameExtractionError}`);
          } else if (frames.length === 0) {
            frameExtractionError = `Frame extraction completed but produced 0 frames. Possible causes: video too short, invalid timestamps, or FFmpeg extraction issues.`;
            console.error(`[VideoAnalyzer] ⚠️  ${frameExtractionError}`);
          }
        } catch (frameError: any) {
          frameExtractionError = `Frame extraction failed: ${frameError.message || frameError}`;
          console.error(`[VideoAnalyzer] ❌ ${frameExtractionError}`);
          console.error(`[VideoAnalyzer] Continuing with text-only analysis (logs, test case comparison, predictions)`);
          frames = []; // Continue with empty frames array
        }
      } else {
        if (this.debug) {
          console.error(`[VideoAnalyzer] Skipping frame extraction (${params.analysisDepth} mode)`);
        }
        frameExtractionError = `Frame extraction skipped (analysisDepth: ${params.analysisDepth})`;
      }
  
      // Step 4: Fetch logs and parse execution steps
      const logsResponse = await this.reportingClient.getTestLogsAndScreenshots(params.testRunId, params.testId, { maxPageSize: 1000 });
      const logItems = logsResponse.items.filter(item => item.kind === 'log');
      const logSteps = this.parseLogsToSteps(logItems);
  
      if (this.debug) {
        console.log(`[VideoAnalyzer] Parsed ${logSteps.length} log steps`);
      }
  
      // Step 5: Analyze failure
      // Assume failure is near the end of video (most common case)
      // Use last 30 seconds as the failure window for frame correlation
      const estimatedFailureTimestamp = Math.max(0, (downloadResult.duration || 0) - 15); // 15s before end
      const failureAnalysis = this.analyzeFailure(test, logItems, frames, estimatedFailureTimestamp);
  
      // Step 6: Compare with test cases (if enabled) WITH VISUAL VERIFICATION
      // NEW: Support for MULTIPLE test cases!
      let testCaseComparison = null;
      let multiTestCaseComparison = null;
      
      if (params.compareWithTestCase && this.comparator && test.testCases && test.testCases.length > 0) {
        // Collect ALL test case keys (not just first one!)
        const testCaseKeys: string[] = [];
        
        if (params.testCaseKey) {
          // User provided specific test case key
          testCaseKeys.push(params.testCaseKey);
        } else {
          // Use all test cases assigned to test
          for (const tc of test.testCases) {
            if (tc.testCaseId) {
              testCaseKeys.push(tc.testCaseId);
            }
          }
        }
        
        if (testCaseKeys.length > 0) {
          if (this.debug) {
            console.log(`[VideoAnalyzer] Found ${testCaseKeys.length} test case(s): ${testCaseKeys.join(', ')}`);
          }
          
          if (testCaseKeys.length === 1) {
            // Single test case - use legacy comparison
            if (this.debug) {
              console.log(`[VideoAnalyzer] Starting single test case comparison with visual verification (${frames.length} frames)`);
            }
            
            testCaseComparison = await this.comparator.compareWithTestCase(
              testCaseKeys[0],
              projectKey,
              logSteps,
              frames
            );
          } else {
            // Multiple test cases - use NEW multi-TC comparison
            if (this.debug) {
              console.log(`[VideoAnalyzer] Starting MULTI test case comparison with visual verification (${frames.length} frames)`);
            }
            
            const baseUrl = this.reportingClient['config'].baseUrl;
            multiTestCaseComparison = await this.comparator.compareWithMultipleTestCases(
              testCaseKeys,
              projectKey,
              logSteps,
              frames,
              baseUrl  // Pass baseUrl for building clickable TC URLs
            );
          }
        }
      }
  
      // Step 7: Generate prediction
      const prediction = this.predictor.predictIssueType(
        failureAnalysis,
        testCaseComparison,
        frames,
        JSON.stringify(logItems)
      );
  
      // Step 8: Build video metadata
      const videoMetadata: VideoMetadata = {
        videoUrl: videoInfo.videoUrl,
        sessionId: videoInfo.sessionId,
        sessionStart: videoInfo.sessionStart,
        sessionEnd: videoInfo.sessionEnd,
        videoDuration: downloadResult.duration || 0,
        extractedFrames: frames.length,
        videoResolution: downloadResult.resolution || 'unknown',
        downloadSuccess: true,
        localVideoPath: videoPath,
        platformName: videoInfo.platformName,
        deviceName: videoInfo.deviceName,
        status: videoInfo.status,
        frameExtractionError
      };
  
      // Step 9: Build execution flow
      const executionFlow = {
        stepsFromLogs: logSteps,
        stepsFromVideo: frames.map((f, idx) => ({
          stepNumber: idx + 1,
          timestamp: f.timestamp,
          inferredAction: f.visualAnalysis || 'Frame analysis pending',
          screenTransition: f.appState || 'Unknown',
          confidence: 'medium' as const
        })),
        correlatedSteps: logSteps.map((logStep, idx) => ({
          logStep: idx + 1,
          videoTimestamp: this.findClosestFrameTimestamp(logStep.timestamp, frames),
          match: true,
          discrepancy: undefined
        }))
      };
  
      // Step 10: Build links
      const baseUrl = this.reportingClient['config'].baseUrl;
      const links: AnalysisLinks = {
        videoUrl: videoInfo.videoUrl,
        testUrl: `${baseUrl}/tests/runs/${params.testRunId}/results/${params.testId}`,
        testCaseUrl: testCaseComparison 
          ? `${baseUrl}/tests/cases/${testCaseComparison.testCaseKey}`
          : undefined
      };
  
      // Step 11: Generate summary
      const summary = this.generateSummary(
        test,
        videoMetadata,
        prediction,
        testCaseComparison
      );
  
      // Step 12: Cleanup
      if (videoPath) {
        this.downloader.cleanupVideo(videoPath);
      }
      this.extractor.cleanupFrames(frames);
  
      if (this.debug) {
        console.log('[VideoAnalyzer] Analysis complete!');
      }
  
      return {
        videoMetadata,
        frames,
        executionFlow,
        testCaseComparison: testCaseComparison || undefined,  // Legacy: single test case
        multiTestCaseComparison: multiTestCaseComparison || undefined,  // NEW: multiple test cases
        failureAnalysis,
        prediction,
        summary,
        links
      };
  
    } catch (error) {
      if (this.debug) {
        console.error('[VideoAnalyzer] Analysis failed:', error);
      }
  
      // Cleanup on error
      if (videoPath) {
        this.downloader.cleanupVideo(videoPath);
      }
  
      throw new Error(`Video analysis failed: ${error instanceof Error ? error.message : error}`);
    }
  }