Get Started

npm install personaspec @playwright/test
npx playwright install chromium

npx personaspec init

npx playwright test

npx personaspec report test-results/alex-observations.json

import { test } from '@playwright/test';
import { ObservationCollector, definePersona } from 'personaspec';

const persona = definePersona({
  name: 'Dana',
  role: 'Developer Evaluating',
  background: 'Senior frontend dev, skeptical of new tools, has 15 minutes',
  goals: [
    'Understand if worth the learning curve',
    'Find runnable code examples',
    'Assess implementation effort',
  ],
  behaviors: [
    'Skims headings, jumps to code',
    'Looks for quickstart guides',
  ],
});

const collector = new ObservationCollector({
  outputDir: './test-results',
  persona,
});

import {
  definePersona,
  interactionPatternDefaults,
  emotionalBaselineDefaults,
  cognitionDefaults,
} from 'personaspec';

const persona = definePersona({
  name: 'Marcus',
  role: 'Frustrated Customer',
  background: 'Has been trying to resolve an issue for days...',
  goals: ['Get immediate help', 'Talk to a real person'],
  behaviors: ['Impatient with slow responses', 'Will abandon if frustrated'],

  // Human-scale timing (even impatient users don't click 100x/sec)
  interactionPatterns: interactionPatternDefaults.impatient,

  // Emotional state
  emotionalBaseline: {
    frustrationLevel: 60,           // Already frustrated
    frustrationEscalation: 'volatile',
    trustLevel: 'skeptical',
    urgency: 'urgent',
  },

  // How they process information
  cognition: cognitionDefaults.scanner,

  // What they compare against
  priorExperience: {
    referenceProducts: ['Zendesk', 'Intercom'],
    expectedPatterns: ['Live chat indicator', 'Response time estimate'],
    delighters: ['Instant response', 'No queue'],
    petPeeves: ['Long wait times', 'Generic responses'],
  },

  // Session context
  sessionContext: {
    isReturning: true,
    priorActivity: 'Failed email attempts',
    distractionLevel: 'low',
    timeContext: 'midday-busy',
  },
});

test.describe.configure({ mode: 'serial' });

test.describe(`${persona.name} - ${persona.role}`, () => {
  test.afterAll(async () => {
    await collector.save();
  });

  test('find code examples quickly', async ({ page }) => {
    // 1. Start timing
    collector.startTask();

    // 2. Initialize success as false
    let success = false;

    // 3. Navigate and screenshot
    await page.goto('https://example.com');
    collector.trackPageLoad();
    await collector.screenshot(page, 'homepage',
      'Dana lands on homepage, scanning for code');

    // 4. Attempt the task
    const codeBlock = page.locator('pre code').first();

    // 5. Evaluate and observe
    if (await codeBlock.isVisible({ timeout: 5000 })) {
      success = true;
      collector.observe('success', 'Code visible on homepage', 'Homepage');
    } else {
      collector.observe('frustration', 'No code examples found', 'Homepage');
    }

    // 6. Result screenshot
    await collector.screenshot(page, 'code-search-result',
      'After searching for code examples');

    // 7. Record the task
    collector.recordTask('find code examples quickly', success,
      success ? 'Found on homepage' : 'Code not visible');
  });
});

test('free exploration', async ({ page }) => {
  collector.startTask();

  await page.goto('https://example.com');
  collector.trackPageLoad();

  // Browse naturally based on persona behaviors
  const links = await page.locator('nav a').all();
  for (const link of links.slice(0, 3)) {
    try {
      await link.click();
      collector.trackClick();
      collector.trackPageLoad();
      await collector.screenshot(page, `explore-${await link.textContent()}`,
        'Exploring navigation');
    } catch (e) {
      collector.observe('note', 'Navigation click failed', page.url());
    }
  }

  // Free exploration always "succeeds" - observations are the value
  collector.recordTask('free exploration', true, 'Browsed site naturally');
});

npx personaspec init [options]

# Options:
  --force    Overwrite existing files

npx personaspec report <results.json> [options]

# Options:
  --output <file>    Output filename (default: persona-report.html)

npx personaspec analyze <results.json> [options]

# Options:
  --api-key <key>          Anthropic API key (or set ANTHROPIC_API_KEY env var)
  --output <file>          Output filename (default: analysis-report.md)
  --model <model>          Claude model (default: claude-sonnet-4-20250514)
  --max-screenshots <n>    Max screenshots to analyze (default: 10)

new ObservationCollector({
  outputDir: string,           // Where to save results
  persona: PersonaDefinition,   // From definePersona()
  includeBase64?: boolean,     // Include base64 screenshots (default: true)
  screenshotFormat?: 'png' | 'jpeg',  // Screenshot format (default: 'png')
})

definePersona({
  // Required - Core attributes
  name: string,
  role: string,
  background: string,
  goals: string[],
  behaviors: string[],

  // Optional - Behavioral Realism attributes
  interactionPatterns?: InteractionPatterns,
  emotionalBaseline?: EmotionalBaseline,
  cognition?: CognitionProfile,
  priorExperience?: PriorExperience,
  sessionContext?: SessionContext,
}): PersonaDefinition

import { personaTemplates } from 'personaspec';

// Use default template
const visitor = personaTemplates.firstTimeVisitor();

// Customize the template
const custom = personaTemplates.firstTimeVisitor({
  name: 'Jordan',
  goals: ['Find pricing', 'Compare with competitors'],
});

{
  "persona": "Alex - First-Time Visitor",
  "background": "New to the site with no prior context...",
  "goals": ["Understand what this does within 10 seconds"],
  "behaviors": ["Skims headings before reading"],
  "session": {
    "startTime": "2024-01-15T10:30:00Z",
    "endTime": "2024-01-15T10:32:45Z",
    "pagesVisited": 4,
    "clickCount": 5,
    "backNavCount": 1,
    "consoleErrors": []
  },
  "tasks": [
    {
      "name": "understand site purpose",
      "success": true,
      "duration": 4500,
      "notes": "Clear headline"
    }
  ],
  "observations": [
    {
      "type": "success",
      "description": "Value prop clear in hero",
      "location": "Homepage hero",
      "timestamp": "2024-01-15T10:30:15Z"
    }
  ],
  "screenshots": [
    {
      "name": "homepage-initial",
      "context": "First view of homepage",
      "url": "https://example.com/",
      "base64": "iVBORw0KGgo..."
    }
  ]
}