@litocodes/persona-test 1.0.0

package/.env

@@ -0,0 +1,11 @@
+# Cerebras API Configuration
+# Get your API key from: https://cloud.cerebras.ai/
+
+# Your Cerebras API Key (required)
+CEREBRAS_API_KEY=csk-fptmf5m4hxn84c3jx95yw9tce2v6yxkhpjkwjpkxd88cmrjp
+
+# Model to use (Cerebras models - very fast!)
+# Options:
+#   - llama-3.3-70b (recommended - smart and fast)
+#   - llama-3.1-8b (lightweight, fastest)
+CEREBRAS_MODEL=llama-3.3-70b

package/README.md

@@ -0,0 +1,159 @@
+# 🎭 Persona - AI-Powered User Testing Tool
+
+An automated user-testing MVP that uses AI Agents to "look" at a website (via screenshots) and behave like specific human personas.
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         PERSONA                              │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌──────────┐    ┌──────────┐    ┌──────────┐              │
+│  │  👁️ EYE   │───▶│  🧠 BRAIN │───▶│  🖐️ HAND  │              │
+│  │Playwright│    │ OpenRouter│    │ Locator  │              │
+│  │Screenshot│    │  Vision   │    │ Execute  │              │
+│  └──────────┘    └──────────┘    └──────────┘              │
+│       ▲                                  │                  │
+│       └──────────────────────────────────┘                  │
+│                    REPEAT LOOP                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+1. **The Eye**: Playwright takes a JPEG screenshot of the current page
+2. **The Brain**: Screenshot + Persona System Prompt sent to Vision LLM
+3. **The Hand**: LLM returns JSON action with visual element description
+4. **The Locator**: Playwright semantic locators find and interact with elements
+
+## 📦 Installation
+
+```bash
+# Clone or create the project
+cd Persona
+
+# Install dependencies
+npm install
+
+# Install Playwright browsers
+npx playwright install chromium
+```
+
+## ⚙️ Configuration
+
+Create a `.env` file with your OpenRouter API key:
+
+```env
+OPENAI_API_KEY=your-openrouter-api-key-here
+OPENROUTER_MODEL=google/gemini-2.0-flash-exp:free
+```
+
+Get your API key from: https://openrouter.ai/keys
+
+## 🚀 Usage
+
+```bash
+# Basic usage
+node index.js --url="https://example.com" --agent="zoomer"
+
+# With options
+node index.js --url="https://google.com" --agent="boomer" --headless
+
+# Test API connection
+node index.js --test
+
+# Show help
+node index.js --help
+```
+
+### CLI Options
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--url` | `-u` | Target website URL (required) |
+| `--agent` | `-a` | Persona to simulate (required) |
+| `--headless` | | Run browser without UI |
+| `--test` | | Test OpenRouter connection |
+| `--help` | `-h` | Show help message |
+
+## 👥 Available Personas
+
+### 🧓 Boomer (70yo)
+- Low tech literacy
+- Needs high contrast and large text
+- Quits if frustrated
+- **Goal**: Find the contact phone number
+
+### ⚡ Zoomer (20yo)
+- Extremely impatient
+- Scrolls fast, ignores instructions
+- Prefers social login
+- **Goal**: Sign up as fast as possible
+
+### 🔍 Skeptic (40yo)
+- Paranoid about privacy
+- Refuses all cookies
+- Checks Privacy Policy
+- **Goal**: Evaluate site trustworthiness
+
+### 💻 Hacker (30yo)
+- Security tester mindset
+- Probes input fields
+- Tests for SQL injection, XSS
+- **Goal**: Test inputs for vulnerabilities
+
+## 📝 How It Works
+
+1. Launch Chromium browser and navigate to target URL
+2. Take a compressed JPEG screenshot
+3. Send screenshot + persona prompt to Vision LLM
+4. LLM analyzes the page and returns a JSON action:
+   ```json
+   {
+     "action": "click",
+     "selector": "text=Sign Up",
+     "reason": "Found signup button, clicking to proceed"
+   }
+   ```
+5. Execute the action using Playwright semantic locators
+6. Repeat until goal achieved or max actions reached
+
+## 🎯 Action Types
+
+| Action | Description | Selector Format |
+|--------|-------------|-----------------|
+| `click` | Click an element | `text=Button Text` |
+| `type` | Type into input | `placeholder=Email` |
+| `scroll` | Scroll the page | `down`, `up`, `to=text` |
+| `done` | Goal achieved | N/A |
+| `quit` | Give up | N/A |
+
+## 🔧 Project Structure
+
+```
+Persona/
+├── index.js       # Main CLI entry point
+├── brain.js       # OpenRouter vision client
+├── personas.js    # Persona definitions
+├── package.json   # Dependencies
+├── .env           # API configuration
+└── README.md      # This file
+```
+
+## 🐛 Troubleshooting
+
+**"OPENAI_API_KEY not set"**
+- Create a `.env` file with your OpenRouter API key
+
+**"Element not found"**
+- The AI's selector may not match exactly
+- The element might not be visible
+- Try running with `--headless=false` to see what's happening
+
+**"Connection failed"**
+- Check your API key
+- Run `node index.js --test` to verify connection
+- Check OpenRouter status
+
+## 📄 License
+
+MIT

package/brain.js

@@ -0,0 +1,124 @@
+// brain.js - With Action History & Strict Form Flow
+// Reads last 3 actions to understand form context
+
+import OpenAI from 'openai';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+if (!process.env.CEREBRAS_API_KEY) {
+    console.error('❌ CEREBRAS_API_KEY not set');
+    process.exit(1);
+}
+
+const MODEL = process.env.CEREBRAS_MODEL || 'llama-3.3-70b';
+
+const cerebras = new OpenAI({
+    baseURL: 'https://api.cerebras.ai/v1',
+    apiKey: process.env.CEREBRAS_API_KEY
+});
+
+/**
+ * Get agent action with full history context
+ * @param {string} domMap - DOM with [BROKEN] tags
+ * @param {object} persona - Persona profile
+ * @param {Array} actionHistory - Last 3 actions [{action, id, text}]
+ */
+export async function getAgentAction(domMap, persona, actionHistory = []) {
+    // Format history as readable string
+    const historyStr = actionHistory.length > 0
+        ? actionHistory.map(h => `${h.action.toUpperCase()} [${h.id}] "${h.text}"`).join(' → ')
+        : 'None yet';
+
+    // Check if we just typed (for form flow logic)
+    const lastTyped = actionHistory.filter(h => h.action === 'type').length;
+
+    const systemPrompt = `You are a User Tester acting as: "${persona.name}".
+
+PERSONA: ${persona.behavior}
+
+GOAL: "${persona.goal}"
+
+--- RECENT HISTORY (Last 3 moves) ---
+${historyStr}
+${lastTyped > 0 ? '\n⚠️ You have already TYPED. If the form is filled, you should now CLICK a Submit/Login button!' : ''}
+
+--- CRITICAL RULES ---
+1. 🛑 NEVER click/type on elements marked [BROKEN - DO NOT USE]
+2. 📝 FORM FLOW:
+   - If you just TYPED into username/password, your NEXT action should be CLICK on a "Submit", "Login", "Create", or "Sign up" button
+   - Do NOT type into the same field twice
+3. 🔄 NO LOOPS: If your history shows the same action 2+ times, do something DIFFERENT
+4. ✅ GOAL CHECK: If PAGE CONTEXT shows your goal (phone number, success message), say "done"
+5. 😤 GIVE UP: If everything is [BROKEN] or stuck, say "quit"
+
+${domMap}
+
+Return ONLY JSON (no markdown):
+{
+  "action": "click" | "type" | "scroll" | "done" | "quit",
+  "elementId": 12,
+  "inputText": "test_user" (REQUIRED if typing),
+  "reason": "brief reason",
+  "frustration": 0-10
+}`;
+
+    try {
+        console.log('  🧠 Asking Cerebras...');
+
+        const response = await cerebras.chat.completions.create({
+            model: MODEL,
+            messages: [{ role: 'user', content: systemPrompt }],
+            max_tokens: 200,
+            temperature: 0.7
+        });
+
+        const content = response.choices[0]?.message?.content || '';
+        return parseAIResponse(content);
+
+    } catch (error) {
+        console.error('  ❌ AI Error:', error.message);
+        return { action: 'quit', reason: 'AI failed', frustration: 10 };
+    }
+}
+
+function parseAIResponse(content) {
+    let jsonStr = content.trim();
+    if (jsonStr.startsWith('```json')) jsonStr = jsonStr.slice(7);
+    else if (jsonStr.startsWith('```')) jsonStr = jsonStr.slice(3);
+    if (jsonStr.endsWith('```')) jsonStr = jsonStr.slice(0, -3);
+
+    const match = jsonStr.match(/\{[\s\S]*\}/);
+    if (match) jsonStr = match[0];
+
+    try {
+        const a = JSON.parse(jsonStr);
+        return {
+            action: a.action || 'quit',
+            elementId: parseInt(a.elementId) || null,
+            inputText: a.inputText || a.input_text || '',
+            reason: a.reason || '',
+            frustration: parseInt(a.frustration) || 0
+        };
+    } catch (e) {
+        return { action: 'quit', reason: 'Parse error', frustration: 10 };
+    }
+}
+
+export async function testConnection() {
+    console.log('🧪 Testing Cerebras...');
+    try {
+        const r = await cerebras.chat.completions.create({
+            model: MODEL,
+            messages: [{ role: 'user', content: 'Say "Brain online"' }],
+            max_tokens: 10
+        });
+        console.log('  ✅', r.choices[0]?.message?.content);
+        return true;
+    } catch (e) {
+        console.error('  ❌', e.message);
+        return false;
+    }
+}
+
+export default { getAgentAction, testConnection };

