TestForge 🧪

Self-Healing Automated Testing Platform for QA Engineers and Product Managers

TestForge is an intelligent test automation platform that combines browser (E2E) and API testing with a revolutionary Self-Healing system. When UI elements change, TestForge automatically adapts using multi-layer selector strategies, reducing test maintenance to near zero.

🌟 Key Features

🏗️ Hierarchical Test Organization

Service → Feature → Scenario → Step
Organize tests by business logic, not technical implementation
Perfect for large applications with multiple features

🔄 Self-Healing Technology

Multi-layer selectors: testId → role → text → label → css → xpath
Automatic fallback when UI changes
Confidence scoring for healing suggestions
Approval workflow for production safety

🧩 Reusable Components

Extract common flows (login, navigation, setup)
Parameterize and reuse across scenarios
Track component usage across all scenarios

🌐 Unified Testing

Browser automation with Playwright
API testing with request/response validation
Mixed scenarios: Combine browser and API steps seamlessly

⚡ Real-time Execution

Live step-by-step progress via Server-Sent Events (SSE)
Instant feedback on test execution
Visual healing indicators

👥 No-Code Friendly

Visual scenario editor
Point-and-click step creation
QA engineers and product managers can create tests

🚀 Quick Start

Prerequisites

Before you begin, ensure you have the following installed:

Bun v1.0+ (runtime and package manager)
Node.js v18+ (for compatibility)
Git

Install Bun

# macOS, Linux, WSL
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

Installation

Clone the repository

git clone https://github.com/yourusername/testforge.git
cd testforge

Install dependencies

bun install

Install Playwright browsers

bunx playwright install chromium

Initialize the database

bun run db:migrate

Seed sample data (optional)

bun run db:seed

Running the Application

Start both server and web app (recommended):

bun run dev

This will start:

🖥️ API Server: http://localhost:3001
🌐 Web UI: http://localhost:3000

Or start them individually:

# Terminal 1 - API Server
bun run dev:server

# Terminal 2 - Web UI
bun run dev:web

Your First Test

Open the web UI: http://localhost:3000
Create a Service: Click "New Service", enter name and base URL
Create a Feature: Select your service, add a feature
Create a Scenario: Add steps using the visual editor
Run the test: Click the "▶️ Run" button
Watch it execute: See real-time step-by-step progress

📚 Tech Stack

Runtime & Build

Bun - Fast all-in-one JavaScript runtime
TypeScript - Type safety across the stack
Bun Workspace - Monorepo management

Frontend

React 18 - UI framework
Rsbuild - Fast Rspack-based build tool
React Router - Client-side routing
Zustand - Lightweight state management
TanStack Query - Server state management
Tailwind CSS - Utility-first CSS
shadcn/ui - High-quality React components
Axios - HTTP client

Backend

Hono - Ultrafast web framework
Hono RPC - Type-safe client-server communication
DuckDB - Embedded analytical database
Drizzle ORM - TypeScript ORM
Zod - Schema validation

Test Execution

Playwright - Browser automation
Built-in Fetch API - HTTP/API testing

📁 Project Structure

