slapify 0.0.14 → 0.0.17

package/README.md

@@ -1,453 +1,537 @@
 # slapify 🖐️
 
-**AI-powered E2E testing that slaps** — write tests in plain English.
+**AI-powered browser automation that slaps** — run autonomous agents, audit performance, and write E2E tests in plain English.
 
 By [slaps.dev](https://slaps.dev)
 
+---
+
+## What can it do?
+
+| Mode       | What it does                                                                                                                                                   |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`task`** | Autonomous AI agent — give it any goal, it figures out how to achieve it. Browses, logs in, schedules itself, audits performance, remembers state across runs. |
+| **`run`**  | Execute `.flow` test files — plain-English E2E tests with screenshots and HTML reports                                                                         |
+
+---
+
 ## Installation
 
 ```bash
-# Install globally
 npm install -g slapify
 
-# Or use directly with npx (no install needed)
+# or run without installing
 npx slapify init
 ```
 
+---
+
 ## Quick Start
 
 ```bash
-# Initialize in your project (interactive setup)
+# 1. Set up your project (interactive — picks LLM, browser, creates sample files)
 slapify init
 
-# Or with npx
-npx slapify init
+# 2. Set your API key
+export ANTHROPIC_API_KEY=your-key
 
-# Quick init with defaults (skip prompts)
-slapify init -y
+# 3a. Run an autonomous task
+slapify task "Summarise the top posts on reddit.com/r/programming today" --report
 
-# Set your API key
-export ANTHROPIC_API_KEY=your-key
+# 3b. Run a test flow
+slapify run tests/example.flow --report
+```
+
+---
 
-# Run the example test (command is "slapify run", not "flow")
-slapify run tests/example.flow
-# Or with npx:
-npx slapify run tests/example.flow
+## Autonomous Agent (`slapify task`)
+
+Give it a goal in plain English. The agent decides what to do, browses pages, handles login, retries on errors, and keeps running until the goal is complete — even if that takes hours or days.
+
+### CLI
+
+```bash
+# One-off research
+slapify task "What is the current gold price?"
+slapify task "Go to reddit.com/r/programming and summarise the top 5 posts"
+slapify task "Check https://myapp.com and tell me if anything looks broken"
+
+# Performance audits
+slapify task "Audit the performance of slaps.dev" --report
+slapify task "Audit the home, pricing, and about pages on vercel.com" --report
+
+# Long-running / scheduled
+slapify task "Check my LinkedIn messages every 30 minutes and summarise new ones"
+slapify task "Monitor https://example.com/status every 5 minutes and alert if down"
+slapify task "Check BTC price every hour for 24 hours and give me an end-of-day summary"
+
+# Auth-required tasks (agent handles login automatically)
+slapify task "Log into myapp.com and export my account data"
+slapify task "Reply to any unread Slack DMs with a friendly holding message"
+
+# Flags
+slapify task "..." --report      # generate HTML report on exit
+slapify task "..." --headed      # show the browser window
+slapify task "..." --debug       # verbose logs
+slapify task "..." --save-flow   # save steps as a reusable .flow file
 ```
 
-The interactive `init` command will:
+### What the agent can do
+
+| Capability                | Details                                                                        |
+| ------------------------- | ------------------------------------------------------------------------------ |
+| **Browse & interact**     | Navigate, click, type, scroll, fill forms, handle popups                       |
+| **Bypass bot protection** | Falls back to HTTP-level requests when the browser is blocked                  |
+| **Login automatically**   | Detects login forms, uses saved credential profiles, asks you to save new ones |
+| **Persistent memory**     | Stores key facts between runs (thread URLs, last-seen items, etc.)             |
+| **Schedule itself**       | Creates its own cron jobs for recurring subtasks                               |
+| **Ask for input**         | Pauses and prompts you when it needs information (e.g. OTP, confirmation)      |
+| **Performance audit**     | Scores, web vitals, network analysis, framework detection, re-render testing   |
+| **HTML report**           | Full session report with tool timeline, summaries, and perf data               |
 
-- Ask which LLM provider to use (Anthropic/OpenAI)
-- Detect installed browsers on your system
-- Let you choose between system Chrome or downloading Chromium
-- Create a sample test file to get started
+### Programmatic (JS/TS)
 
-## Writing Tests
+```typescript
+import { runTask } from "slapify";
 
-Create `.flow` files with natural language steps:
+// Simple one-shot task
+const result = await runTask({
+  goal: "Go to news.ycombinator.com and return the top 10 headlines",
+});
 
+console.log(result.finalSummary);
 ```
-# tests/login.flow
-
-Go to https://myapp.com
-Login with default credentials
-Verify "Welcome" message appears
-[Optional] Close promotional popup
-Navigate to settings
-Verify "Account Settings" page loads
+
+```typescript
+import { runTask, TaskEvent } from "slapify";
+
+// With real-time events
+const result = await runTask({
+  goal: "Audit the performance of https://myapp.com/pricing and /about",
+
+  onEvent: (event: TaskEvent) => {
+    if (event.type === "message") console.log("Agent:", event.text);
+    if (event.type === "status_update") console.log("→", event.message);
+    if (event.type === "tool_start") console.log(`  [${event.toolName}]`);
+    if (event.type === "done") console.log("✅", event.summary);
+  },
+
+  // Called when the agent needs a human answer (e.g. 2FA code, confirmation)
+  onHumanInput: async (question, hint) => {
+    return await promptUser(question); // plug in your own UI
+  },
+});
 ```
 
-### Syntax
+```typescript
+import { runTask } from "slapify";
 
-| Feature       | Example                                     |
-| ------------- | ------------------------------------------- |
-| Comments      | `# This is a comment`                       |
-| Required step | `Click the login button`                    |
-| Optional step | `[Optional] Close popup`                    |
-| Conditional   | `If "Accept cookies" appears, click Accept` |
-| Credentials   | `Login with admin credentials`              |
-| Verification  | `Verify "Success" message appears`          |
+// Resume a previous session (credentials, memory, and context are preserved)
+const result = await runTask({
+  goal: "Continue monitoring LinkedIn messages",
+  sessionId: "task-2026-02-19T20-19-44-dtbfu",
+});
+```
 
-## Configuration
+```typescript
+import { runTask } from "slapify";
+
+// Long-running scheduled task — agent sets its own cron internally
+await runTask({
+  goal:
+    "Every hour, check the BTC price and store it. " +
+    "After 24 hours, summarise the day's movements.",
+  maxIterations: 500,
+  onEvent: (e) => {
+    if (e.type === "scheduled") console.log(`Scheduled: ${e.cron}`);
+    if (e.type === "sleeping") console.log(`Sleeping until: ${e.until}`);
+    if (e.type === "done") console.log(e.summary);
+  },
+});
+```
 
-### `.slapify/config.yaml`
+---
 
-```yaml
-# LLM Settings (required)
-llm:
-  provider: anthropic
-  model: claude-sonnet-4-20250514
-  api_key: ${ANTHROPIC_API_KEY}
+## Performance Auditing
 
-# Browser Settings (optional)
-browser:
-  headless: true
-  timeout: 30000
-  viewport:
-    width: 1280
-    height: 720
+The agent has a built-in `perf_audit` tool. Just ask it to check performance — it navigates, injects observers, collects everything, and includes it all in the HTML report.
 
-# Report Settings (optional)
-report:
-  format: html
-  screenshots: true
-  output_dir: ./test-reports
+### What's measured
+
+| Category              | Metrics                                                          |
+| --------------------- | ---------------------------------------------------------------- |
+| **Real-user metrics** | FCP, LCP, CLS, TTFB                                              |
+| **Lab scores**        | Performance, Accessibility, SEO, Best Practices (0–100)          |
+| **Framework**         | React / Next.js detection, re-render issues, interaction tests   |
+| **Network**           | Total size, JS bundle size, CSS, images                          |
+| **API calls**         | Method, URL, status, duration — slow (>500ms) and failed flagged |
+| **Long tasks**        | JavaScript blocking the main thread (>50ms)                      |
+| **Memory**            | JS heap usage                                                    |
+
+### Multi-page comparison
+
+Audit multiple pages in one command. The HTML report shows a **tab bar** — one tab per URL, click to switch. Each tab has the full breakdown for that page.
+
+```bash
+# Three-tab report: /, /pricing, /about
+slapify task "Audit the home, pricing, and about pages on vercel.com" --report
 ```
 
-### `.slapify/credentials.yaml`
+### Programmatic
 
-```yaml
-profiles:
-  default:
-    type: login-form
-    username: ${TEST_USERNAME}
-    password: ${TEST_PASSWORD}
+```typescript
+import { runPerfAudit } from "slapify/perf";
+import { BrowserAgent } from "slapify";
 
-  admin:
-    type: login-form
-    username: admin@example.com
-    password: ${ADMIN_PASSWORD}
-    totp_secret: JBSWY3DPEHPK3PXP # For 2FA
+const browser = new BrowserAgent();
+await browser.launch();
 
-  session:
-    type: inject
-    cookies:
-      - name: auth_token
-        value: ${AUTH_TOKEN}
-        domain: .example.com
+const result = await runPerfAudit("https://myapp.com/pricing", browser, {
+  lighthouse: true, // lab scores — Performance/A11y/SEO/Best Practices (default: true)
+  reactScan: true, // framework detection + re-render analysis (default: true)
+  navigate: true, // navigate to the URL before auditing (default: true)
+});
+
+console.log(result.vitals); // { fcp, lcp, cls, ttfb }
+console.log(result.scores); // { performance, accessibility, seo, bestPractices }
+console.log(result.react); // { detected, version, issues, interactionTests }
+console.log(result.network); // { totalRequests, totalBytes, apiCalls, longTasks, ... }
+
+await browser.close();
 ```
 
-## CLI Commands
+---
 
-```bash
-# Initialize project
-slapify init
+## Test Flows (`slapify run`)
+
+Write tests as `.flow` files in plain English. The AI interprets each line and executes browser actions, with screenshots and auto-retry on failure.
+
+### Smart by default
+
+You don't need to spell out every edge case. The runner handles these automatically on every step:
 
-# Run all tests in tests/ directory
-slapify run
+| What happens automatically               | How                                                                                                                                       |
+| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| **Cookie banners, popups, chat widgets** | Detected and dismissed before they block the next step                                                                                    |
+| **CAPTCHAs**                             | Detected by page content signals (reCAPTCHA, hCaptcha, Cloudflare Turnstile) and solved automatically                                     |
+| **Credential lookup**                    | Steps like `Log in` or `Sign in` (no profile named) auto-pick the best matching profile for the current domain, falling back to `default` |
+| **Auto-retry**                           | Failed steps are retried once before being marked failed                                                                                  |
 
-# Run specific files
-slapify run tests/login.flow tests/checkout.flow
+### Writing `.flow` files
 
-# Run all tests in a directory
+```
+# tests/checkout.flow
+
+Go to https://myshop.com
+[Optional] Close cookie banner
+Click "Add to Cart" on the first product
+Go to checkout
+Log in                              # picks the right credential profile automatically
+Fill shipping address
+Click "Place Order"
+Verify "Order confirmed" appears
+```
+
+**Syntax reference:**
+
+| Syntax           | Example                                          |
+| ---------------- | ------------------------------------------------ |
+| Comment          | `# This is a comment`                            |
+| Required step    | `Click the login button`                         |
+| Optional step    | `[Optional] Close popup`                         |
+| Conditional      | `If "Accept cookies" appears, click Accept`      |
+| Named credential | `Login with admin credentials`                   |
+| Auto credential  | `Log in` — picks best profile for current domain |
+| Assertion        | `Verify "Welcome" message appears`               |
+
+### CLI
+
+```bash
+# Run a single flow
+slapify run tests/login.flow
+
+# Run all flows in a directory
 slapify run tests/
 
-# Run with visible browser
-slapify run --headed
+# With visible browser
+slapify run tests/ --headed
 
-# Run with HTML report
-slapify run --report
+# Generate HTML report with screenshots
+slapify run tests/ --report
+
+# Include performance audit in the report
+slapify run tests/ --report --performance
 
 # Run in parallel (4 workers by default)
 slapify run tests/ --parallel
 
 # Run in parallel with 8 workers
-slapify run tests/ -p -w 8
+slapify run tests/ --parallel --workers 8
 
-# Fix failing tests automatically
+# Auto-fix a failing flow
 slapify fix tests/broken.flow
 
-# Validate flow files
-slapify validate
+# Other utilities
+slapify list             # list all flow files
+slapify validate         # validate flow syntax
+slapify create my-test   # create a blank flow
+```
+
+### Generating flows
 
-# List all tests
-slapify list
+Instead of writing flows by hand, use `generate` to have the agent discover the real path by actually running it in the browser — handles login, captcha, and dynamic content automatically, and only records steps that worked.
 
-# Create a new flow file
-slapify create my-test
+```bash
+# Agent runs the goal, saves verified steps to tests/
+slapify generate "test the login flow on github.com"
 
-# Generate flow from prompt
-slapify generate "test login flow for github.com"
+# Save to a specific directory
+slapify generate "test checkout on myshop.com" --dir tests/checkout
 
-# Interactive mode
-slapify interactive https://myapp.com
+# With visible browser
+slapify generate "sign up flow on myapp.com" --headed
 ```
 
-## Programmatic Usage
+This is equivalent to `slapify task "..." --save-flow --dir tests/` — the saved `.flow` file is proven to work, not just AI-guessed from a page snapshot.
 
-### Basic Usage
+### Programmatic (JS/TS)
 
 ```typescript
 import { Slapify } from "slapify";
 
-// Using config directory
 const slapify = new Slapify({ configDir: ".slapify" });
 
-// Or with inline config
-const slapify = new Slapify({
-  config: {
-    llm: {
-      provider: "anthropic",
-      model: "claude-sonnet-4-20250514",
-      api_key: process.env.ANTHROPIC_API_KEY,
-    },
-    browser: { headless: true },
-  },
-});
-
 // Run inline steps
 const result = await slapify.run(
   [
     "Go to https://example.com",
-    'Click on "More information"',
+    'Click "More information"',
     'Verify URL contains "iana.org"',
   ],
   "example-test"
 );
 
-console.log(result.status); // 'passed' or 'failed'
-console.log(result.passedSteps); // Number of passed steps
-console.log(result.duration); // Total time in ms
+console.log(result.status); // 'passed' | 'failed'
+console.log(result.passedSteps); // number
+console.log(result.duration); // ms
 ```
 
-### Run from File
-
 ```typescript
+// Run from file
 const result = await slapify.runFile("./tests/checkout.flow");
-```
-
-### Run Multiple Tests
 
-```typescript
-// Sequential
+// Run multiple — sequential
 const results = await slapify.runMultiple([
   "tests/login.flow",
   "tests/checkout.flow",
 ]);
 
-// Parallel with 4 workers
+// Run multiple — parallel
 const results = await slapify.runMultiple(["tests/"], {
   parallel: true,
   workers: 4,
 });
-
-// Run all tests in a directory
-const results = await slapify.runAll("tests/", { parallel: true });
 ```
 
-### With Progress Callbacks
-
 ```typescript
+// Step-level callbacks
 const result = await slapify.run(steps, "my-test", {
-  onTestStart: (name, totalSteps) => {
-    console.log(`Starting ${name} with ${totalSteps} steps`);
-  },
-  onStep: (stepResult, testName) => {
+  onTestStart: (name, totalSteps) =>
+    console.log(`Starting ${name} (${totalSteps} steps)`),
+  onStep: (stepResult) => {
     const icon = stepResult.status === "passed" ? "✓" : "✗";
     console.log(`  ${icon} ${stepResult.step.text}`);
   },
-  onTestComplete: (result) => {
-    console.log(`Finished: ${result.status}`);
-  },
+  onTestComplete: (result) => console.log(`Done: ${result.status}`),
 });
 ```
 
-### Generate Reports
-
 ```typescript
-// Single test report
-const reportPath = slapify.saveReport(result);
-
-// Suite report for multiple tests
-const suiteReportPath = slapify.saveSuiteReport(results);
-
-// Get report HTML as string
-const html = slapify.generateReport(result);
+// Save reports
+const reportPath = slapify.saveReport(result); // single test
+const suiteReport = slapify.saveSuiteReport(results); // full suite
+const html = slapify.generateReport(result); // HTML as string
 ```
 
-### Jest Integration
+### Jest / Vitest integration
 
 ```typescript
 import { Slapify } from "slapify";
 
-describe("E2E Tests", () => {
-  const slapify = new Slapify({ configDir: ".slapify" });
-
-  test("user can login", async () => {
-    const result = await slapify.run(
-      [
-        "Go to https://myapp.com/login",
-        "Fill email with test@example.com",
-        "Fill password with secret123",
-        "Click Login button",
-        'Verify "Dashboard" appears',
-      ],
-      "login-test"
-    );
-
-    expect(result.status).toBe("passed");
-  }, 60000);
-
-  test("checkout flow works", async () => {
-    const result = await slapify.runFile("tests/checkout.flow");
-    expect(result.failedSteps).toBe(0);
-  }, 120000);
-});
-```
-
-### Vitest Integration
-
-```typescript
-import { describe, test, expect } from "vitest";
-import { Slapify } from "slapify";
+const slapify = new Slapify({ configDir: ".slapify" });
 
-describe("E2E Tests", () => {
-  const slapify = new Slapify({ configDir: ".slapify" });
-
-  test(
-    "user can search",
-    async () => {
-      const result = await slapify.run([
-        "Go to https://google.com",
-        "Fill search box with slapify",
-        "Press Enter",
-        "Verify results appear",
-      ]);
-
-      expect(result.status).toBe("passed");
-    },
-    { timeout: 60000 }
+test("user can log in", async () => {
+  const result = await slapify.run(
+    [
+      "Go to https://myapp.com/login",
+      "Fill email with test@example.com",
+      "Fill password with secret123",
+      "Click Login",
+      'Verify "Dashboard" appears',
+    ],
+    "login-test"
   );
-});
+  expect(result.status).toBe("passed");
+}, 60_000);
+
+test("checkout flow", async () => {
+  const result = await slapify.runFile("tests/checkout.flow");
+  expect(result.failedSteps).toBe(0);
+}, 120_000);
 ```
 
-## How It Works
+---
 
-1. **Parse**: Flow files are parsed into structured steps
-2. **Interpret**: AI interprets each step and determines browser actions
-3. **Execute**: Browser automation executes the actions
-4. **Report**: Results are collected and formatted
+## Credential Management
 
-### Auto-Handling
+Slapify handles credentials for any site — login forms, OAuth, or injecting an existing session.
 
-Slapify automatically handles common interruptions:
+### `.slapify/credentials.yaml`
 
-- Cookie consent banners
-- Newsletter popups
-- Notification prompts
-- Chat widgets
-- CAPTCHAs (basic)
+```yaml
+profiles:
+  default:
+    type: login-form
+    username: ${TEST_USERNAME}
+    password: ${TEST_PASSWORD}
 
-All auto-handled items are noted in the report.
+  admin:
+    type: login-form
+    username: admin@example.com
+    password: ${ADMIN_PASSWORD}
+    totp_secret: JBSWY3DPEHPK3PXP # TOTP 2FA
 
-### Auto-Retry
+  # Skip login entirely — inject an existing session
+  my-session:
+    type: inject
+    cookies:
+      - name: auth_token
+        value: ${AUTH_TOKEN}
+        domain: .example.com
+    localStorage:
+      user_id: "12345"
+      theme: dark
+```
 
-Failed steps are automatically retried once before marking as failed. This helps with:
+In **task mode**, credentials are fully automatic:
 
-- Flaky network requests
-- Animation timing issues
-- Element loading delays
+- The agent detects login forms and picks the right profile
+- If no profile matches, it asks you to enter credentials and offers to save them
+- Saved sessions are reused on future runs — no re-login needed
 
-### Auto-Fix
+---
 
-Use `slapify fix` to automatically analyze and fix failing tests:
+## Configuration
 
-```bash
-slapify fix tests/broken.flow
-```
+### `.slapify/config.yaml`
 
-## Reports
+```yaml
+llm:
+  provider: anthropic
+  model: claude-haiku-4-5-20251001 # fast & cheap — recommended
+  api_key: ${ANTHROPIC_API_KEY}
 
-Beautiful HTML reports with:
+browser:
+  headless: true
+  timeout: 30000
+  viewport:
+    width: 1280
+    height: 720
 
-- Expandable step details
-- Embedded screenshots
-- Duration metrics
-- Pass/fail summary
-- Assumptions highlighted
-- Auto-handled items noted
+report:
+  format: html
+  screenshots: true
+  output_dir: ./test-reports
+```
+
+---
 
 ## LLM Providers
 
-Supports 6 AI providers via Vercel AI SDK. **Cheap models are recommended by default.**
+Supports 6 providers via Vercel AI SDK.
 
-### Recommended (Budget-Friendly)
+### Budget-friendly (recommended)
 
 ```yaml
-# Anthropic - Claude Haiku 4.5 (fast & cheap, $1/5M tokens)
+# Anthropic — Claude Haiku 4.5 (fast, ~$1/5M tokens)
 llm:
   provider: anthropic
   model: claude-haiku-4-5-20251001
   api_key: ${ANTHROPIC_API_KEY}
 
-# OpenAI - GPT-4o Mini (fast & cheap, $0.15/0.6M tokens)
+# OpenAI — GPT-4o Mini
 llm:
   provider: openai
   model: gpt-4o-mini
   api_key: ${OPENAI_API_KEY}
 
-# Google - Gemini 2.0 Flash (fastest & cheapest)
+# Google — Gemini 2.0 Flash (generous free tier)
 llm:
   provider: google
   model: gemini-2.0-flash
   api_key: ${GOOGLE_API_KEY}
 
-# Groq - Free tier available!
+# Groq — free tier available
 llm:
   provider: groq
   model: llama-3.3-70b-versatile
   api_key: ${GROQ_API_KEY}
 ```
 
-### More Capable (Higher Cost)
+### More capable
 
 ```yaml
-# Anthropic - Claude Sonnet 4 ($3/15M tokens)
+# Anthropic — Claude Sonnet
 llm:
   provider: anthropic
   model: claude-sonnet-4-20250514
 
-# OpenAI - GPT-4o ($2.5/10M tokens)
+# OpenAI — GPT-4o
 llm:
   provider: openai
   model: gpt-4o
 ```
 
-### Local (No API Key)
+### Local (no API key)
 
 ```yaml
-# Ollama - runs locally, free
+# Ollama — runs on your machine, completely free
 llm:
   provider: ollama
   model: llama3 # or mistral, codellama, phi3
   base_url: http://localhost:11434/v1
 ```
 
-### Other Providers
-
-```yaml
-# Mistral
-llm:
-  provider: mistral
-  model: mistral-small-latest # or mistral-large-latest
-  api_key: ${MISTRAL_API_KEY}
-```
+---
 
 ## Project Structure
 
 ```
 your-project/
 ├── .slapify/
-│   ├── config.yaml
-│   ├── credentials.yaml
-│   └── .gitignore
+│   ├── config.yaml          # LLM + browser + report settings
+│   ├── credentials.yaml     # Saved login profiles
+│   └── tasks/               # Persisted agent sessions (auto-created)
+│       └── task-2026-....jsonl
 ├── tests/
 │   ├── auth/
 │   │   ├── login.flow
 │   │   └── signup.flow
-│   ├── checkout/
-│   │   └── purchase.flow
-│   └── smoke.flow
-└── test-reports/
+│   └── checkout.flow
+└── test-reports/            # HTML reports
     └── login-1234567890/
         ├── report.html
-        └── screenshots...
+        └── screenshots/
 ```
 
+---
+
 ## Requirements
 
 - Node.js 18+
-- `agent-browser` (installed automatically)
+- `agent-browser` (installed as a peer dependency)
+
+---
 
 ## License