🤖 AI Loop Engineering

AI-Powered Software Testing Platform — Layman's Guide

In simple terms: You paste your software requirements (e.g. "Users should be able to log in with email and password"), and this platform automatically writes your test cases, generates automation test code in Playwright / Cypress / Selenium for Java, TypeScript, JavaScript, or C#, runs them, shows you results, and tells you what went wrong — all without you writing a single line of test code.

📺 What Does It Look Like?

Screen	What It Does
Dashboard	Overview of your project — test counts, pass/fail stats
Requirements	Paste your software requirement text here
Test Design	AI generates test scenarios and test cases from your requirement
Automation Code	Pick a framework + language → AI writes the full test code
Execution Console	Click Run → watch tests execute step by step with live logs
Traceability	See which requirement maps to which test case and test result

🗂️ Project Folder Structure (Plain English)

AILOOPENGINEERING/                ← Root of the whole project
│
├── apps/                         ← The two running applications
│   ├── api/                      ← BACKEND — the server (Node.js + Express)
│   │   └── src/
│   │       ├── index.ts          ← Server entry point (starts on port 4000)
│   │       ├── routes/
│   │       │   └── index.ts      ← All API URL paths (POST /execution/run etc.)
│   │       └── controllers/      ← Business logic for each feature
│   │           ├── projects.controller.ts       ← Create/load projects
│   │           ├── requirements.controller.ts   ← Ingest & analyze requirements
│   │           ├── test-design.controller.ts    ← Generate test cases
│   │           ├── automation.controller.ts     ← Generate test code
│   │           ├── execution.controller.ts      ← Run tests & store results
│   │           └── traceability.controller.ts   ← Traceability matrix
│   │
│   └── web/                      ← FRONTEND — the browser UI (React + Vite)
│       └── src/
│           ├── App.tsx           ← Main app shell (handles global state)
│           ├── main.tsx          ← React entry point
│           ├── index.css         ← Global styles (dark theme)
│           ├── components/       ← Reusable UI pieces
│           │   ├── Header.tsx          ← Top bar with project switcher + framework pills
│           │   ├── Sidebar.tsx         ← Left navigation tabs
│           │   └── ProjectWizardModal.tsx  ← "New Project" popup
│           ├── pages/            ← One file = one screen in the app
│           │   ├── DashboardPage.tsx       ← Home screen stats
│           │   ├── RequirementsPage.tsx    ← Paste requirements here
│           │   ├── TestDesignPage.tsx      ← View generated test cases
│           │   ├── AutomationPage.tsx      ← View & generate test code
│           │   ├── ExecutionPage.tsx       ← Run tests, see console output
│           │   └── TraceabilityPage.tsx    ← Requirement → Test coverage map
│           └── services/
│               └── api.ts        ← All HTTP calls to the backend
│
├── packages/                     ← Shared code libraries (used by the apps)
│   ├── automation-ir/            ← "IR" = Intermediate Representation
│   │   └── src/
│   │       └── index.ts          ← Defines the universal test blueprint all generators read
│   │
│   ├── automation-generators/    ← The code writers — one per framework
│   │   └── src/
│   │       ├── factory.ts        ← Picks the right generator based on framework + language
│   │       │                       PlaywrightGenerator → TS / JS / Java / C#
│   │       │                       CypressGenerator    → TS / JS
│   │       │                       SeleniumGenerator   → Java / C# / JS
│   │       └── generator.interface.ts  ← Shared interface all generators implement
│   │
│   ├── ai-core/                  ← AI/LLM connection layer
│   │   └── src/
│   │       └── index.ts          ← Connects to OpenAI / local LLM for requirement analysis
│   │
│   ├── ai-agents/                ← AI agents that perform specific tasks
│   │   └── src/
│   │       ├── RequirementAnalysisAgent.ts  ← Reads requirement → extracts features
│   │       ├── ScenarioGeneratorAgent.ts    ← Creates test scenarios
│   │       ├── TestCaseGeneratorAgent.ts    ← Creates detailed test cases with steps
│   │       ├── AutomationReviewAgent.ts     ← Reviews generated code quality
│   │       └── FailureAnalysisAgent.ts      ← Explains why a test failed (AI root cause)
│   │
│   ├── database/                 ← Database setup (SQLite via Prisma ORM)
│   │   ├── prisma/
│   │   │   ├── schema.prisma     ← Defines all tables (Project, Requirement, TestCase, etc.)
│   │   │   └── dev.db            ← The actual SQLite database file (local, no server needed)
│   │   └── src/
│   │       └── index.ts          ← Exports the `db` client used everywhere
│   │
│   ├── shared/                   ← Common TypeScript types shared across packages
│   └── testing/                  ← Internal test utilities for this project itself
│
├── package.json                  ← Root config — lists all workspaces (monorepo)
├── tsconfig.json                 ← TypeScript settings for the whole repo
├── .env                          ← Environment variables (API keys, DB path)
├── .env.example                  ← Template for .env — copy this first!
└── clear-exec.js                 ← Utility: clears all execution history from DB

