@scraminator/core

AI-Powered Playwright Automation Framework
Convert natural language instructions into executable Playwright code with step-by-step execution and intelligent error recovery.

🚀 Features

• Natural Language Processing: Convert plain English instructions into Playwright automation code
• Step-by-Step Execution: Execute workflows incrementally with real browser context
• AI-Powered Code Generation: Generate robust Playwright code using Claude AI
• Intelligent Error Recovery: Automatic retry mechanisms with AI-driven error analysis
• Context-Aware Execution: Capture and analyze page context for better automation
• Final Code Delivery: Combine all successful steps into executable Playwright code
• Comprehensive Reporting: Detailed execution results with timing and error analysis

📦 Installation

npm install @scraminator/core

Prerequisites

• Node.js 18+
• Playwright installed in your project
• Anthropic API key for AI code generation

🎯 Quick Start

import { EnhancedAIPlaywrightFramework } from '@scraminator/core';

// Initialize the framework
const framework = new EnhancedAIPlaywrightFramework({
  aiProvider: 'anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: 'claude-3-haiku-20240307',
  options: {
    headless: false,
    timeout: 30000,
  },
});

// Execute a workflow
const workflow = [
  '1. Go to https://example.com',
  '2. Click the login button',
  '3. Fill username with "testuser"',
  '4. Fill password with "testpass"',
  '5. Click submit',
];

const result = await framework.execute(workflow);

console.log('Success:', result.success);
console.log('Generated Code:', result.finalCode);

📚 API Documentation

EnhancedAIPlaywrightFramework

The main framework class for executing AI-powered Playwright workflows.

Constructor

new EnhancedAIPlaywrightFramework(config: EnhancedAIPlaywrightFrameworkConfig)

Configuration Options:

interface EnhancedAIPlaywrightFrameworkConfig {
  aiProvider: string; // AI provider (currently 'anthropic')
  apiKey: string; // API key for the AI provider
  model: string; // AI model to use
  options?: {
    maxRetries?: number; // Max retry attempts (default: 3)
    timeout?: number; // Page timeout in ms (default: 30000)
    headless?: boolean; // Browser headless mode (default: true)
    browserType?: 'chromium' | 'firefox' | 'webkit'; // Browser type
    environment?: Record<string, any>; // Environment variables
  };
}

Methods

execute(workflow, options?)

Execute a workflow step-by-step with AI code generation.

async execute(
  workflow: string | string[] | Instruction[],
  options?: any
): Promise<WorkflowResult>

Parameters:

• workflow: Workflow instructions as string, string array, or Instruction array
• options: Optional execution options

Returns:

interface WorkflowResult {
  success: boolean; // Overall success status
  steps: StepResult[]; // Individual step results
  finalCode: string; // Combined executable code
  totalDuration: number; // Total execution time
  summary: {
    totalSteps: number; // Total steps in workflow
    successfulSteps: number; // Successfully executed steps
    failedSteps: number; // Failed steps
    recoveryAttempts: number; // Total recovery attempts
  };
}

Types

Instruction

interface Instruction {
  step: number; // Step number
  action: string; // Action description
  metadata?: Record<string, any>; // Optional metadata
}

StepResult

interface StepResult {
  step: number; // Step number
  success: boolean; // Step success status
  generatedCode: string; // Generated Playwright code
  executionResult: any; // Step execution result
  error?: string; // Error message if failed
  recoveryAttempts?: number; // Number of recovery attempts
  pageContext: StepContext; // Page context at execution
  duration: number; // Step execution time
}

StepContext

interface StepContext {
  pageUrl: string; // Current page URL
  pageTitle: string; // Page title
  pageSummary: string; // AI-generated page summary
  htmlContent: string; // Cleaned HTML content
  previousSteps: Instruction[]; // Previously executed steps
  environment: Record<string, any>; // Environment variables
  timestamp: string; // Execution timestamp
}

🔧 Usage Examples

Basic Workflow Execution

import { EnhancedAIPlaywrightFramework } from '@scraminator/core';

const framework = new EnhancedAIPlaywrightFramework({
  aiProvider: 'anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: 'claude-3-haiku-20240307',
  options: {
    headless: false,
    timeout: 30000,
  },
});

