slapify 0.0.0

package/README.md

@@ -0,0 +1,452 @@
+# slapify 🖐️
+
+**AI-powered E2E testing that slaps** — write tests in plain English.
+
+By [slaps.dev](https://slaps.dev)
+
+## Installation
+
+```bash
+# Install globally
+npm install -g slapify
+
+# Or use directly with npx (no install needed)
+npx slapify init
+```
+
+## Quick Start
+
+```bash
+# Initialize in your project (interactive setup)
+slapify init
+
+# Or with npx
+npx slapify init
+
+# Quick init with defaults (skip prompts)
+slapify init -y
+
+# Set your API key
+export ANTHROPIC_API_KEY=your-key
+
+# Run the example test
+slapify run tests/example.flow
+```
+
+The interactive `init` command will:
+
+- 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
+
+## Writing Tests
+
+Create `.flow` files with natural language steps:
+
+```
+# 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
+```
+
+### Syntax
+
+| 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`          |
+
+## Configuration
+
+### `.slapify/config.yaml`
+
+```yaml
+# LLM Settings (required)
+llm:
+  provider: anthropic
+  model: claude-sonnet-4-20250514
+  api_key: ${ANTHROPIC_API_KEY}
+
+# Browser Settings (optional)
+browser:
+  headless: true
+  timeout: 30000
+  viewport:
+    width: 1280
+    height: 720
+
+# Report Settings (optional)
+report:
+  format: html
+  screenshots: true
+  output_dir: ./test-reports
+```
+
+### `.slapify/credentials.yaml`
+
+```yaml
+profiles:
+  default:
+    type: login-form
+    username: ${TEST_USERNAME}
+    password: ${TEST_PASSWORD}
+
+  admin:
+    type: login-form
+    username: admin@example.com
+    password: ${ADMIN_PASSWORD}
+    totp_secret: JBSWY3DPEHPK3PXP # For 2FA
+
+  session:
+    type: inject
+    cookies:
+      - name: auth_token
+        value: ${AUTH_TOKEN}
+        domain: .example.com
+```
+
+## CLI Commands
+
+```bash
+# Initialize project
+slapify init
+
+# Run all tests in tests/ directory
+slapify run
+
+# Run specific files
+slapify run tests/login.flow tests/checkout.flow
+
+# Run all tests in a directory
+slapify run tests/
+
+# Run with visible browser
+slapify run --headed
+
+# Run with HTML report
+slapify run --report
+
+# Run in parallel (4 workers by default)
+slapify run tests/ --parallel
+
+# Run in parallel with 8 workers
+slapify run tests/ -p -w 8
+
+# Fix failing tests automatically
+slapify fix tests/broken.flow
+
+# Validate flow files
+slapify validate
+
+# List all tests
+slapify list
+
+# Create a new flow file
+slapify create my-test
+
+# Generate flow from prompt
+slapify generate "test login flow for github.com"
+
+# Interactive mode
+slapify interactive https://myapp.com
+```
+
+## Programmatic Usage
+
+### Basic Usage
+
+```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"',
+    '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
+```
+
+### Run from File
+
+```typescript
+const result = await slapify.runFile("./tests/checkout.flow");
+```
+
+### Run Multiple Tests
+
+```typescript
+// Sequential
+const results = await slapify.runMultiple([
+  "tests/login.flow",
+  "tests/checkout.flow",
+]);
+
+// Parallel with 4 workers
+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
+const result = await slapify.run(steps, "my-test", {
+  onTestStart: (name, totalSteps) => {
+    console.log(`Starting ${name} with ${totalSteps} steps`);
+  },
+  onStep: (stepResult, testName) => {
+    const icon = stepResult.status === "passed" ? "✓" : "✗";
+    console.log(`  ${icon} ${stepResult.step.text}`);
+  },
+  onTestComplete: (result) => {
+    console.log(`Finished: ${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);
+```
+
+### Jest 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";
+
+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 }
+  );
+});
+```
+
+## 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
+
+### Auto-Handling
+
+Slapify automatically handles common interruptions:
+
+- Cookie consent banners
+- Newsletter popups
+- Notification prompts
+- Chat widgets
+- CAPTCHAs (basic)
+
+All auto-handled items are noted in the report.
+
+### Auto-Retry
+
+Failed steps are automatically retried once before marking as failed. This helps with:
+
+- Flaky network requests
+- Animation timing issues
+- Element loading delays
+
+### Auto-Fix
+
+Use `slapify fix` to automatically analyze and fix failing tests:
+
+```bash
+slapify fix tests/broken.flow
+```
+
+## Reports
+
+Beautiful HTML reports with:
+
+- Expandable step details
+- Embedded screenshots
+- Duration metrics
+- Pass/fail summary
+- Assumptions highlighted
+- Auto-handled items noted
+
+## LLM Providers
+
+Supports 6 AI providers via Vercel AI SDK. **Cheap models are recommended by default.**
+
+### Recommended (Budget-Friendly)
+
+```yaml
+# Anthropic - Claude Haiku 4.5 (fast & cheap, $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)
+llm:
+  provider: openai
+  model: gpt-4o-mini
+  api_key: ${OPENAI_API_KEY}
+
+# Google - Gemini 2.0 Flash (fastest & cheapest)
+llm:
+  provider: google
+  model: gemini-2.0-flash
+  api_key: ${GOOGLE_API_KEY}
+
+# Groq - Free tier available!
+llm:
+  provider: groq
+  model: llama-3.3-70b-versatile
+  api_key: ${GROQ_API_KEY}
+```
+
+### More Capable (Higher Cost)
+
+```yaml
+# Anthropic - Claude Sonnet 4 ($3/15M tokens)
+llm:
+  provider: anthropic
+  model: claude-sonnet-4-20250514
+
+# OpenAI - GPT-4o ($2.5/10M tokens)
+llm:
+  provider: openai
+  model: gpt-4o
+```
+
+### Local (No API Key)
+
+```yaml
+# Ollama - runs locally, 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
+├── tests/
+│   ├── auth/
+│   │   ├── login.flow
+│   │   └── signup.flow
+│   ├── checkout/
+│   │   └── purchase.flow
+│   └── smoke.flow
+└── test-reports/
+    └── login-1234567890/
+        ├── report.html
+        └── screenshots...
+```
+
+## Requirements
+
+- Node.js 18+
+- `agent-browser` (installed automatically)
+
+## License
+
+MIT — Made with 🖐️ by [slaps.dev](https://slaps.dev)

package/bin/slapify.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli.js";

package/dist/ai/interpreter.d.ts

@@ -0,0 +1,54 @@
+import { LLMConfig, FlowStep, BrowserState, CredentialProfile } from "../types.js";
+/**
+ * AI interpreter for converting natural language steps to browser actions
+ */
+export declare class AIInterpreter {
+    private config;
+    constructor(config: LLMConfig);
+    /**
+     * Interpret a step and generate browser commands
+     */
+    interpretStep(step: FlowStep, browserState: BrowserState, credentials?: Record<string, CredentialProfile>): Promise<InterpretedStep>;
+    /**
+     * Check for auto-handle opportunities (popups, banners, etc.)
+     */
+    checkAutoHandle(browserState: BrowserState): Promise<AutoHandleAction[]>;
+    /**
+     * Analyze page to find login form for credentials injection
+     */
+    findLoginForm(browserState: BrowserState): Promise<LoginFormInfo | null>;
+    /**
+     * Verify an assertion/condition on the page
+     */
+    verifyCondition(condition: string, browserState: BrowserState): Promise<VerificationResult>;
+}
+export interface InterpretedStep {
+    actions: BrowserCommand[];
+    assumptions: string[];
+    needsCredentials: boolean;
+    credentialProfile: string | null;
+    skipReason: string | null;
+    verified?: boolean;
+}
+export interface BrowserCommand {
+    command: string;
+    args: string[];
+    description: string;
+}
+export interface AutoHandleAction {
+    type: string;
+    ref: string;
+    action: string;
+    description: string;
+}
+export interface LoginFormInfo {
+    usernameRef: string;
+    passwordRef: string;
+    submitRef: string;
+}
+export interface VerificationResult {
+    satisfied: boolean;
+    evidence: string;
+    suggestion?: string;
+}
+//# sourceMappingURL=interpreter.d.ts.map

package/dist/ai/interpreter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpreter.d.ts","sourceRoot":"","sources":["../../src/ai/interpreter.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,iBAAiB,EAElB,MAAM,aAAa,CAAC;AAoDrB;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAY;gBAEd,MAAM,EAAE,SAAS;IAI7B;;OAEG;IACG,aAAa,CACjB,IAAI,EAAE,QAAQ,EACd,YAAY,EAAE,YAAY,EAC1B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAC9C,OAAO,CAAC,eAAe,CAAC;IAoG3B;;OAEG;IACG,eAAe,CACnB,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAoD9B;;OAEG;IACG,aAAa,CACjB,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IA+ChC;;OAEG;IACG,eAAe,CACnB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC,kBAAkB,CAAC;CAkD/B;AAGD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}