endorphin-ai 0.9.0 → 1.0.0

package/README.md

@@ -4,15 +4,18 @@
   # 💜 ENDORPHIN
   
   ## E2E Testing Reinvented with AI
-</div>
 
 Write tests in plain English. Let AI generate, validate, and fix them
 automatically.
 
+🌐 https://endorphinai.dev
+
+</div>
+
 <div align="center">
-  <img src="./doc/images/playwright-logo.png" alt="Playwright" height="40" />
-  <span style="margin: 10px 15px; font-size: 24px; display: inline-block; vertical-align: middle;">+</span>
-  <img src="./doc/images/langchain-logo.png" alt="LangChain" height="40" />
+  <img src="./doc/images/playwright-logo.png" alt="Playwright" height="30" />
+  &nbsp;&nbsp;&nbsp;<strong>+</strong>&nbsp;&nbsp;&nbsp;
+  <img src="./doc/images/langchain-logo.png" alt="LangChain" height="30" />
 </div>
 
 A powerful, modular browser automation framework using AI-powered testing with
@@ -34,6 +37,38 @@ comprehensive test management.
     📊 Explore beautiful HTML reports with screenshots<br />
     ⚡ From setup to test execution in 10 minutes
   </p>
+  <p style="margin-top: 20px;">
+    <a href="https://endorphinai.dev" style="color: #007bff; text-decoration: none; font-size: 18px; font-weight: bold;">
+      🌐 Visit our website for more examples and tutorials
+    </a>
+  </p>
+</div>
+
+---
+
+## 🌐 Read in Your Language
+
+<div align="center">
+  <a href="doc/languages/ua/README-UA.md">🇺🇦 Українська</a>
+  <a href="doc/languages/de/README-DE.md">🇩🇪 Deutsch</a> • 
+  <a href="doc/languages/fr/README-FR.md">🇫🇷 Français</a> • 
+  <a href="doc/languages/es/README-ES.md">🇪🇸 Español</a> • 
+  <a href="doc/languages/it/README-IT.md">🇮🇹 Italiano</a> • 
+  <a href="doc/languages/pt/README-PT.md">🇵🇹 Português</a> • 
+  <a href="doc/languages/ja/README-JA.md">🇯🇵 日本語</a> • 
+  <a href="doc/languages/ko/README-KO.md">🇰🇷 한국어</a> • 
+  <a href="doc/languages/zh/README-ZH.md">🇨🇳 中文</a> • 
+  <a href="doc/languages/tr/README-TR.md">🇹🇷 Türkçe</a> • 
+  <a href="doc/languages/nl/README-NL.md">🇳🇱 Nederlands</a> • 
+  <a href="doc/languages/sv/README-SV.md">🇸🇪 Svenska</a> • 
+  <a href="doc/languages/no/README-NO.md">🇳🇴 Norsk</a> • 
+  <a href="doc/languages/da/README-DA.md">🇩🇰 Dansk</a> • 
+  <a href="doc/languages/fi/README-FI.md">🇫🇮 Suomi</a> • 
+  <a href="doc/languages/pl/README-PL.md">🇵🇱 Polski</a> • 
+  <a href="doc/languages/ar/README-AR.md">🇸🇦 العربية</a> • 
+  <a href="doc/languages/he/README-HE.md">🇮🇱 עברית</a> • 
+  <a href="doc/languages/id/README-ID.md">🇮🇩 Indonesia</a> • 
+  
 </div>
 
 ---
@@ -95,6 +130,10 @@ npx endorphin-ai generate report && npx endorphin-ai open report
 - Interactive HTML reports with screenshots
 - Complete project structure for scaling
 
+### 🎬 Demo Video
+
+https://github.com/user-attachments/assets/166b27d5-5da8-4aab-baaa-6924435f07a9
+
 ### 🔧 Troubleshooting Installation
 
 If `npx endorphin-ai` doesn't work, try these **guaranteed solutions**:
@@ -121,6 +160,17 @@ endorphin-ai init
 resolution, not a problem with Endorphin AI. The npm scripts above always work
 regardless of npx behavior.
 
