npm package: @litocodes/persona-test
Description: AI User Testing with Personality - Simulate real users breaking your website
Latest version: 1.3.0

# 🌍 Persona: The Lagos Test

> **Your app works on a MacBook Pro on Fiber. It breaks for the other 5 billion people.**

Persona is **Chaos Engineering for UX**. It spawns adversarial AI agents with distinct psychological profiles to attack your app under real-world conditions.

[![npm](https://img.shields.io/npm/v/@litocodes/persona-test)](https://www.npmjs.com/package/@litocodes/persona-test)

---

## 🔥 The Lagos Test

Silicon Valley builds software for perfect internet. Persona tests for the **real world**:

```bash
# Test your site as an emerging market user on 3G
npx @litocodes/persona-test --url="https://your-site.com" --agent="lagos" --network="lagos-3g"
```

**What happens:**
- 🌐 400ms latency, 400 Kbps bandwidth (real Lagos conditions)
- 📱 Simulated $50 Android phone behavior
- 🖱️ Double-clicks (because first click "didn't work")
- 🔄 Aggressive refresh when spinners hang
- 😤 Immediate distrust of popups and data collection

---

## 🎭 The Agents

| Agent | Personality | The Test |
|-------|-------------|----------|
| 🌍 **Agent Lagos** | Emerging market user on $50 phone, 3G | Survives your bloated JS bundle |
| 👴 **Grandpa Joe** | 70yo, low tech literacy | Finds the phone number |
| 🏎️ **Zoomer Zoe** | 20yo, rage-clicks, impatient | Signs up in <5 clicks |
| 🕵️ **Skeptical Sam** | Privacy paranoid, reads fine print | Finds and rejects cookies |
| 💀 **Hacker Harry** | Security researcher | SQL injection testing |
| 🧭 **Explorer Emma** | Methodical, maps everything | Full site exploration |

---

## 🌐 Network Chaos Modes

```bash
--network="wifi"         # No throttling
--network="4g"           # 4 Mbps, 20ms
--network="3g"           # 1.5 Mbps, 100ms
--network="lagos-3g"     # 400 Kbps, 400ms (Nigerian 3G)
--network="lagos-tunnel" # 200 Kbps, 800ms (tunnel effect)
--network="chaos"        # 100 Kbps, 1200ms (worst case)
--network="edge"         # 50 Kbps, 800ms (2G)
```

---

## 🚀 Quick Start

```bash
# Run instantly
npx @litocodes/persona-test --url="https://your-site.com" --agent="lagos" --network="lagos-3g"

# Run ALL agents in parallel (Mission Control)
npx @litocodes/persona-test --url="https://your-site.com" --all

# Set your Cerebras API key (free)
export CEREBRAS_API_KEY=csk-xxxxx
```

---

## 📦 Output

Every session produces:

1. **🎥 Video Recording** - Watch the AI break your site
2. **📝 QA Report** - AI-generated friction analysis
3. **📋 Action Log** - Step-by-step decision trail

```
videos/Agent_Lagos_lagos-3g_2026-01-25_ABANDONED.webm
reports/REPORT_Agent_Lagos_2026-01-25.md
```

---

## 🎯 Why This Exists

> "If you pass the Lagos Test, you're ready for the world."
> "If you fail, you're just a US-only toy."

Most testing tools check if buttons **work**.
Persona checks if buttons are **frustrating**.

We test for:
- **Confusion**, not correctness
- **Trust**, not just functionality  
- **Global readiness**, not just US/EU

---

## 🛠️ CLI Options

```bash
persona --url="<URL>" --agent="<AGENT>" [options]

Options:
  --url, -u       Target URL (required)
  --agent, -a     lagos, boomer, zoomer, skeptic, hacker, explorer
  --all           Run ALL agents in parallel
  --network, -n   wifi, 4g, 3g, lagos-3g, lagos-tunnel, chaos, edge
  --record        Record video (default: true)
  --headless      Run without visible browser
```

---

## 📜 License

MIT © 2026

---

**Built for the next billion users.** 🌍