🧠 How the Whole System Works (Step by Step)

YOU type a requirement
        ↓
1️⃣  REQUIREMENT INGESTION
    You type: "Users should be able to log in with email & password"
    → Saved to the database as a Requirement record
        ↓
2️⃣  AI REQUIREMENT ANALYSIS
    RequirementAnalysisAgent reads your text
    → Extracts: features, risks, acceptance criteria
    → Output: "Login Feature → valid credentials → should reach dashboard"
        ↓
3️⃣  TEST SCENARIO GENERATION
    ScenarioGeneratorAgent creates test scenarios
    → "Login with valid credentials"
    → "Login with wrong password"
    → "Login with empty fields"
        ↓
4️⃣  TEST CASE GENERATION
    TestCaseGeneratorAgent writes full test cases with numbered steps
    → TC-001: Navigate → Enter username → Enter password → Click Login → Assert Dashboard
        ↓
5️⃣  CODE GENERATION ✨
    You pick: Framework (Playwright / Cypress / Selenium) + Language (TS / JS / Java / C#)
    → System builds an IR (universal test blueprint)
    → The correct Generator writes framework-specific code
    → Output: TestSpec.java + LoginPage.java + DashboardPage.java + pom.xml
        ↓
6️⃣  TEST EXECUTION
    You click "Run"
    → Backend simulates running the test (real-looking Maven / Playwright / Cypress output)
    → Results stored: PASS ✓ or FAIL ✗
        ↓
7️⃣  FAILURE ANALYSIS (if a test fails)
    FailureAnalysisAgent reads the error and explains it in plain English
    → Suggests a fix (self-healing locator)
        ↓
8️⃣  TRACEABILITY
    Maps Requirement → Scenario → Test Case → Automation → Execution Result
    → Shows test coverage %

🚀 First Time Setup (Step by Step)

Prerequisites

Make sure you have these installed:

Node.js v18 or higher — https://nodejs.org
npm v9 or higher (comes with Node.js)

Step 1 — Copy the environment file

# Windows
copy .env.example .env

# Mac/Linux
cp .env.example .env

Step 2 — Add your API key (optional)

Open .env in any text editor and set:

OPENAI_API_KEY=sk-your-key-here
DATABASE_URL="file:./packages/database/prisma/dev.db"
PORT=4000

Note: The app works without an API key in demo mode. AI features will return smart fallback responses.

Step 3 — Install all dependencies

npm install

This installs packages for the entire monorepo (frontend + backend + all shared packages).

Step 4 — Build the project

npm run build

Compiles all TypeScript code in the correct order.

Step 5 — Set up the database

npx prisma migrate deploy --schema=packages/database/prisma/schema.prisma

Creates the SQLite database at packages/database/prisma/dev.db.

Step 6 — Start the backend (Terminal 1)

npm run dev --workspace=@ai-loop/api

✅ You'll see: 🚀 AI Loop Engineering API Server listening on http://localhost:4000

Step 7 — Start the frontend (Terminal 2)

npm run dev --workspace=@ai-loop/web

✅ You'll see: Local: http://localhost:5173/

Step 8 — Open in browser

Navigate to http://localhost:5173 🎉

🎯 Your First Project (Walkthrough)

1. Create a Project

Click "+ New Project" in the top navigation bar

Fill in the form:

Project Name: Login Feature Tests

Requirement (paste this):

Users should be able to login with a valid username and password.
Invalid credentials should show an error message.
Empty fields should show a validation error.

Framework: Playwright
Language: TypeScript

Click "Create Project & Run AI Pipeline"
Wait ~10 seconds — AI runs all 4 stages automatically

2. View Generated Test Cases

Click Test Design in the sidebar
You'll see test cases like TC-001: Login with valid credentials
Each test case has: Priority, Steps, Expected Result, Automation Candidate flag

3. Generate Selenium Java Code

Click Automation Code in the sidebar
Click SELENIUM (framework pill) → pill highlights amber
Click Java (language pill) → pill highlights purple
Click Generate SELENIUM · Java
4 file tabs appear:
- TC001Test.java — JUnit 5 test class with 6 test steps
- LoginPage.java — Page Object with WebDriverWait
- DashboardPage.java — Dashboard assertions
- pom.xml — Maven config with Selenium 4 + WebDriverManager

4. Run the Tests

Click Execution Console in the sidebar
Select SELENIUM and Java using the pills
Click Run SELENIUM (JAVA) Test Suite
Watch the 5 steps animate green one by one
Banner shows: ✅ ALL PASSED — 1 test(s) completed
Console shows full Maven BUILD SUCCESS output

5. Check Traceability

Click Traceability in the sidebar
See the full chain: Requirement → Scenario → Test Case → Code → Result

🔌 API Reference

Method	URL	What It Does
`POST`	`/api/projects`	Create a new project
`GET`	`/api/projects`	List all projects
`GET`	`/api/projects/:id`	Get full project details
`POST`	`/api/requirements`	Save a requirement
`POST`	`/api/requirements/:id/analyze`	Run AI analysis
`POST`	`/api/requirements/:id/scenarios/generate`	Generate test scenarios
`POST`	`/api/requirements/:id/test-cases/generate`	Generate test cases
`POST`	`/api/automation/generate`	Generate test code
`POST`	`/api/execution/run`	Execute tests
`DELETE`	`/api/execution/history/:projectId`	Clear old run history
`GET`	`/api/projects/:id/traceability`	Get traceability matrix

🧰 Framework & Language Support Matrix

Framework	TypeScript	JavaScript	Java	C#
Playwright	✅ Full POM + spec	✅ Full POM + spec	✅ JUnit 5 + pom.xml	✅ NUnit + .csproj
Cypress	✅ cy.ts + page	✅ cy.js + page	❌ Not supported	❌ Not supported
Selenium	❌	✅ Mocha + WebDriver	✅ JUnit 5 + WebDriverManager + pom.xml	✅ NUnit + ChromeDriver + .csproj

What Gets Generated (Selenium + Java)

📁 Generated Files
├── src/
│   ├── main/java/com/ailoop/pages/
│   │   ├── LoginPage.java        ← @FindBy, WebDriverWait, ExpectedConditions
│   │   └── DashboardPage.java    ← Post-login assertions
│   └── test/java/com/ailoop/tests/
│       └── TC001Test.java        ← JUnit 5, @BeforeEach, @Test, @AfterEach
└── pom.xml                       ← Selenium 4.21 + WebDriverManager + Maven Surefire

Run Commands

# Selenium Java
mvn test -Dtest=TC001Test

# Selenium C#
dotnet test

# Selenium JavaScript
npx mocha tests/**/*.test.js

# Playwright TypeScript
npx playwright test

# Playwright Java
mvn test

# Cypress TypeScript
npx cypress run

🗄️ Database Schema

Project
  ├── id, name, framework, language, targetAppUrl
  │
  └── Requirement
        ├── rawText (your pasted requirement)
        ├── analyzedData (AI extraction result)
        │
        └── AcceptanceCriteria (AC-001, AC-002...)
        └── TestScenario (SCN-001, SCN-002...)
              └── TestCase (TC-001, TC-002...)
                    ├── steps (JSON array of numbered steps)
                    ├── priority, severity, testType
                    │
                    └── AutomationTest (AT-001...)
                          ├── framework, language
                          ├── generatedCode (the test spec code)
                          ├── pageObjects (JSON map of file → code)
                          ├── qualityScore (AI review score)
                          │
                          └── Execution (RUN-001...)
                                ├── status: RUNNING → COMPLETED
                                ├── passedCount, failedCount
                                │
                                └── ExecutionResult (per test)
                                      ├── status: PASS / FAIL
                                      ├── stdout (console output)
                                      │
                                      └── Failure (if test failed)
                                            ├── errorMessage
                                            ├── aiDiagnosis
                                            └── healedLocator

🛠️ Troubleshooting

Problem	Solution
Port 4000 already in use	`Stop-Process -Id (Get-NetTCPConnection -LocalPort 4000).OwningProcess -Force`
Port 5173 already in use	`Stop-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess -Force`
Tests show FAILED from old runs	`node clear-exec.js`
Build fails (TypeScript errors)	`npm run build` from root folder
Framework pills not responding	Hard refresh: `Ctrl + Shift + R`
Database migration error	`npx prisma migrate reset --schema=packages/database/prisma/schema.prisma`
"No test case found" error	Create a project first using the wizard
AI features not working	Check `OPENAI_API_KEY` in `.env` (app works without it in demo mode)

🏗️ Technology Stack

Layer	Technology	Purpose
Frontend	React 18 + TypeScript + Vite	Fast SPA with hot module reload
Styling	Vanilla CSS + Custom dark theme	Zero framework dependency
Backend	Node.js + Express + TypeScript	REST API server
ORM	Prisma	Type-safe database queries
Database	SQLite (`dev.db`)	Local, zero-config storage
AI	OpenAI GPT (optional)	Requirement analysis + code review
Code Gen	Custom Generator Classes	Framework-specific test code
Monorepo	npm Workspaces	All packages in one repo
Build	TypeScript compiler (tsc)	Compile-time safety

👨‍💻 Developer Tips

# Build only one package (faster than full build)
npm run build --workspace=@ai-loop/automation-generators

# Watch API logs
# Check the terminal running:  npm run dev --workspace=@ai-loop/api

# Clear all execution history (when tests show stale FAIL data)
node clear-exec.js

# Check what's running on a port (Windows PowerShell)
Get-NetTCPConnection -LocalPort 4000

# Force kill a port (Windows PowerShell)
Stop-Process -Id (Get-NetTCPConnection -LocalPort 4000).OwningProcess -Force

Built with ❤️ — AI Loop Engineering: Autonomous STLC & Test Automation Platform

Name		Name	Last commit message	Last commit date
apps		apps
packages		packages
.env.example		.env.example
.gitignore		.gitignore
API.md		API.md
ARCHITECTURE.md		ARCHITECTURE.md
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
cleanup-db.js		cleanup-db.js
clear-exec.js		clear-exec.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

🤖 AI Loop Engineering

AI-Powered Software Testing Platform — Layman's Guide

📺 What Does It Look Like?

🗂️ Project Folder Structure (Plain English)

🧠 How the Whole System Works (Step by Step)

🚀 First Time Setup (Step by Step)

Prerequisites

Step 1 — Copy the environment file

Step 2 — Add your API key (optional)

Step 3 — Install all dependencies

Step 4 — Build the project

Step 5 — Set up the database

Step 6 — Start the backend (Terminal 1)

Step 7 — Start the frontend (Terminal 2)

Step 8 — Open in browser

🎯 Your First Project (Walkthrough)

1. Create a Project

2. View Generated Test Cases

3. Generate Selenium Java Code

4. Run the Tests

5. Check Traceability

🔌 API Reference

🧰 Framework & Language Support Matrix

What Gets Generated (Selenium + Java)

Run Commands

🗄️ Database Schema

🛠️ Troubleshooting

🏗️ Technology Stack

👨‍💻 Developer Tips

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🤖 AI Loop Engineering

AI-Powered Software Testing Platform — Layman's Guide

📺 What Does It Look Like?

🗂️ Project Folder Structure (Plain English)

🧠 How the Whole System Works (Step by Step)

🚀 First Time Setup (Step by Step)

Prerequisites

Step 1 — Copy the environment file

Step 2 — Add your API key (optional)

Step 3 — Install all dependencies

Step 4 — Build the project

Step 5 — Set up the database

Step 6 — Start the backend (Terminal 1)

Step 7 — Start the frontend (Terminal 2)

Step 8 — Open in browser

🎯 Your First Project (Walkthrough)

1. Create a Project

2. View Generated Test Cases

3. Generate Selenium Java Code

4. Run the Tests

5. Check Traceability

🔌 API Reference

🧰 Framework & Language Support Matrix

What Gets Generated (Selenium + Java)

Run Commands

🗄️ Database Schema

🛠️ Troubleshooting

🏗️ Technology Stack

👨‍💻 Developer Tips

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages