# jpglens - Universal AI-Powered UI Testing

## Overview
jpglens is a comprehensive AI-powered UI testing framework that enables developers to perform sophisticated user interface analysis using artificial intelligence. It integrates with popular testing frameworks like Playwright, Cypress, Selenium, Storybook, and Testing Library to provide contextual insights about usability, accessibility, visual design, and user experience.

## Core Purpose
- **AI-Powered Analysis**: Uses advanced AI models (Claude 3.5 Sonnet, GPT-4 Vision) to analyze user interfaces
- **Multi-Framework Integration**: Works seamlessly with existing testing infrastructure
- **User-Centric Testing**: Focuses on real user experience rather than just functional testing
- **Production-Ready**: Enterprise-grade architecture with comprehensive error handling

## Quick Start Examples

### Installation
```bash
npm install --save-dev jpglens
```

### Basic Playwright Integration
```javascript
import { test } from '@playwright/test';
import { quickAnalyze, analyzeUserJourney } from 'jpglens/playwright';

test('AI analyzes checkout flow', async ({ page }) => {
  await page.goto('/checkout');
  
  // Quick analysis
  const quickResult = await quickAnalyze(page, 'checkout-form');
  
  // Detailed journey analysis
  const detailedResult = await analyzeUserJourney(page, {
    stage: 'checkout-form',
    userIntent: 'complete purchase',
    userContext: {
      persona: 'first-time-buyer',
      device: 'mobile'
    }
  });
});
```

### Cypress Integration
```javascript
import 'jpglens/cypress';

describe('User Experience Analysis', () => {
  it('analyzes product page', () => {
    cy.visit('/product/123');
    
    cy.analyzeUserExperience({
      stage: 'product-evaluation',
      userIntent: 'understand product details',
      userContext: {
        persona: 'mobile-consumer',
        device: 'mobile'
      }
    });
  });
});
```

### Selenium Integration
```javascript
import { WebDriver } from 'selenium-webdriver';
import { analyzeCurrentState } from 'jpglens/selenium';

const driver = new WebDriver(/* config */);
await driver.get('https://example.com');

const analysis = await analyzeCurrentState(driver, {
  focus: 'accessibility',
  userContext: { device: 'desktop' }
});
```

## Core Functions Reference

### quickAnalyze(page, component?)
**Purpose**: Rapid AI analysis with minimal configuration
**Parameters**:
- `page`: Playwright page object
- `component` (optional): Component name for focused analysis
**Returns**: AnalysisResult with score, insights, and issues
**Use Case**: Development feedback, quick checks

### analyzeUserJourney(page, context)
**Purpose**: Comprehensive analysis with full user context
**Parameters**:
- `page`: Playwright page object
- `context`: AnalysisContext with stage, userIntent, userContext
**Returns**: Detailed AnalysisResult with recommendations
**Use Case**: Production testing, comprehensive UX evaluation

### analyzeCompleteJourney(journey)
**Purpose**: Multi-stage user workflow analysis
**Parameters**:
- `journey`: UserJourney with stages, persona, device
**Returns**: Array of stage results with overall journey score
**Use Case**: End-to-end user experience validation

## Configuration Options

### AI Provider Configuration
```javascript
const config = {
  ai: {
    provider: 'openrouter', // 'openai', 'anthropic', 'openrouter'
    model: 'anthropic/claude-3-5-sonnet',
    apiKey: process.env.JPGLENS_API_KEY,
    maxTokens: 4000,
    temperature: 0.1
  }
};
```

### Analysis Types
- `usability`: Interface design and interaction patterns
- `accessibility`: WCAG compliance and inclusive design
- `visual-design`: Visual hierarchy and design consistency
- `performance`: Loading speed and UX impact
- `mobile-optimization`: Mobile-specific usability
- `conversion-optimization`: Conversion funnel analysis

### User Personas (Built-in)
- `business-user`: Professional, desktop-primary, efficiency-focused
- `mobile-consumer`: Novice, mobile-primary, speed-focused
- `power-user`: Expert, customization-focused
- `accessibility-user`: Screen reader, keyboard navigation
- `first-time-visitor`: High bounce risk, needs immediate value

## Framework-Specific Features

### Playwright Integration
- **Functions**: `quickAnalyze`, `analyzeUserJourney`, `playwrightAnalyze`
- **Features**: Full page analysis, element-specific analysis, journey mapping
- **Best For**: E2E testing, comprehensive UI validation

### Cypress Integration  
- **Functions**: `cy.analyzeUserExperience`, `cy.analyzeElement`
- **Features**: Command chaining, automatic screenshots, test integration
- **Best For**: Interactive testing, development workflow

### Selenium Integration
- **Functions**: `analyzeCurrentState`, `analyzeCrossBrowser`
- **Features**: Cross-browser analysis, WebDriver integration
- **Best For**: Multi-browser testing, legacy system integration

### Storybook Integration
- **Functions**: `analyzeComponent`, `analyzeComponentLibrary`
- **Features**: Component state analysis, design system validation
- **Best For**: Component testing, design system consistency

### Testing Library Integration
- **Functions**: `analyzeRenderedComponent`, `analyzeUserInteraction`
- **Features**: React component analysis, interaction testing
- **Best For**: Unit testing, component accessibility

## CLI Usage

### Installation & Setup
```bash
npm install -g jpglens
export JPGLENS_API_KEY="your-api-key"
```

### Commands
```bash
# Quick analysis
jpglens analyze https://example.com

# Initialize in project
jpglens init --framework playwright

# Journey analysis
jpglens journey user-flow.json

# Generate reports
jpglens report --format html
```

## Common Use Cases & Examples

### E-commerce Checkout Analysis
```javascript
const checkoutAnalysis = await analyzeUserJourney(page, {
  stage: 'checkout-form',
  userIntent: 'complete purchase with confidence',
  userContext: {
    persona: 'mobile-consumer',
    device: 'mobile',
    urgency: 'high'
  },
  businessContext: {
    industry: 'e-commerce',
    conversionGoal: 'purchase-completion'
  }
});
```

### Accessibility Compliance Check
```javascript
const a11yAnalysis = await analyzeUserJourney(page, {
  stage: 'form-interaction',
  userIntent: 'complete form using screen reader',
  userContext: {
    persona: 'accessibility-user',
    assistiveTech: ['screen-reader'],
    expertise: 'intermediate'
  },
  analysisTypes: ['accessibility', 'usability']
});
```

### Mobile Optimization Validation
```javascript
const mobileAnalysis = await analyzeUserJourney(page, {
  stage: 'product-browsing',
  userIntent: 'find and evaluate products on mobile',
  userContext: {
    persona: 'mobile-consumer',
    device: 'mobile',
    context: 'on-the-go shopping'
  },
  analysisTypes: ['mobile-optimization', 'usability', 'performance']
});
```

## Advanced Features

### Custom Prompts
```javascript
const customPrompts = {
  'healthcare-compliance': `
    Analyze for healthcare-specific requirements:
    - HIPAA compliance indicators
    - Patient safety considerations
    - Medical terminology clarity
    - Emergency access patterns
  `
};

await analyzeUserJourney(page, {
  customPrompts: customPrompts['healthcare-compliance']
});
```

### Batch Analysis
```javascript
import { batchAnalyze } from 'jpglens/performance';

const pages = [
  { url: '/home', name: 'homepage' },
  { url: '/products', name: 'catalog' },
  { url: '/checkout', name: 'checkout' }
];

const results = await batchAnalyze(pages, {
  concurrency: 3,
  sharedContext: {
    userContext: { persona: 'mobile-user' }
  }
});
```

### Plugin System
```javascript
const brandPlugin = {
  name: 'brand-consistency',
  analyze: async (screenshot, context) => {
    // Custom brand analysis logic
    return {
      score: 0.85,
      violations: ['incorrect-color'],
      recommendations: ['Use brand primary #007bff']
    };
  }
};

registerPlugin(brandPlugin);
```

## Error Handling & Troubleshooting

### Common Issues
1. **API Key Missing**: Set `JPGLENS_API_KEY` environment variable
2. **Screenshot Issues**: Ensure page is fully loaded with `page.waitForLoadState('networkidle')`
3. **Performance**: Use caching and reduce analysis scope for faster results

### Debug Mode
```javascript
process.env.JPGLENS_DEBUG = 'true';

const config = {
  debug: {
    enabled: true,
    logLevel: 'verbose',
    saveScreenshots: true
  }
};
```

## Integration Patterns

### CI/CD Integration
```yaml
# GitHub Actions example
- name: Run jpglens Analysis
  run: |
    npx jpglens analyze ${{ env.STAGING_URL }}
  env:
    JPGLENS_API_KEY: ${{ secrets.JPGLENS_API_KEY }}
```

