endorphin-ai 0.3.0 → 0.4.1

package/README.md

@@ -42,7 +42,13 @@ npm install endorphin-ai
    npx endorphin run test HEALTH-001
    ```
 
-That's it! Your project is ready with a sample test, configuration, and all necessary directories.
+4. Generate an interactive HTML report:
+   ```bash
+   npx endorphin generate report
+   npx endorphin open report
+   ```
+
+That's it! Your project is ready with a sample test, configuration, all necessary directories, and beautiful HTML reporting.
 
 ### Manual Setup (Alternative)
 If you prefer manual setup:
@@ -227,6 +233,70 @@ npm run test:record
 npx endorphin run test-recorder
 ```
 
+## 📊 HTML Reports & Analytics
+
+Endorphin AI generates beautiful, interactive HTML reports that provide comprehensive insights into your test execution results.
+
+### 🚀 Quick Report Generation
+
+```bash
+# Generate a full interactive HTML report
+npx endorphin generate report
+
+# Generate a lightweight summary report
+npx endorphin generate report --summary
+
+# Open the latest report in your browser
+npx endorphin open report
+
+# Open a specific report file
+npx endorphin open report report-2025-06-22.html
+```
+
+### ✨ Report Features
+
+#### 📈 **Interactive Dashboard**
+- **Real-time Statistics**: Success rates, test counts, execution trends
+- **Visual Progress Bars**: Easy-to-understand success rate indicators
+- **Summary Cards**: Quick overview of test health
+
+#### 🔍 **Advanced Search & Filtering**
+- **Real-time Search**: Find tests by name or ID instantly
+- **Status Filtering**: Filter by passed/failed tests with one click
+- **Smart Results**: Shows "5 of 25 tests matching 'login' with status 'failed'"
+- **Keyboard Shortcuts**: `Ctrl+F` to search, `Ctrl+3` for failed tests only
+
+#### 🎯 **Detailed Test Analysis**
+- **Step-by-Step Timeline**: See exactly what happened during test execution
+- **Screenshot Galleries**: Visual debugging with click-to-zoom screenshots
+- **Interactive Modals**: Deep dive into test execution details
+- **Tool Call Tracking**: See which browser actions were performed
+
+#### ⌨️ **Productivity Features**
+- **Export to JSON**: Data-driven analysis and custom reporting
+- **Print Support**: Documentation-ready printed reports
+- **Responsive Design**: Works on desktop, tablet, and mobile
+- **Performance Optimized**: Fast loading even with large test suites
+
+### 🛠️ Report Management
+
+```bash
+# Clean up old test results (keep 10 most recent per test)
+npx endorphin cleanup results
+
+# Keep only 5 most recent results per test
+npx endorphin cleanup results 5
+
+# Clean up old report files (older than 30 days)
+npx endorphin cleanup reports
+
+# Clean up report files older than 7 days  
+npx endorphin cleanup reports 7
+```
+
+### 📖 Complete Guide
+For detailed usage instructions, advanced features, and best practices, see the **[HTML Reporter User Guide](./doc/user-guide/HTML-Reporter-Guide.md)**.
+
 ## 🏗️ Framework Architecture
 
 Endorphin AI is built with a modular, extensible architecture designed for reliability and maintainability. 
@@ -412,6 +482,145 @@ Intelligent AI-powered tools for navigation, interaction, verification, and util
 
 The framework is production-ready and provides a solid foundation for scalable browser automation testing!
 