+**Alternative npm scripts in package.json:**
+```json
+{
+  "scripts": {
+    "endorphin:init": "./node_modules/.bin/endorphin init",
+    "endorphin:version": "./node_modules/.bin/endorphin --version",
+    "endorphin:help": "./node_modules/.bin/endorphin --help"
+  }
+}
+```
+
 ### Manual Setup (Alternative)
 
 If you prefer manual setup:
@@ -168,9 +218,11 @@ If you prefer manual setup:
      priority: 'High',
      tags: ['authentication', 'login', 'smoke'],
      site: 'https://qafromla.herokuapp.com/',
-     testData: {
-       originalEmail: 'papapin888@gmail.com',
-       originalPassword: 'lalalend',
+     data: async () => {
+       return {
+         originalEmail: 'papapin888@gmail.com',
+         originalPassword: 'lalalend',
+       };
      },
      task: `Navigate to https://qafromla.herokuapp.com/. 
      Click on "Log In" button. Wait 2 seconds for page load. 
@@ -210,18 +262,25 @@ If you prefer manual setup:
 ### 📊 Beautiful Reports
 
 - **Interactive HTML reports** with screenshots and step-by-step execution
+- **Cost & token tracking** - Monitor AI usage and optimize expenses
+- **AI decision history** - See exactly how AI analyzes and executes tests
 - **Real-time filtering and search** to quickly find issues
 - **Visual debugging** with click-to-zoom screenshots
 - **Export capabilities** for sharing with your team
 
+### 🎬 Report Demo
+
+https://github.com/user-attachments/assets/83a900c6-9279-496d-bc12-f16fb98cf6dc
+
 ### 🛠️ Developer Experience
 
 - **Zero configuration** - Works out of the box
 - **TypeScript support** with full type definitions
-- **Custom tools** - Extend testing capabilities with your own AI-powered tools
+- **Smart test structure** - Dynamic setup, data generation, and task functions
+- **Built-in tools system** - 12 comprehensive automation tools included
+- **VS Code debugging** - Professional debugging with debug object access
 - **Multiple browsers** - Chrome, Firefox, Safari support
-- **Parallel execution** for faster test runs
-- **Hot reload** for rapid test development
+- **Sequential execution** for reliable test runs
 
 ### 🎮 Interactive Tools
 
@@ -234,7 +293,7 @@ If you prefer manual setup:
 
 ## 🔄 Staying Updated
 
-### Current Version: v0.8.0
+### Current Version: v0.9.0
 
 ```bash
 # Check your current version
@@ -247,16 +306,18 @@ npm update endorphin-ai
 npx endorphin-ai --help
 ```
 
-### What's New in v0.8.0
+### What's New in v0.9.0
 
-- ✅ **Custom Tools Support** - Extend testing capabilities with your own
-  AI-powered tools
-- ✅ **CLI Tool Management** - Create, validate, and list custom tools
-- ✅ **Template System** - Quick tool creation with built-in templates (basic,
-  API, UI)
-- ✅ **Comprehensive Error Handling** - Robust error classification and recovery
-- ✅ **Auto-Discovery** - Automatic tool loading with detailed validation
-- ✅ **TypeScript-First** - Full type safety and IntelliSense for custom tools
+- ✅ **Smart Test Structure** - New async `setup()`, `data()`, and `task()`
+  functions for dynamic test preparation
+- ✅ **Enhanced HTML Reports** - Interactive reports with cost tracking and AI
+  decision history
+- ✅ **Cost & Token Tracking** - Monitor AI usage costs per test and per step
+- ✅ **AI Decision History** - See exactly how AI analyzes and executes tests
+- ✅ **Built-in Tools System** - 12 comprehensive browser automation tools (no
+  custom tools needed)
+- ✅ **Professional Debugging** - VS Code integration with debug object access
+- ✅ **CI/CD Ready** - Ready-to-use GitHub Actions workflows included
 
 ## 🚀 Project Initialization
 
@@ -316,9 +377,6 @@ npx endorphin-ai init
 
 # What gets created:
 # ├── tests/sample-test.ts     # Ready-to-run TypeScript test
-# ├── tools/                   # Custom tools directory
-# │   ├── jsonplaceholder-api.ts # Working API tool example
-# │   └── README.md            # Custom tools documentation
 # ├── .env                     # API key configuration
 # ├── endorphin.config.ts      # Framework settings (TypeScript)
 # ├── tsconfig.json            # TypeScript configuration
@@ -421,22 +479,6 @@ npx endorphin open report report-2025-06-22.html
 - **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
@@ -448,7 +490,7 @@ Endorphin AI is built with a modular, extensible architecture designed for
 reliability and maintainability.
 
 📖
-**[View detailed Framework Architecture documentation](./doc/Framework-Architecture.md)**
+**[View detailed Framework Architecture documentation](./doc/framework-development/Framework-Architecture.md)**
 
 ### Key Components
 
@@ -502,7 +544,7 @@ npm run test:single QE-001 -- --no-headless
 npx endorphin run test all --browser firefox
 npx endorphin run test QE-001 --no-headless
 npx endorphin run test all --viewport 1920x1080
-npx endorphin run test all --parallel 3
+npx endorphin run test all
 npx endorphin run test all --model gpt-4
 npx endorphin run test all --env staging
 ```
@@ -554,120 +596,61 @@ export const LOGOUT_TEST: TestCase = {
 };
 ```
 
-## 🔧 Custom Tools
-
-Endorphin AI supports custom tools that extend the framework's capabilities with
-your own AI-powered functionality.
-
-### 🚀 Quick Start with Custom Tools
-
-When you run `npx endorphin-ai init`, you automatically get a working custom
-tool example:
-
-```bash
-npx endorphin-ai init
-# Creates tools/jsonplaceholder-api.ts - a working API testing tool
-```
-
-### 📝 Creating Custom Tools
-
-Use the CLI to create new tools from templates:
+## 🔧 Smart Test Structure (v0.9.0)
 
-```bash
-# Create a basic custom tool
-npx endorphin create tool my-custom-tool
-
-# Create an API testing tool
-npx endorphin create tool api-validator --template api
-
-# Create a UI automation tool
-npx endorphin create tool ui-helper --template ui
-```
-
-### ✅ Validate Your Tools
+Endorphin AI v0.9.0 introduces a powerful new test structure with async
+functions for dynamic test preparation.
 
-Ensure your custom tools work correctly:
-
-```bash
-# Validate all custom tools
-npx endorphin validate tools
-
-# List all available tools (built-in + custom)
-npx endorphin list tools
-
-# Show detailed information
-npx endorphin list tools --verbose
-```
-
-### 🛠️ Tool Development
-
-Create powerful custom tools in TypeScript:
-
-```typescript
-// tools/my-api-tool.ts
-import { z } from 'zod';
-import type { EnhancedBrowserTestFramework } from 'endorphin-ai';
-
-export function createApiTool(framework: EnhancedBrowserTestFramework) {
-  return {
-    name: 'api-validator',
-    description: 'Validate API responses and data',
-    schema: z.object({
-      endpoint: z.string().describe('API endpoint to test'),
-      method: z.enum(['GET', 'POST', 'PUT', 'DELETE']).default('GET'),
-      expectedStatus: z.number().default(200),
-    }),
-    call: async ({ endpoint, method, expectedStatus }) => {
-      framework.logTestStep(`Testing ${method} ${endpoint}`);
-
-      const response = await fetch(endpoint, { method });
-      const data = await response.json();
-
-      if (response.status !== expectedStatus) {
-        throw new Error(`Expected ${expectedStatus}, got ${response.status}`);
-      }
-
-      return {
-        status: response.status,
-        data,
-        message: `API test passed: ${method} ${endpoint}`,
-      };
-    },
-  };
-}
-```
-
-### ⚙️ Configuration
-
-Add custom tools to your `endorphin.config.ts`:
+### 🚀 New Test Format
 
 ```typescript
-// endorphin.config.ts
-import type { FrameworkConfig } from 'endorphin-ai';
+import type { TestCase } from 'endorphin-ai';
 
-const config: FrameworkConfig = {
-  // Enable custom tools from the tools directory
-  customTools: ['./tools'],
+export const SMART_TEST: TestCase = {
+  id: 'LOGIN-001',
+  name: 'User Login Test',
+  description: 'Test login with generated credentials',
+  priority: 'High',
+  tags: ['auth', 'smoke'],
+
+  // Generate test data dynamically
+  data: async () => {
+    const timestamp = Date.now();
+    return {
+      email: `testuser${timestamp}@example.com`,
+      password: 'SecurePassword123!',
+      firstName: 'Test',
+      lastName: 'User',
+    };
+  },
 
-  // Or specify individual files
-  customTools: [
-    './tools/api-tool.ts',
-    './tools/database-tool.ts',
-    './my-custom-tools/',
-  ],
+  // Set up test environment
+  setup: async () => {
+    return {
+      baseUrl: process.env.TEST_URL || 'https://example.com',
+      startTime: new Date().toISOString(),
+    };
+  },
 
-  // Other configuration...
+  // Main test instructions using generated data
+  task: async (data, setupData) => {
+    return `
+      Navigate to ${setupData.baseUrl}/login
+      Fill email with "${data.email}"
+      Fill password with "${data.password}"
+      Click Submit button
+      Verify welcome message contains "${data.firstName}"
+    `;
+  },
 };
-
-export default config;
 ```
 
-### 📖 Custom Tools Guide
-
-For detailed documentation on creating, configuring, and using custom tools,
-see:
+### ✨ Key Benefits
 
-**[📖 Custom Tools Development Guide](./doc/Custom-Tools-Guide.md)**
+- **Dynamic Data Generation** - Create unique test data for each run
+- **Environment Setup** - Prepare test environment before execution
+- **Type Safety** - Full TypeScript support for all functions
+- **Backward Compatibility** - Old test format still works perfectly
 
 ## 📁 Project Structure
 
@@ -680,10 +663,6 @@ my-test-project/
 │   ├── login-test.ts      # Authentication tests
 │   ├── checkout-test.ts   # E-commerce tests
 │   └── navigation-test.ts # UI/Navigation tests
-├── tools/                  # Custom tools (optional)
-│   ├── jsonplaceholder-api.ts # API testing tool
-│   ├── database-tool.ts   # Database operations
-│   └── custom-validators.ts # Custom validation tools
 ├── endorphin.config.ts    # Optional configuration (TypeScript)
 ├── tsconfig.json          # TypeScript configuration
 └── package.json           # Project config
@@ -703,10 +682,11 @@ export const QE001: TestCase = {
   priority: 'High', // High, Medium, Low
   tags: ['authentication', 'login', 'smoke'], // Categories
   site: 'https://example.com/', // Target website
-  testData: {
-    // Test data (optional, fully typed)
-    email: 'test@example.com',
-    password: 'password123',
+  data: async () => {
+    return {
+      email: 'test@example.com',
+      password: 'password123',
+    };
   },
   task: `Your test instructions in plain English...`,
 };
@@ -769,53 +749,6 @@ Create tests on-the-fly with guided prompts:
 - Login test automation
 - Content verification
 
-## 🔍 Browser Automation Tools
-
-Intelligent AI-powered tools for navigation, interaction, verification, and
-utilities.
-
-📖
-**[View detailed tool documentation](./doc/Framework-Architecture.md#browser-automation-tools)**
-
----
-
-## 💡 Common Use Cases
-
-### 🔐 Authentication Testing
-
-```bash
-# Test login flows across different user types
-npx endorphin run test --tag authentication
-```
-
-### 🛒 E-commerce Workflows
-
-```bash
-# Test complete purchase flows
-npx endorphin run test --tag checkout
-```
-
-### 📱 Responsive Testing
-
-```bash
-# Test mobile, tablet, and desktop layouts
-npx endorphin run test --tag responsive
-```
-
-### 🔍 Search & Navigation
-
-```bash
-# Test site search and menu navigation
-npx endorphin run test --tag navigation
-```
-
-### 📊 Form Validation
-
-```bash
-# Test form submissions and validation
-npx endorphin run test --tag forms
-```
-
 ---
 
 ## 🏆 Why Choose Endorphin AI?
@@ -840,186 +773,6 @@ npx endorphin run test --tag forms
 ✅ **Type Safe**: Full TypeScript support  
 ✅ **Extensible**: Modular architecture for custom needs
 
-## 🎮 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
-```
-
-#### Custom Tools Management
-
-```bash
-# Create a new custom tool
-npx endorphin create tool my-tool
-npx endorphin create tool api-tool --template api
-npx endorphin create tool ui-tool --template ui
-
-# Validate all custom tools
-npx endorphin validate tools
-
-# List all tools (built-in + custom)
-npx endorphin list tools
-npx endorphin list tools --verbose
-```
-
-#### Project Setup
-
-```bash
-# Initialize new project (recommended for new projects)
-npx endorphin-ai init
-
-# Show help and available commands
-npx endorphin-ai --help
-npx endorphin help
-
-# Check current version
-npx endorphin-ai --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",
-    "tools:create": "endorphin create tool",
-    "tools:validate": "endorphin validate tools",
-    "tools:list": "endorphin list tools",
-    "endorphin:init": "./node_modules/.bin/endorphin-ai init",
-    "endorphin:version": "./node_modules/.bin/endorphin --version",
-    "endorphin:help": "./node_modules/.bin/endorphin --help"
-  }
-}
-```
-
-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
-
-# Custom tools management:
-npm run tools:create my-tool  # Create new tool
-npm run tools:validate # Validate all tools
-npm run tools:list     # List all tools
-
-# Guaranteed to work (bypasses npx issues):
-npm run endorphin:init  # Initialize project
-npm run endorphin:version # Check version
-npm run endorphin:help  # Get help
-```
-
 ## 🔄 Staying Updated
 
 ### Check Your Version
@@ -1050,7 +803,9 @@ npx endorphin-ai --version
 
 ### Version History & Features
 
-- **v0.8.0** _(Latest)_: Custom tools support with CLI management and templates
+- **v0.9.0** _(Latest)_: Smart test structure, enhanced HTML reports with cost
+  tracking, AI decision history, built-in tools system
+- **v0.8.0**: Custom tools support with CLI management and templates
 - **v0.6.1**: Fixed npx resolution issues, enhanced user experience
 - **v0.6.0**: Enhanced CLI, security-first publishing, cross-platform CI/CD
 - **v0.5.0**: Advanced HTML reporting with interactive features
@@ -1076,13 +831,18 @@ Update with confidence - your existing tests won't break!
 
 ### 📚 Documentation
 
-- **[Quick Start Guide](./README.md)** - Get up and running quickly
-- **[Custom Tools Development Guide](./doc/Custom-Tools-Guide.md)** - Create and
-  manage custom tools
+- **[Quick Start Guide](./doc/user-guide/Quick-Start.md)** - Get up and running
+  quickly
+- **[Test Writing Tips](./doc/user-guide/Test-Writing-Tips.md)** - Enterprise &
+  small app examples
 - **[HTML Reporter Guide](./doc/user-guide/HTML-Reporter-Guide.md)** -
-  Interactive reporting
-- **[Framework Architecture](./doc/Framework-Architecture.md)** - Technical deep
-  dive
+  Interactive reporting with cost tracking
+- **[VS Code Debugging Guide](./doc/user-guide/VSCode-Debugging-Guide.md)** -
+  Professional debugging setup
+- **[CI/CD Setup Guide](./doc/user-guide/CI-CD-Setup-Guide.md)** - GitHub
+  Actions integration
+- **[Framework Architecture](./doc/framework-development/Framework-Architecture.md)** -
+  Technical deep dive
 
 ### 🐛 Issues & Feature Requests
 
@@ -1114,10 +874,11 @@ questions
 ---
 
 <div align="center">
-  <p><strong>⚡ Ready to revolutionize your testing?</strong></p>
+  <p><strong>⚡ Happy Vibetesting!</strong></p>
   <p>
     <a href="#-installation--setup">Get Started Now</a> • 
     <a href="https://youtu.be/ev_71RBO6g8?si=F9xTPSJNp36Mr1wx">Watch Demo</a> • 
-    <a href="./doc/">Documentation</a>
+    <a href="./doc/">Documentation</a> • 
+    <a href="https://endorphinai.dev">Website</a>
   </p>
 </div>