package/index.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+
+// index.js - With Memory State (History + Blacklist)
+
+import { chromium } from 'playwright';
+import minimist from 'minimist';
+import dotenv from 'dotenv';
+import { parsePage, findElementById } from './parser.js';
+import { getAgentAction, testConnection } from './brain.js';
+import { getPersona, listPersonas } from './personas.js';
+
+dotenv.config();
+
+const argv = minimist(process.argv.slice(2), {
+    string: ['url', 'agent'],
+    boolean: ['headless', 'test', 'help'],
+    default: { headless: false },
+    alias: { u: 'url', a: 'agent', h: 'help' }
+});
+
+if (argv.help) {
+    console.log(`
+🎭 PERSONA - AI User Testing (Final Version)
+
+Usage: node index.js --url="<site>" --agent="<persona>"
+Personas: ${listPersonas().join(', ')}
+`);
+    process.exit(0);
+}
+
+if (argv.test) { await testConnection(); process.exit(0); }
+if (!argv.url || !argv.agent) { console.error('❌ --url and --agent required'); process.exit(1); }
+
+const persona = getPersona(argv.agent);
+if (!persona) { console.error(`❌ Unknown: ${argv.agent}`); process.exit(1); }
+
+async function main() {
+    console.log(`
+╔══════════════════════════════════════════════════════════════╗
+║           🎭 PERSONA - AI User Testing (Final)               ║
+╚══════════════════════════════════════════════════════════════╝
+`);
+    console.log(`🎯 ${argv.url}`);
+    console.log(`👤 ${persona.name} | Goal: ${persona.goal}\n`);
+
+    const browser = await chromium.launch({ headless: argv.headless });
+    const page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
+
+    await page.goto(argv.url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+    await page.waitForTimeout(2000);
+    console.log('✅ Page loaded\n');
+
+    // 🧠 MEMORY STATE
+    const actionHistory = []; // Last 3 actions: [{action, id, text}]
+    const failedIds = [];     // Blacklisted IDs
+
+    for (let step = 1; step <= persona.maxActions; step++) {
+        console.log(`┌─ Step ${step}/${persona.maxActions} ${'─'.repeat(44)}`);
+
+        const html = await page.content();
+        const { domMap, elements, elementCount } = parsePage(html, failedIds);
+        console.log(`  📊 ${elementCount} elements (${failedIds.length} blacklisted)`);
+
+        if (elementCount === 0) {
+            console.log('  ⚠️ No elements');
+            await page.mouse.wheel(0, 300);
+            continue;
+        }
+
+        // Pass full history to brain
+        const decision = await getAgentAction(domMap, persona, actionHistory);
+
+        console.log(`  🤖 ${decision.action.toUpperCase()} [${decision.elementId}]`);
+        console.log(`  💭 ${decision.reason}`);
+        console.log(`  😤 Frustration: ${decision.frustration}/10`);
+
+        if (decision.action === 'done' || decision.action === 'quit') {
+            console.log(`\n${'═'.repeat(60)}`);
+            console.log(decision.action === 'done' ? '  🎉 GOAL ACHIEVED!' : '  😤 GAVE UP');
+            console.log(`  ${decision.reason}`);
+            console.log(`${'═'.repeat(60)}`);
+            break;
+        }
+
+        const target = decision.elementId ? findElementById(elements, decision.elementId) : null;
+
+        if (!target) {
+            console.log('  ❌ Invalid ID');
+            continue;
+        }
+
+        try {
+            const locator = page.locator(target.selector).first();
+
+            if (decision.action === 'click') {
+                await locator.click({ timeout: 4000 });
+                console.log(`  🖱️ Clicked: "${target.text}"`);
+            } else if (decision.action === 'type') {
+                const text = decision.inputText || persona.testStrings?.sql || 'test_user';
+                await locator.fill(text, { timeout: 4000 });
+                console.log(`  ⌨️ Typed: "${text}"`);
+            } else if (decision.action === 'scroll') {
+                await page.mouse.wheel(0, 400);
+                console.log('  📜 Scrolled');
+            }
+
+            // ✅ Add to history (keep last 3)
+            actionHistory.push({ action: decision.action, id: decision.elementId, text: target.text });
+            if (actionHistory.length > 3) actionHistory.shift();
+
+        } catch (e) {
+            const msg = e.message.split('\n')[0].substring(0, 50);
+            console.log(`  ⚠️ FAILED: ${msg}`);
+
+            // 🚨 Add to blacklist
+            failedIds.push(decision.elementId);
+            console.log(`  🚫 ID [${decision.elementId}] blacklisted`);
+        }
+
+        await page.waitForTimeout(2000);
+        console.log(`└${'─'.repeat(58)}┘`);
+    }
+
+    console.log('\n📋 History:', actionHistory.map(h => `${h.action}[${h.id}]`).join(' → '));
+    console.log('🚫 Blacklist:', failedIds.length ? failedIds.join(', ') : 'none');
+    await browser.close();
+    console.log('✅ Done\n');
+}
+
+main().catch(e => console.error('💀', e));

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@litocodes/persona-test",
+  "version": "1.0.0",
+  "description": "AI User Testing with Personality - Simulate real users breaking your website",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "persona": "./index.js",
+    "persona-test": "./index.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "node index.js --test",
+    "postinstall": "npx playwright install chromium"
+  },
+  "keywords": [
+    "user-testing",
+    "ai",
+    "playwright",
+    "automation",
+    "persona",
+    "qa",
+    "testing",
+    "ux"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/persona-test"
+  },
+  "dependencies": {
+    "cheerio": "^1.0.0",
+    "dotenv": "^16.4.5",
+    "minimist": "^1.2.8",
+    "openai": "^4.77.0",
+    "playwright": "^1.49.1"
+  }
+}

