# 💜 ENDORPHIN

## E2E Testing Reinvented with AI

Write tests in plain English. Let AI generate, validate, and fix them
automatically.

🌐 https://endorphinai.dev

   +   

A powerful, modular browser automation framework using AI-powered testing with
LangChain, OpenAI GPT-4o, and Playwright. Provides intelligent browser
automation with automatic element detection, visual validation, and
comprehensive test management.

🎬 Watch Demo

🎯 See Endorphin AI in Action - Complete Walkthrough

✨ Watch how AI writes and executes your tests

🔍 See intelligent element detection in real-time

📊 Explore beautiful HTML reports with screenshots

⚡ From setup to test execution in 10 minutes

🌐 Visit our website for more examples and tutorials

---

🌐 Read in Your Language

---

🚀 Quick Start

$3

Get started in under 30 seconds:

``bash


⚡ Quick setup (recommended)

`bash


1. Create your project

`bash


Edit the .env file that was created

`bash


Run the sample health check test

If npx endorphin-ai doesn't work, try these guaranteed solutions:

`bash


Option 1: Use npm scripts (always works)

Alternative npm scripts in package.json:
`json
{
"scripts": {
"endorphin:init": "./node_modules/.bin/endorphin init",
"endorphin:version": "./node_modules/.bin/endorphin --version",
"endorphin:help": "./node_modules/.bin/endorphin --help"
}
}
`

$3

If you prefer manual setup:

1. Create your project directory:

`bash
mkdir my-test-project && cd my-test-project
`

2. Initialize with ES modules:

`bash
npm init -y
npm pkg set type="module"
`

3. Install Endorphin AI:

`bash
npm install endorphin-ai
`

4. Set up your .env file with your OpenAI API key:

`env
OPENAI_API_KEY=your_api_key_here
`

5. Create tests directory:

`bash
mkdir tests
`

6. Create your first test file tests/login-test.ts:

`typescript
import type { TestCase } from 'endorphin-ai';

export const QE001: TestCase = {
id: 'QE-001',
name: 'Basic Login Test',
description: 'Test the login functionality with valid credentials',
priority: 'High',
tags: ['authentication', 'login', 'smoke'],
site: 'https://qafromla.herokuapp.com/',
data: async () => {
return {
originalEmail: 'papapin888@gmail.com',
originalPassword: 'lalalend',
};
},
task: Navigate to https://qafromla.herokuapp.com/.
Click on "Log In" button. Wait 2 seconds for page load.
Fill email field with "papapin888@gmail.com".
Fill password field with "lalalend".
Click "Sign In" button. Wait 3 seconds for page load.
Verify login was successful by checking page content.,
};
`

7. Add scripts to your package.json:
`json
{
"scripts": {
"test": "endorphin-ai run test all",
"test:smoke": "endorphin-ai run test --tag smoke",
"test:auth": "endorphin-ai run test --tag authentication",
"test:single": "endorphin-ai run test",
"test:record": "endorphin-ai run test-recorder",
"endorphin:init": "./node_modules/.bin/endorphin-ai init",
"endorphin:version": "./node_modules/.bin/endorphin --version"
}
}
`

🎯 Core Features

$3

- Write tests in plain English - No complex selectors needed
- Intelligent element detection - AI finds buttons, forms, and content
automatically
- Self-healing tests - Adapts to UI changes without breaking
- Smart error recovery - Automatically retries failed actions with different
strategies

$3

- Interactive HTML reports with screenshots and step-by-step execution
- Cost & token tracking - Monitor AI usage and optimize expenses
- AI decision history - See exactly how AI analyzes and executes tests
- Real-time filtering and search to quickly find issues
- Visual debugging with click-to-zoom screenshots
- Export capabilities for sharing with your team

$3

https://github.com/user-attachments/assets/83a900c6-9279-496d-bc12-f16fb98cf6dc

$3

- Zero configuration - Works out of the box
- TypeScript support with full type definitions
- Smart test structure - Dynamic setup, data generation, and task functions
- Built-in tools system - 12 comprehensive automation tools included
- VS Code debugging - Professional debugging with debug object access
- Multiple browsers - Chrome, Firefox, Safari support
- Sequential execution for reliable test runs

$3

- Test Recorder - Create tests by clicking through your app
- Live debugging - See exactly what the AI is doing
- Custom test creation with guided prompts
- Session replay to understand test failures

---

🔄 Staying Updated

$3

`bash


Check your current version

- ✅ Smart Test Structure - New async setup(), data(), and task()
functions for dynamic test preparation
- ✅ Enhanced HTML Reports - Interactive reports with cost tracking and AI
decision history
- ✅ Cost & Token Tracking - Monitor AI usage costs per test and per step
- ✅ AI Decision History - See exactly how AI analyzes and executes tests
- ✅ Built-in Tools System - 12 comprehensive browser automation tools (no
custom tools needed)
- ✅ Professional Debugging - VS Code integration with debug object access
- ✅ CI/CD Ready - Ready-to-use GitHub Actions workflows included

🚀 Project Initialization

$3

`bash