+## 🎮 Complete CLI Reference
+
+### Core Commands
+
+#### Test Execution
+```bash
+# Run a specific test
+npx endorphin run test TEST-001
+
+# Run all tests
+npx endorphin run test all
+
+# Run tests by tag
+npx endorphin run test --tag smoke
+npx endorphin run test --tag authentication
+
+# Run tests by priority
+npx endorphin run test --priority High
+npx endorphin run test --priority Medium
+```
+
+#### Test Creation & Recording
+```bash
+# Start interactive test recorder
+npx endorphin run test-recorder
+
+# List all available tests
+npx endorphin list
+```
+
+#### Project Setup
+```bash
+# Initialize new project (recommended for new projects)
+npx endorphin init
+
+# Show help and available commands
+npx endorphin --help
+npx endorphin help
+
+# Check current version
+npx endorphin --version
+```
+
+### HTML Reports & Analytics
+
+#### Report Generation
+```bash
+# Generate full interactive HTML report
+npx endorphin generate report
+
+# Generate lightweight summary report
+npx endorphin generate report --summary
+```
+
+#### Report Management
+```bash
+# Open latest report in browser
+npx endorphin open report
+
+# Open specific report file
+npx endorphin open report report-2025-06-22.html
+npx endorphin open report summary-report.html
+```
+
+#### Cleanup Commands
+```bash
+# Clean old test results (keep 10 most recent per test)
+npx endorphin cleanup results
+
+# Keep only 5 most recent results per test
+npx endorphin cleanup results 5
+
+# Clean old report files (older than 30 days)
+npx endorphin cleanup reports
+
+# Clean report files older than 7 days
+npx endorphin cleanup reports 7
+```
+
+### Advanced Options
+
+#### Browser Configuration
+```bash
+# Use different browsers
+npx endorphin run test all --browser firefox
+npx endorphin run test all --browser webkit
+
+# Headless/headed mode
+npx endorphin run test all --no-headless
+npx endorphin run test all --headless
+
+# Custom viewport
+npx endorphin run test all --viewport 1920x1080
+npx endorphin run test all --viewport 1366x768
+```
+
+#### AI & Performance
+```bash
+# Use different AI models
+npx endorphin run test all --model gpt-4
+npx endorphin run test all --model gpt-4o-mini
+
+# Parallel execution
+npx endorphin run test all --parallel 3
+npx endorphin run test all --parallel 5
+
+# Environment selection
+npx endorphin run test all --env staging
+npx endorphin run test all --env production
+```
+
+### npm Scripts Integration
+
+Add these to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "test": "endorphin run test all",
+    "test:smoke": "endorphin run test --tag smoke",
+    "test:auth": "endorphin run test --tag authentication", 
+    "test:single": "endorphin run test",
+    "test:record": "endorphin run test-recorder",
+    "test:report": "endorphin generate report",
+    "test:summary": "endorphin generate report --summary",
+    "test:open": "endorphin open report",
+    "test:cleanup": "endorphin cleanup results"
+  }
+}
+```
+
+Then use npm scripts:
+```bash
+npm test                # Run all tests
+npm run test:smoke      # Run smoke tests
+npm run test:report     # Generate HTML report
+npm run test:open       # Open latest report
+```
+
 ## 🔄 Staying Updated
 
 ### Check Your Version

package/bin/endorphin.js

@@ -110,14 +110,19 @@ Usage:
   endorphin <command> [options]
 
 Commands:
-  init                   Initialize new project with examples
-  run test <test-id>     Run a specific test (e.g., QE-001)
-  run test all           Run all tests
-  run test --tag <tag>   Run tests by tag (e.g., authentication)
-  run test --priority <level>  Run tests by priority (High, Medium, Low)
-  run test-recorder      Start interactive test recorder
-  list                   List all available tests
-  help                   Show this help message
+  init                           Initialize new project with examples
+  run test <test-id>             Run a specific test (e.g., QE-001)
+  run test all                   Run all tests
+  run test --tag <tag>           Run tests by tag (e.g., authentication)
+  run test --priority <level>    Run tests by priority (High, Medium, Low)
+  run test-recorder              Start interactive test recorder
+  list                           List all available tests
+  generate report                Generate HTML test report
+  generate report --summary      Generate lightweight summary report
+  open report [file]             Open latest (or specific) test report in browser
+  cleanup results [count]        Clean up old test results (keep N per test, default: 10)
+  cleanup reports [days]         Clean up old report files (older than N days, default: 30)
+  help                           Show this help message
 
 Options:
   --headless             Run browser in headless mode
@@ -136,6 +141,12 @@ Examples:
   endorphin run test --priority High --env staging # Run high priority tests on staging
   endorphin run test-recorder                  # Start test recorder
   endorphin list                               # Show all available tests
+  endorphin generate report                    # Generate interactive HTML report
+  endorphin generate report --summary          # Generate lightweight summary report
+  endorphin generate report --file custom.html # Generate report with custom filename
+  endorphin open report                        # Open latest report in browser
+  endorphin cleanup results 5                  # Keep only 5 recent results per test
+  endorphin cleanup reports 7                  # Remove reports older than 7 days
 
 Configuration:
   Create endorphin.config.js in your project root for default settings
@@ -159,6 +170,18 @@ async function main() {
       process.exit(0);
     }
 
+    // Display Endorphin molecular structure for test commands
+    const command = args[0];
+    const subcommand = args[1];
+    const target = args[2];
+    
+    if (command === 'run' && (subcommand === 'test' || subcommand === 'test-recorder')) {
+      // Import ConsoleReporter and display molecular structure
+      const { ConsoleReporter } = await import('../framework/core/console-reporter.js');
+      const reporter = new ConsoleReporter();
+      reporter.displayEndorphinMolecule();
+    }
+
     // Load configuration with CLI flag overrides
     const cliFlags = parseCliFlags(args);
     const config = await getConfig({ cwd: process.cwd(), cliFlags });
@@ -168,10 +191,6 @@ async function main() {
       console.log('🔧 Loaded configuration:', JSON.stringify(config, null, 2));
     }
 
-    const command = args[0];
-    const subcommand = args[1];
-    const target = args[2];
-
     // Handle list command
     if (command === 'list') {
       console.log('📋 Available Tests:');
@@ -247,6 +266,81 @@ async function main() {
       process.exit(1);
     }
 
+    // Handle generate command
+    if (command === 'generate') {
+      if (subcommand === 'report') {
+        console.log('📊 Generating HTML test report...');
+        const { HTMLReporter } = await import('../framework/core/reporter.js');
+        const reporter = new HTMLReporter();
+        
+        const options = {};
+        
+        // Parse additional flags for report generation
+        if (args.includes('--summary')) {
+          const reportPath = await reporter.generateSummaryReport(options);
+          console.log(`✅ Summary report generated: ${reportPath}`);
+        } else {
+          // Check for custom filename
+          const fileIndex = args.indexOf('--file');
+          if (fileIndex !== -1 && args[fileIndex + 1]) {
+            options.filename = args[fileIndex + 1];
+          }
+          
+          const reportPath = await reporter.generateReport(options);
+          console.log(`🌐 Open report: ${reportPath}`);
+        }
+        process.exit(0);
+      }
+
+      console.error(`❌ Unknown generate command: ${subcommand}`);
+      console.log('Use "endorphin help" for usage information');
+      process.exit(1);
+    }
+
+    // Handle open command
+    if (command === 'open') {
+      if (subcommand === 'report') {
+        console.log('🌐 Opening latest test report...');
+        const { HTMLReporter } = await import('../framework/core/reporter.js');
+        const reporter = new HTMLReporter();
+        
+        // Check for specific report file
+        const reportPath = target || null;
+        await reporter.openReport(reportPath);
+        process.exit(0);
+      }
+
+      console.error(`❌ Unknown open command: ${subcommand}`);
+      console.log('Use "endorphin help" for usage information');
+      process.exit(1);
+    }
+
+    // Handle cleanup command
+    if (command === 'cleanup') {
+      const { HTMLReporter } = await import('../framework/core/reporter.js');
+      const reporter = new HTMLReporter();
+      
+      if (subcommand === 'results') {
+        console.log('🧹 Cleaning up old test results...');
+        const keepCount = parseInt(target) || 10;
+        const cleanup = await reporter.cleanupResults(keepCount);
+        console.log(`✅ Cleanup completed: ${cleanup.removedCount} directories removed`);
+        process.exit(0);
+      }
+      
+      if (subcommand === 'reports') {
+        console.log('🧹 Cleaning up old report files...');
+        const maxAge = parseInt(target) || 30;
+        const cleanup = await reporter.cleanupOldReports(maxAge);
+        console.log(`✅ Cleanup completed: ${cleanup.removedCount} report files removed`);
+        process.exit(0);
+      }
+
+      console.error(`❌ Unknown cleanup command: ${subcommand}`);
+      console.log('Available: cleanup results [count], cleanup reports [days]');
+      process.exit(1);
+    }
+
     console.error(`❌ Unknown command: ${command}`);
     console.log('Use "endorphin help" for usage information');
     process.exit(1);

package/examples/test-results/HEALTH-001_2025-06-22T22-39-35-383Z/summary.json

@@ -0,0 +1,13 @@
+{
+  "testName": "Framework Health Check",
+  "sessionId": "HEALTH-001",
+  "status": "FAILED",
+  "startTime": "2025-06-22T22:39:35.384Z",
+  "endTime": "2025-06-22T22:39:35.386Z",
+  "duration": 2,
+  "totalSteps": 2,
+  "successfulSteps": 1,
+  "failedSteps": 1,
+  "totalScreenshots": 0,
+  "finalResult": "The OPENAI_API_KEY environment variable is missing or empty; either provide it, or instantiate the OpenAI client with an apiKey option, like new OpenAI({ apiKey: 'My API Key' })."
+}

package/examples/test-results/HEALTH-001_2025-06-22T22-39-35-383Z/test-session.json

@@ -0,0 +1,38 @@
+{
+  "sessionId": "HEALTH-001",
+  "sessionName": "HEALTH-001_2025-06-22T22-39-35-383Z",
+  "testName": "Framework Health Check",
+  "testId": "HEALTH-001",
+  "startTime": "2025-06-22T22:39:35.384Z",
+  "endTime": "2025-06-22T22:39:35.386Z",
+  "sessionDir": "/Users/papapin777/Documents/CODE/AI/endorphin-ai/examples/test-results/HEALTH-001_2025-06-22T22-39-35-383Z",
+  "screenshotsDir": "/Users/papapin777/Documents/CODE/AI/endorphin-ai/examples/test-results/HEALTH-001_2025-06-22T22-39-35-383Z/screenshots",
+  "steps": [
+    {
+      "stepNumber": 1,
+      "timestamp": "2025-06-22T22:39:35.384Z",
+      "description": "Starting test execution: Framework Health Check",
+      "toolName": null,
+      "toolArgs": null,
+      "result": "Test ID: HEALTH-001",
+      "status": "SUCCESS",
+      "screenshots": []
+    },
+    {
+      "stepNumber": 2,
+      "timestamp": "2025-06-22T22:39:35.386Z",
+      "description": "Test execution failed",
+      "toolName": null,
+      "toolArgs": null,
+      "result": "The OPENAI_API_KEY environment variable is missing or empty; either provide it, or instantiate the OpenAI client with an apiKey option, like new OpenAI({ apiKey: 'My API Key' }).",
+      "status": "FAILED",
+      "screenshots": []
+    }
+  ],
+  "toolCalls": [],
+  "stepCounter": 2,
+  "screenshotCounter": 0,
+  "status": "FAILED",
+  "finalResult": "The OPENAI_API_KEY environment variable is missing or empty; either provide it, or instantiate the OpenAI client with an apiKey option, like new OpenAI({ apiKey: 'My API Key' }).",
+  "duration": 2
+}

package/examples/test-results/QE-001_2025-06-22T22-39-35-364Z/summary.json

@@ -0,0 +1,13 @@
+{
+  "testName": "Basic Login Test",
+  "sessionId": "QE-001",
+  "status": "FAILED",
+  "startTime": "2025-06-22T22:39:35.370Z",
+  "endTime": "2025-06-22T22:39:35.383Z",
+  "duration": 13,
+  "totalSteps": 2,
+  "successfulSteps": 1,
+  "failedSteps": 1,
+  "totalScreenshots": 0,
+  "finalResult": "The OPENAI_API_KEY environment variable is missing or empty; either provide it, or instantiate the OpenAI client with an apiKey option, like new OpenAI({ apiKey: 'My API Key' })."
+}

package/examples/test-results/QE-001_2025-06-22T22-39-35-364Z/test-session.json

@@ -0,0 +1,38 @@
+{
+  "sessionId": "QE-001",
+  "sessionName": "QE-001_2025-06-22T22-39-35-364Z",
+  "testName": "Basic Login Test",
+  "testId": "QE-001",
+  "startTime": "2025-06-22T22:39:35.370Z",
+  "endTime": "2025-06-22T22:39:35.383Z",
+  "sessionDir": "/Users/papapin777/Documents/CODE/AI/endorphin-ai/examples/test-results/QE-001_2025-06-22T22-39-35-364Z",
+  "screenshotsDir": "/Users/papapin777/Documents/CODE/AI/endorphin-ai/examples/test-results/QE-001_2025-06-22T22-39-35-364Z/screenshots",
+  "steps": [
+    {
+      "stepNumber": 1,
+      "timestamp": "2025-06-22T22:39:35.370Z",
+      "description": "Starting test execution: Basic Login Test",
+      "toolName": null,
+      "toolArgs": null,
+      "result": "Test ID: QE-001",
+      "status": "SUCCESS",
+      "screenshots": []
+    },
+    {
+      "stepNumber": 2,
+      "timestamp": "2025-06-22T22:39:35.383Z",
+      "description": "Test execution failed",
+      "toolName": null,
+      "toolArgs": null,
+      "result": "The OPENAI_API_KEY environment variable is missing or empty; either provide it, or instantiate the OpenAI client with an apiKey option, like new OpenAI({ apiKey: 'My API Key' }).",
+      "status": "FAILED",
+      "screenshots": []
+    }
+  ],
+  "toolCalls": [],
+  "stepCounter": 2,
+  "screenshotCounter": 0,
+  "status": "FAILED",
+  "finalResult": "The OPENAI_API_KEY environment variable is missing or empty; either provide it, or instantiate the OpenAI client with an apiKey option, like new OpenAI({ apiKey: 'My API Key' }).",
+  "duration": 13
+}

package/framework/core/browser-framework.js

@@ -480,10 +480,15 @@ Current Task: ${taskDescription}`;
   }
 
   async runSingleTest(test) {
-    console.log(`\n🚀 Starting test: ${test.id} - ${test.name}`);
-    console.log(`📝 Description: ${test.description}`);
-    console.log(`🎯 Priority: ${test.priority}`);
-    console.log(`🏷️ Tags: ${test.tags ? test.tags.join(', ') : 'None'}`);
+    // Only show detailed logs if not using console reporter (for backwards compatibility)
+    const useDetailedLogs = !process.env.ENDORPHIN_CONSOLE_REPORTER;
+    
+    if (useDetailedLogs) {
+      console.log(`\n🚀 Starting test: ${test.id} - ${test.name}`);
+      console.log(`📝 Description: ${test.description}`);
+      console.log(`🎯 Priority: ${test.priority}`);
+      console.log(`🏷️ Tags: ${test.tags ? test.tags.join(', ') : 'None'}`);
+    }
     
     // Create test session with detailed tracking
     this.createTestSession(test.name, test.id);
@@ -516,11 +521,15 @@ Current Task: ${taskDescription}`;
       // Finish the test session
       const session = await this.finishTestSession('SUCCESS', 'Test completed successfully');
       
-      console.log(`✅ Test ${test.id} completed successfully!`);
+      if (useDetailedLogs) {
+        console.log(`✅ Test ${test.id} completed successfully!`);
+      }
       return { success: true, session };
       
     } catch (error) {
-      console.error(`❌ Test ${test.id} failed:`, error.message);
+      if (useDetailedLogs) {
+        console.error(`❌ Test ${test.id} failed:`, error.message);
+      }
       
       this.logTestStep('Test execution failed', null, null, error.message, false);
       const session = await this.finishTestSession('FAILED', error.message);