package/parser.js

@@ -0,0 +1,103 @@
+// parser.js - With Blacklist Support
+// Tags failed elements as [BROKEN] so AI avoids them
+
+import * as cheerio from 'cheerio';
+
+/**
+ * Parse HTML with blacklist support
+ * @param {string} html - Raw HTML
+ * @param {number[]} failedIds - IDs that previously failed
+ */
+export function parsePage(html, failedIds = []) {
+    const $ = cheerio.load(html);
+    const elements = [];
+    let idCounter = 1;
+
+    $('script, style, noscript').remove();
+
+    // 1. Context
+    let contextText = "";
+    const pageTitle = $('title').text().trim();
+    if (pageTitle) contextText += `[TITLE] ${pageTitle}\n`;
+
+    $('h1, h2, h3, p, label').each((i, el) => {
+        const text = $(el).text().trim().replace(/\s+/g, ' ');
+        if (text.length > 5 && text.length < 150) {
+            contextText += `[TEXT] ${text.substring(0, 100)}\n`;
+        }
+    });
+
+    // Phone numbers
+    const phoneRegex = /(\+?1?[-.\s]?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}|1-800-\w+-\w+)/g;
+    const phoneMatches = $('body').text().match(phoneRegex);
+    if (phoneMatches) {
+        phoneMatches.slice(0, 3).forEach(p => contextText += `[PHONE] ${p.trim()}\n`);
+    }
+
+    contextText = contextText.substring(0, 1500);
+
+    // 2. Interactive elements
+    $('button, a, input, select, textarea').each((i, el) => {
+        const $el = $(el);
+        const tagName = $el.prop('tagName')?.toLowerCase() || 'unknown';
+        const type = $el.attr('type') || '';
+
+        if (type === 'hidden') return;
+        if ($el.attr('aria-hidden') === 'true') return;
+
+        let text = $el.text().trim() ||
+            $el.attr('placeholder') ||
+            $el.attr('aria-label') ||
+            $el.attr('name') ||
+            $el.attr('value') || '';
+        text = text.replace(/\s+/g, ' ').trim();
+
+        let selector = tagName;
+        const id = $el.attr('id');
+        const name = $el.attr('name');
+        const placeholder = $el.attr('placeholder');
+
+        if (id) selector = `#${id}`;
+        else if (name) selector = `${tagName}[name="${name}"]`;
+        else if (placeholder) selector = `${tagName}[placeholder="${placeholder}"]`;
+        else if (type && tagName === 'input') selector = `input[type="${type}"]`;
+        else if (text && tagName !== 'input') selector = `${tagName}:has-text("${text.substring(0, 20)}")`;
+
+        if (!text && !id && !name && !placeholder) return;
+
+        elements.push({
+            id: idCounter++,
+            type: tagName,
+            text: text.substring(0, 50),
+            selector,
+            inputType: type
+        });
+    });
+
+    // 3. Build map with BROKEN tags
+    const interactiveMap = elements.map(el => {
+        const broken = failedIds.includes(el.id) ? ' ⚠️ [BROKEN - DO NOT USE]' : '';
+
+        if (el.type === 'input') return `[${el.id}] INPUT (${el.inputType || 'text'}): "${el.text}"${broken}`;
+        if (el.type === 'textarea') return `[${el.id}] TEXTAREA: "${el.text}"${broken}`;
+        if (el.type === 'select') return `[${el.id}] DROPDOWN: "${el.text}"${broken}`;
+        if (el.type === 'a') return `[${el.id}] LINK: "${el.text}"${broken}`;
+        return `[${el.id}] BUTTON: "${el.text}"${broken}`;
+    }).join('\n');
+
+    const domMap = `
+--- PAGE CONTEXT ---
+${contextText || '(empty)'}
+--------------------
+--- INTERACTIVE ---
+${interactiveMap || '(none)'}
+`;
+
+    return { domMap, elements, elementCount: elements.length };
+}
+
+export function findElementById(elements, id) {
+    return elements.find(el => el.id === id) || null;
+}
+
+export default { parsePage, findElementById };