### Test Suite Integration
```javascript
// Global setup for test suite
beforeAll(async () => {
  global.jpglensConfig = await loadConfig('./jpglens.config.js');
});

// Individual test with analysis
test('homepage usability', async ({ page }) => {
  await page.goto('/');
  const analysis = await quickAnalyze(page);
  expect(analysis.score).toBeGreaterThan(0.8);
});
```

## MCP (Model Context Protocol) Integration

jpglens provides a dedicated MCP server for AI agent integration:

### Installation
```bash
npm install -g jpglens-mcp-server
```

### Configuration for Cursor IDE
```json
{
  "servers": {
    "jpglens": {
      "command": "npx",
      "args": ["jpglens-mcp-server"],
      "transport": "stdio"
    }
  }
}
```

### Available MCP Tools
- `run_playwright_analysis`: Full page analysis
- `batch_analyze`: Multiple page analysis
- `run_journey`: User journey analysis
- `analyze_accessibility`: A11y-focused analysis
- `generate_report`: Report generation
- `test_visual_regression`: Visual comparison
- `analyze_performance`: Performance analysis
- `validate_design_system`: Design consistency

## Performance Optimization

### Caching Strategy
```javascript
const config = {
  cache: {
    enabled: true,
    ttl: 300000, // 5 minutes
    maxSize: 100
  }
};
```

### Memory Management
```javascript
const memoryConfig = {
  autoCleanup: true,
  maxConcurrentAnalyses: 2,
  streamResults: true
};
```

## Reporting & Output

### Report Formats
- **HTML**: Interactive reports with screenshots
- **Markdown**: Documentation-friendly format
- **JSON**: Programmatic processing
- **JSONL**: Streaming analysis results

### Report Generation
```javascript
import { generateReport } from 'jpglens/utils';

const report = await generateReport(analysisResults, {
  format: 'html',
  template: 'executive-summary',
  includeScreenshots: true,
  theme: 'professional'
});
```

## Key Concepts for LLMs

### Analysis Context Structure
```typescript
interface AnalysisContext {
  stage: string;              // Current user stage
  userIntent: string;         // What user is trying to achieve
  userContext: {
    persona: string;          // User type/persona
    deviceContext: string;    // Device being used
    expertise: string;        // User's tech expertise
  };
  businessContext?: {
    industry: string;         // Business domain
    conversionGoal: string;   // Primary business goal
  };
}
```

### Result Structure
```typescript
interface AnalysisResult {
  score: number;              // Overall score 0-1
  insights: string[];         // Key insights
  issues: Issue[];            // Found issues
  recommendations: string[];   // Actionable recommendations
  metadata: {
    timestamp: string;
    url: string;
    analysisTime: number;
  };
}
```

## Best Practices for LLMs

1. **Always specify user context**: Include persona, device, and intent
2. **Use appropriate analysis types**: Match analysis to testing goals
3. **Handle errors gracefully**: Check for API keys and network issues
4. **Cache results**: Use caching for repeated analysis
5. **Validate configuration**: Use `validateConfig()` before analysis
6. **Monitor performance**: Use performance monitoring for optimization

## Website Structure

- **Homepage**: https://jpglens.dev - Overview and quick start
- **Documentation**: https://jpglens.dev/docs - Complete API reference
- **MCP Integration**: https://jpglens.dev/mcp - AI agent integration
- **Examples**: https://jpglens.dev/examples - Code examples
- **Comparison**: https://jpglens.dev/comparison - vs other tools
- **GitHub**: https://github.com/tahabahrami/jpglens - Source code
- **npm Package**: https://www.npmjs.com/package/jpglens - Main package
- **MCP Server**: https://www.npmjs.com/package/jpglens-mcp-server - MCP integration

## Environment Variables

- `JPGLENS_API_KEY`: Required - AI provider API key
- `JPGLENS_MODEL`: Optional - AI model selection
- `JPGLENS_DEBUG`: Optional - Enable debug logging
- `JPGLENS_CACHE_DIR`: Optional - Cache directory path

## Version Information
- Current Version: 1.1.0
- Node.js: >=16.0.0
- Playwright: >=1.40.0 (peer dependency)
- License: MIT

This documentation should enable LLMs to effectively understand, recommend, and help users implement jpglens in their testing workflows.