Quick setup for new projects

The init command creates:

- ✅ tests/ directory with sample TypeScript test
- ✅ test-results/ for test outputs
- ✅ test-recorder/ for recorded tests
- ✅ .env file with API key placeholder
- ✅ endorphin.config.ts with optimized TypeScript settings

- ✅ tsconfig.json for TypeScript compilation
- ✅ .gitignore with Endorphin-specific patterns
- ✅ README-ENDORPHIN.md quick start guide

$3

For existing Endorphin projects, the init command is optional and safe:

- ✅ Never overwrites existing configuration files
- ✅ Only creates missing directories
- ✅ Adds helpful template files if needed

`bash


Safe to run in existing projects

`bash


Check current version

`bash


Create a new Endorphin AI project with all necessary files

`bash


Using npm scripts (recommended)

`bash


Using npm scripts

`bash


Using npm scripts

`bash


Using npm scripts

`bash


Generate a full interactive HTML report

- Real-time Search: Find tests by name or ID instantly
- Status Filtering: Filter by passed/failed tests with one click
- Smart Results: Shows "5 of 25 tests matching 'login' with status 'failed'"
- Keyboard Shortcuts: Ctrl+F to search, Ctrl+3 for failed tests only

#### 🎯 Detailed Test Analysis

- Step-by-Step Timeline: See exactly what happened during test execution
- Screenshot Galleries: Visual debugging with click-to-zoom screenshots
- Interactive Modals: Deep dive into test execution details
- Tool Call Tracking: See which browser actions were performed

#### ⌨️ Productivity Features

- Export to JSON: Data-driven analysis and custom reporting
- Print Support: Documentation-ready printed reports
- Responsive Design: Works on desktop, tablet, and mobile
- Performance Optimized: Fast loading even with large test suites

$3

For detailed usage instructions, advanced features, and best practices, see the
HTML Reporter User Guide.

🏗️ Framework Architecture

Endorphin AI is built with a modular, extensible architecture designed for
reliability and maintainability.

📖
View detailed Framework Architecture documentation

$3

- Core Framework: Main test execution engine and session management
- Browser Tools: Intelligent automation tools powered by AI
- Configuration System: Flexible, hierarchical configuration management
- Test Discovery: Automatic test file detection and loading
- Interactive Tools: Real-time test creation and debugging

⚙️ Configuration

$3

Endorphin AI works out of the box with sensible defaults, but you can customize
it by creating an endorphin.config.ts file in your project root:

`typescript
// endorphin.config.ts
import type { FrameworkConfig } from 'endorphin-ai';

const config: FrameworkConfig = {
// Global test settings
defaultTimeout: 30000,
headless: false,
viewport: { width: 1280, height: 720 },

// Default test data
testData: {
baseUrl: 'https://staging.example.com',
adminEmail: 'admin@example.com',
},

// Result settings
screenshots: true,
recordVideo: false,
};

export default config;
`

$3

You can override configuration with CLI flags:

`bash


Using npm scripts with -- to pass flags

- authentication - Login, logout, registration tests
- smoke - Critical path tests that must pass
- navigation - Menu, links, page routing tests
- forms - Form filling and validation tests
- checkout - E-commerce purchase flow tests
- search - Search functionality tests
- responsive - Mobile/tablet/desktop tests

$3

- High - Critical functionality, run on every build
- Medium - Important features, run daily
- Low - Nice-to-have features, run weekly

$3

`typescript
// tests/auth-tests.ts
import type { TestCase } from 'endorphin-ai';

export const LOGIN_TEST: TestCase = {
id: 'AUTH-001',
name: 'User Login Test',
description: 'Test user authentication flow',
tags: ['authentication', 'smoke'],
priority: 'High',
site: 'https://example.com',
task: 'Navigate to login page and authenticate user...',
};

export const LOGOUT_TEST: TestCase = {
id: 'AUTH-002',
name: 'User Logout Test',
description: 'Test user logout functionality',
tags: ['authentication'],
priority: 'Medium',
site: 'https://example.com',
task: 'Log out the authenticated user...',
};
`

🔧 Smart Test Structure (v0.9.0)

Endorphin AI v0.9.0 introduces a powerful new test structure with async
functions for dynamic test preparation.

$3

`typescript
import type { TestCase } from 'endorphin-ai';