package/personas.js

@@ -0,0 +1,107 @@
+/**
+ * Persona Profiles for AI-driven user testing
+ * Each persona has unique behaviors, limitations, and goals
+ * Optimized for text-based DOM parsing (no vision)
+ */
+
+export const PERSONAS = {
+    boomer: {
+        name: "Grandpa Joe",
+        age: 70,
+        behavior: `70 years old. Low tech literacy. 
+Gets confused by modern UI with too many options.
+Looking for obvious things like 'Contact', 'Help', or 'Phone'.
+Prefers simple, clear labels over icons.
+Quits if overwhelmed by too many choices.
+Never clicks on anything that seems "fancy" or unclear.`,
+        goal: "Find a phone number or contact information to call.",
+        maxActions: 10,
+        frustrationThreshold: 5
+    },
+
+    zoomer: {
+        name: "Zoomer Zoe",
+        age: 20,
+        behavior: `20 years old. Extremely impatient.
+Clicks the first interesting thing immediately.
+Ignores instructions and fine print completely.
+Prefers 'Sign Up', 'Get Started', 'Join' buttons.
+Loves social login (Google, Apple, etc).
+Gets annoyed if there are too many form fields.
+KNOWS to fill out username/password fields BEFORE clicking submit.
+Types fast with occasional typos. Uses simple usernames like "zoomer123".
+Scrolls fast, barely reads anything.`,
+        goal: "Sign up or find the most interesting thing as fast as possible.",
+        maxActions: 10,
+        frustrationThreshold: 4
+    },
+
+    skeptic: {
+        name: "Skeptical Sam",
+        age: 40,
+        behavior: `40 years old. Paranoid about privacy.
+Always looks for 'Privacy Policy' and 'Terms' links first.
+Refuses to click 'Accept Cookies' - looks for 'Reject' or 'Manage'.
+Reads the fine print before doing anything.
+Distrusts sites without clear contact info.
+Never uses social login - too much data sharing.
+Looks for security indicators and trust badges.`,
+        goal: "Find and read the Privacy Policy, reject cookies, evaluate trustworthiness.",
+        maxActions: 12,
+        frustrationThreshold: 8
+    },
+
+    hacker: {
+        name: "Hacker Harry",
+        age: 30,
+        behavior: `Security researcher mindset.
+Looks for INPUT fields to test with injection strings.
+Types test payloads like: ' OR '1'='1' --
+Also tries: <script>alert(1)</script>
+Methodically tests each input field found.
+Looks for hidden forms, admin links, or unusual endpoints.
+Very patient and thorough.`,
+        goal: "Find all input fields and test them with SQL injection strings.",
+        maxActions: 15,
+        frustrationThreshold: 10,
+        testStrings: {
+            sql: "' OR '1'='1' --",
+            xss: "<script>alert('XSS')</script>",
+            traversal: "../../etc/passwd"
+        }
+    },
+
+    explorer: {
+        name: "Explorer Emma",
+        age: 35,
+        behavior: `Curious user who wants to understand everything.
+Clicks on every main navigation link.
+Reads headings and summaries.
+Takes note of what each section contains.
+Methodically explores the entire site structure.
+Creates a mental map of the site.`,
+        goal: "Explore the entire site and understand its structure.",
+        maxActions: 20,
+        frustrationThreshold: 15
+    }
+};
+
+/**
+ * Get a persona by name (case-insensitive)
+ * @param {string} name - The persona name
+ * @returns {object|null} The persona object or null if not found
+ */
+export function getPersona(name) {
+    const key = name.toLowerCase();
+    return PERSONAS[key] || null;
+}
+
+/**
+ * List all available persona names
+ * @returns {string[]} Array of persona names
+ */
+export function listPersonas() {
+    return Object.keys(PERSONAS);
+}
+
+export default PERSONAS;