testforge/
├── packages/
│   ├── core/                    # Core test execution logic
│   │   ├── src/
│   │   │   ├── executor/        # Test execution engine
│   │   │   │   └── engine.ts    # Main TestExecutor class
│   │   │   ├── locator/         # Multi-layer selector resolution
│   │   │   │   └── resolver.ts  # LocatorResolver with Self-Healing
│   │   │   ├── healing/         # Self-Healing tracking
│   │   │   │   └── tracker.ts   # HealingTracker
│   │   │   ├── api/             # API testing client
│   │   │   │   └── client.ts    # HTTP request executor
│   │   │   └── types/           # TypeScript type definitions
│   │   │       └── index.ts     # All core types (PRD Section 3)
│   │   └── package.json
│   │
│   ├── server/                  # API Server (Hono)
│   │   ├── src/
│   │   │   ├── routes/          # API endpoints
│   │   │   │   ├── services.ts  # Service CRUD
│   │   │   │   ├── features.ts  # Feature CRUD
│   │   │   │   ├── scenarios.ts # Scenario CRUD + execution
│   │   │   │   ├── components.ts # Component CRUD
│   │   │   │   ├── healing.ts   # Healing records
│   │   │   │   └── runs.ts      # Test runs + SSE stream
│   │   │   ├── db/              # Database layer
│   │   │   │   ├── schema.ts    # Drizzle schema definitions
│   │   │   │   ├── database.ts  # Database operations
│   │   │   │   ├── connection.ts # DuckDB connection
│   │   │   │   └── migrate.ts   # Migration runner
│   │   │   ├── execution/       # Test execution management
│   │   │   │   └── manager.ts   # ExecutionManager (singleton)
│   │   │   ├── middleware/      # Middleware
│   │   │   │   └── errorHandler.ts # Global error handler
│   │   │   ├── utils/           # Utilities
│   │   │   │   └── errors.ts    # Custom error classes
│   │   │   └── index.ts         # Server entry point
│   │   └── package.json
│   │
│   └── web/                     # Frontend (React + Rsbuild)
│       ├── src/
│       │   ├── components/      # UI components
│       │   │   ├── ui/          # shadcn/ui components
│       │   │   └── ...          # Custom components
│       │   ├── pages/           # Route pages
│       │   │   ├── Dashboard.tsx        # Home dashboard
│       │   │   ├── Services.tsx         # Service list
│       │   │   ├── ServiceDetail.tsx    # Service detail
│       │   │   ├── FeatureDetail.tsx    # Feature detail
│       │   │   ├── ScenarioEditor.tsx   # Scenario editor
│       │   │   ├── Components.tsx       # Component list
│       │   │   ├── ComponentEditor.tsx  # Component editor
│       │   │   ├── Runs.tsx             # Test run history
│       │   │   ├── RunDetail.tsx        # Run detail (SSE)
│       │   │   └── Healing.tsx          # Healing dashboard
│       │   ├── lib/             # Utilities
│       │   │   └── api.ts       # API client (Axios)
│       │   ├── stores/          # Zustand stores
│       │   ├── hooks/           # Custom React hooks
│       │   ├── App.tsx          # App root
│       │   └── main.tsx         # Entry point
│       ├── rsbuild.config.ts    # Rsbuild configuration
│       └── package.json
│
├── scripts/                     # Development scripts
│   ├── dev.ts                   # Concurrent dev server launcher
│   └── seed.ts                  # Database seeding script
│
├── docs/                        # Documentation
│   ├── PRD.md                   # Product Requirements Document
│   └── USER_GUIDE.md            # User documentation
│
├── CLAUDE.md                    # Claude Code project guide
├── HEALING_DASHBOARD_ENHANCEMENTS.md  # Recent work log
├── package.json                 # Root workspace config
├── bunfig.toml                  # Bun configuration
├── tsconfig.json                # TypeScript configuration
└── README.md                    # This file

🛠️ Development

Available Scripts

Command	Description
`bun run dev`	Start both server and web app in parallel
`bun run dev:server`	Start API server only (port 3001)
`bun run dev:web`	Start web app only (port 3000)
`bun run build`	Build both server and web for production
`bun run build:server`	Build server only
`bun run build:web`	Build web only
`bun run db:migrate`	Run database migrations
`bun run db:seed`	Seed database with sample data
`bun run test`	Run test suite
`bun run lint`	Lint TypeScript files
`bun run typecheck`	Type check without emitting files

Development Workflow

Make changes to code in packages/
Hot reload is enabled for both server and web
Type checking runs automatically in your editor (VS Code recommended)
Lint before committing: bun run lint
Run tests: bun test

Adding New Dependencies

For the entire workspace:

bun add <package>

For a specific package:

cd packages/web
bun add <package>

For development only:

bun add -d <package>

Database Management

View database contents:

# Install DuckDB CLI (optional)
# macOS
brew install duckdb

# Then query
duckdb testforge.duckdb
> SELECT * FROM services;
> .tables  -- list all tables
> .quit

Reset database:

rm testforge.duckdb
bun run db:migrate
bun run db:seed

Adding UI Components (shadcn/ui)

cd packages/web

# Add a new component
bunx shadcn@latest add <component-name>

# Examples
bunx shadcn@latest add button
bunx shadcn@latest add dialog
bunx shadcn@latest add table

🧪 Testing

Running Tests

# Run all tests
bun test

# Run tests in watch mode
bun test --watch

# Run tests in a specific package
cd packages/core
bun test

Creating Tests

# Create a test file next to your source
# Example: packages/core/src/locator/resolver.test.ts

import { describe, test, expect } from "bun:test";
import { LocatorResolver } from "./resolver";

describe("LocatorResolver", () => {
  test("should resolve element by testId", async () => {
    // Test implementation
  });
});

🏗️ Architecture

Data Flow

User Action (Web UI)
    ↓
API Request (Hono RPC)
    ↓
Business Logic (Server)
    ↓
Database (DuckDB) or Test Execution (Core)
    ↓
Response / SSE Events
    ↓
UI Update (React + TanStack Query)

Test Execution Flow

1. Scenario Loaded
    ↓
2. Variables Initialized
    ↓
3. Browser Context Created (Playwright)
    ↓