const workflow = [
  '1. Navigate to https://example.com',
  '2. Find and click the "Get Started" button',
  '3. Fill the email field with "[email protected]"',
  '4. Submit the form',
];

const result = await framework.execute(workflow);

if (result.success) {
  console.log('✅ Workflow completed successfully!');
  console.log('📊 Summary:', result.summary);
  console.log('💻 Generated Code:', result.finalCode);
} else {
  console.log('❌ Some steps failed:', result.summary.failedSteps);
}

Complex Workflow with Error Handling

const complexWorkflow = [
  '1. Go to https://ecommerce-site.com',
  '2. Search for "laptop" in the search box',
  '3. Filter results by price range $500-$1000',
  '4. Sort by customer rating',
  '5. Click on the first product',
  '6. Add item to cart',
  '7. Proceed to checkout',
  '8. Fill shipping information',
];

const result = await framework.execute(complexWorkflow);

// Analyze results
result.steps.forEach((step, index) => {
  const status = step.success ? '✅' : '❌';
  console.log(`${status} Step ${step.step}: ${step.duration}ms`);

  if (!step.success) {
    console.log(`   Error: ${step.error}`);
    console.log(`   Recovery attempts: ${step.recoveryAttempts}`);
  }
});

// Save generated code
if (result.finalCode) {
  await fs.writeFile('generated-workflow.js', result.finalCode);
  console.log('💾 Generated code saved to generated-workflow.js');
}

Using Generated Code

// Import and run the generated workflow
import generatedWorkflow from './generated-workflow.js';
import { chromium } from 'playwright';

async function runGeneratedWorkflow() {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  try {
    const results = await generatedWorkflow(page);
    console.log('Workflow executed successfully:', results);
  } finally {
    await browser.close();
  }
}

runGeneratedWorkflow();

🛠️ Advanced Configuration

Custom Environment Variables

const framework = new EnhancedAIPlaywrightFramework({
  aiProvider: 'anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: 'claude-3-haiku-20240307',
  options: {
    environment: {
      baseUrl: 'https://my-app.com',
      testMode: true,
      customTimeout: 45000,
      userAgent: 'Custom User Agent',
    },
  },
});

Browser Configuration

const framework = new EnhancedAIPlaywrightFramework({
  aiProvider: 'anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: 'claude-3-haiku-20240307',
  options: {
    browserType: 'firefox', // Use Firefox
    headless: false, // Show browser window
    timeout: 60000, // 60 second timeout
  },
});

🔍 Error Recovery

The framework includes intelligent error recovery mechanisms:

1. Automatic Retry: Failed steps are automatically retried up to 3 times
2. AI Error Analysis: Errors are analyzed by AI to suggest recovery strategies
3. Context Preservation: Page context is preserved between retry attempts
4. Graceful Degradation: Workflow continues even if some steps fail

Recovery Strategies

• Retry: Attempt the same action with modified parameters
• Skip: Skip the problematic step and continue
• Alternative Approach: Try a different method to achieve the goal

📊 Monitoring and Logging

The framework provides comprehensive logging and monitoring:

// Enable detailed logging
const framework = new EnhancedAIPlaywrightFramework({
  aiProvider: 'anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: 'claude-3-haiku-20240307',
  options: {
    // Logging is enabled by default
  },
});

// Execution results include detailed metrics
const result = await framework.execute(workflow);

console.log('📈 Performance Metrics:');
console.log(`   Total Duration: ${result.totalDuration}ms`);
console.log(
  `   Average Step Time: ${result.totalDuration / result.summary.totalSteps}ms`
);
console.log(
  `   Success Rate: ${((result.summary.successfulSteps / result.summary.totalSteps) * 100).toFixed(1)}%`
);

🧪 Testing

Run the test suite:

npm test

Run tests with UI:

npm run test:ui

📝 Development

Building

npm run build

Linting

npm run lint
npm run lint:fix

Formatting

npm run format

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• Documentation: Full API Documentation
• Examples: Usage Examples
• Issues: GitHub Issues
• Discussions: GitHub Discussions

🔗 Related Projects

• Playwright - Browser automation library
• Anthropic Claude - AI model for code generation

Made with ❤️ by the Scraminator Team