export const SMART_TEST: TestCase = {
id: 'LOGIN-001',
name: 'User Login Test',
description: 'Test login with generated credentials',
priority: 'High',
tags: ['auth', 'smoke'],

// Generate test data dynamically
data: async () => {
const timestamp = Date.now();
return {
email: testuser${timestamp}@example.com,
password: 'SecurePassword123!',
firstName: 'Test',
lastName: 'User',
};
},

// Set up test environment
setup: async () => {
return {
baseUrl: process.env.TEST_URL || 'https://example.com',
startTime: new Date().toISOString(),
};
},

// Main test instructions using generated data
task: async (data, setupData) => {
return
Navigate to ${setupData.baseUrl}/login
Fill email with "${data.email}"
Fill password with "${data.password}"
Click Submit button
Verify welcome message contains "${data.firstName}"
;
},
};
`

$3

- Dynamic Data Generation - Create unique test data for each run
- Environment Setup - Prepare test environment before execution
- Type Safety - Full TypeScript support for all functions
- Backward Compatibility - Old test format still works perfectly

📁 Project Structure

Your project should look like this:

`
my-test-project/
├── .env # OpenAI API key
├── tests/ # Your test files (TypeScript)
│ ├── login-test.ts # Authentication tests
│ ├── checkout-test.ts # E-commerce tests
│ └── navigation-test.ts # UI/Navigation tests
├── endorphin.config.ts # Optional configuration (TypeScript)
├── tsconfig.json # TypeScript configuration
└── package.json # Project config
`

📝 Test File Format

Each test file should export test objects with TypeScript types:

`typescript
import type { TestCase } from 'endorphin-ai';

export const QE001: TestCase = {
id: 'QE-001', // Unique test identifier
name: 'Basic Login Test', // Human readable name
description: 'Test login functionality with valid credentials',
priority: 'High', // High, Medium, Low
tags: ['authentication', 'login', 'smoke'], // Categories
site: 'https://example.com/', // Target website
data: async () => {
return {
email: 'test@example.com',
password: 'password123',
};
},
task: Your test instructions in plain English...,
};

// Multiple tests per file with full type safety
export const QE002: TestCase = {
id: 'QE-002',
name: 'Registration Test',
description: 'Test user registration flow',
priority: 'Medium',
tags: ['authentication', 'registration'],
site: 'https://example.com/',
task: 'Test new user registration process...',
};
`

$3

- ✅ Full type safety for test configuration
- ✅ IntelliSense support in your IDE
- ✅ Compile-time error checking
- ✅ Auto-completion for test properties
- ✅ Refactoring support across your test suite

📊 Test Results

Each test execution creates:

- 📁 Session Directory: test-result/[test-id]_[timestamp]/
- 📝 Session Data: test-session.json with complete execution details
- 📊 Summary: summary.json with test outcomes
- 📸 Screenshots: Automatic visual documentation
- 🔄 Step Logs: Detailed execution tracking

$3

`
🎯 Running: QE-001 - Basic Login Test
📸 Screenshot taken: step-1-navigation.png
✅ Login successful - test completed!
📊 Result: PASSED
`

🎮 Interactive Features

$3

`bash


Using npm scripts

`bash


Check current installed version

`bash


Update to the latest version

- v0.9.0 _(Latest)_: Smart test structure, enhanced HTML reports with cost
tracking, AI decision history, built-in tools system
- v0.8.0: Custom tools support with CLI management and templates
- v0.6.1: Fixed npx resolution issues, enhanced user experience
- v0.6.0: Enhanced CLI, security-first publishing, cross-platform CI/CD
- v0.5.0: Advanced HTML reporting with interactive features
- v0.4.0: TypeScript-first experience with full type definitions
- v0.3.0: Added endorphin-ai init` command for instant project setup
- v0.2.x: Core framework with AI-powered testing
- v0.1.x: Initial release with basic functionality

$3

Endorphin AI maintains backward compatibility across versions:

- ✅ All existing tests work without modification
- ✅ Configuration files are automatically migrated
- ✅ npm scripts continue to function normally
- ✅ Semantic versioning ensures predictable updates

Update with confidence - your existing tests won't break!

---

🤝 Support & Community

$3

- Quick Start Guide - Get up and running
quickly
- Test Writing Tips - Enterprise &
small app examples
- HTML Reporter Guide -
Interactive reporting with cost tracking
- VS Code Debugging Guide -
Professional debugging setup
- CI/CD Setup Guide - GitHub
Actions integration
- Framework Architecture -
Technical deep dive

$3

Found a bug or have a feature idea?
Open an issue on GitHub.

$3

- Check the documentation first
- Search
existing issues
- Create a
new issue with
details

---

📄 License

Endorphin AI is licensed under the GNU Affero General Public License v3.0
(AGPLv3).

For Open Source Projects: Free to use under AGPLv3
For Commercial Projects: Commercial licenses available

📧 Contact: iam@andrewnovykov.com for licensing
questions

---