4. Steps Executed Sequentially
    ├─ Component Steps → Expanded to sub-steps
    ├─ Browser Steps → LocatorResolver → Self-Healing
    └─ API Steps → HTTP Request + Validation
    ↓
5. Results Saved to Database
    ↓
6. SSE Events Sent to Client
    ↓
7. Browser Cleanup

Self-Healing Process

1. Try primary locator strategy (e.g., testId)
    ↓
2. Element not found?
    ↓
3. Try fallback strategies (role → text → css)
    ↓
4. Element found with fallback?
    ↓
5. Create HealingRecord with confidence score
    ↓
6. Auto-approve if confidence > threshold
    ↓
7. Otherwise, await manual approval
    ↓
8. Approved? Update scenario with healed locator

📖 Documentation

Product Requirements Document (PRD) - Complete technical specification
User Guide - How to use TestForge
Claude Code Guide - Development guidelines for AI agents
Healing Dashboard Enhancements - Recent feature work

🗺️ Roadmap

✅ Phase 1: Foundation (Complete)

Monorepo setup
Database schema & migrations
Basic CRUD APIs
Frontend structure

✅ Phase 2: Self-Healing (Complete)

Multi-layer locator system
Self-Healing detection
Healing approval workflow
Confidence scoring

✅ Phase 3: Components & API Testing (Complete)

Reusable component system
Component parameter binding
API request/assert steps
Response validation

🚧 Phase 4: Polish & Stabilization (95% Complete)

🔮 Future Enhancements

CI/CD integration (GitHub Actions, GitLab CI)
Multi-browser support (Firefox, Safari)
Visual regression testing
Test result analytics dashboard
AI-powered test generation
Mobile app testing (iOS, Android)
Performance testing support

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Follow the coding conventions (see CLAUDE.md)
Read the PRD before implementing features
Write tests for new functionality
Run linting: bun run lint
Commit your changes: git commit -m 'feat: add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Commit Message Convention

feat: add new feature
fix: bug fix
refactor: code refactoring
docs: documentation updates
chore: dependency updates, config changes

🐛 Troubleshooting

Bun command not found

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.bun/bin:$PATH"

Playwright browsers missing

bunx playwright install chromium

Database errors

# Reset the database
rm testforge.duckdb
bun run db:migrate

Port already in use

# Find and kill process on port 3000 or 3001
lsof -ti:3000 | xargs kill -9
lsof -ti:3001 | xargs kill -9

TypeScript errors

# Full type check
bun run typecheck

# Clean install
rm -rf node_modules bun.lockb
bun install

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Bun - For the amazing runtime
Hono - For the ultrafast web framework
Playwright - For reliable browser automation
shadcn/ui - For beautiful, accessible components
DuckDB - For the embedded analytical database

💬 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: support@testforge.dev

Built with ❤️ by the TestForge Team

Website • Documentation • Twitter

Name		Name	Last commit message	Last commit date
Latest commit History 99 Commits
.claude		.claude
docs		docs
packages		packages
screenshots		screenshots
scripts		scripts
.DS_Store		.DS_Store
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
HEALING_DASHBOARD_ENHANCEMENTS.md		HEALING_DASHBOARD_ENHANCEMENTS.md
README.md		README.md
STATUS_SUMMARY.md		STATUS_SUMMARY.md
bun.lock		bun.lock
eslint.config.mjs		eslint.config.mjs
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

TestForge 🧪

🌟 Key Features

🏗️ Hierarchical Test Organization

🔄 Self-Healing Technology

🧩 Reusable Components

🌐 Unified Testing

⚡ Real-time Execution

👥 No-Code Friendly

🚀 Quick Start

Prerequisites

Install Bun

Installation

Running the Application

Your First Test

📚 Tech Stack

Runtime & Build

Frontend

Backend

Test Execution

📁 Project Structure

🛠️ Development

Available Scripts

Development Workflow

Adding New Dependencies

Database Management

Adding UI Components (shadcn/ui)

🧪 Testing

Running Tests

Creating Tests

🏗️ Architecture

Data Flow

Test Execution Flow

Self-Healing Process

📖 Documentation

🗺️ Roadmap

✅ Phase 1: Foundation (Complete)

✅ Phase 2: Self-Healing (Complete)

✅ Phase 3: Components & API Testing (Complete)

🚧 Phase 4: Polish & Stabilization (95% Complete)

🔮 Future Enhancements

🤝 Contributing

Commit Message Convention

🐛 Troubleshooting

Bun command not found

Playwright browsers missing

Database errors

Port already in use

TypeScript errors

📄 License

🙏 Acknowledgments

💬 Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages