scriptgini 1.0.5

Agentic AI system that converts functional test cases into automation test scripts.

ScriptGini

Enterprise-grade Agentic AI system that converts functional test cases into high-quality, review-ready automation test scripts.

---

What is ScriptGini?

ScriptGini is an AI-powered test automation engine built for Quality Engineering teams. You feed it a functional test case and an Application Under Test (AUT) URL — it returns a production-ready automation script in your chosen framework, generated by a multi-step LangGraph agent that reasons about test intent before writing a single line of code.

---

Features

• Agentic 3-node LangGraph pipeline — Intent analysis → Script generation → Quality review
• Multi-provider LLM support — OpenAI, Ollama (local), OpenRouter, Google Gemini, AWS Bedrock
• Framework-agnostic output — Playwright Python, Selenium Python, UFT VBScript, Cypress JS
• Intelligent selector strategy — Role → Label → data-testid → CSS → XPath (last resort)
• Project & AUT management — Store multiple projects, each with its own base URL and defaults
• Full test case history — Every generated script is stored in SQLite with status and token usage
• Execution history persistence — Every run is stored in script_runs with stdout/stderr, exit code, and duration
• Hardened execution sandbox — Script runs use isolated Python mode, static safety validation, and restricted environment variables
• Bulk job orchestration — Project-level bulk generate and bulk run with pollable job status
• Run analytics dashboard — Project-level pass/fail/timeout metrics and recent failure feed
• Richer test case intake — Import .txt, .md, .json, .csv, .feature, .yml/.yaml, and .xlsx
• Import preview mapping — Preview parsed scenarios in the UI before creating a project workspace
• REST API — FastAPI with auto-generated Swagger UI
• Alembic migrations — Safe, versioned schema management over SQLite

---

Tech Stack

Layer	Technology
API	FastAPI + Uvicorn
Agentic AI	LangGraph + LangChain
LLM Providers	OpenAI, Ollama, OpenRouter, Gemini, Bedrock
Database	SQLite
ORM	SQLAlchemy 2.0
Migrations	Alembic
Config	Pydantic Settings (.env)

---

Quick Start

Windows

start.bat

Linux / macOS

chmod +x start.sh
./start.sh

The script will:

1. Create a Python virtual environment
2. Install all dependencies
3. Copy .env.example → .env if missing (edit it before re-running)
4. Run Alembic migrations
5. Start the server and open Swagger UI in your browser

To load a ready-made sample workspace, use the Load Demo Project button in the web UI or call POST /api/v1/demo/load.

---

Configuration

Copy .env.example to .env and fill in the values you need:

cp .env.example .env

# Choose your default provider
DEFAULT_LLM_PROVIDER=openrouter   # openai | ollama | openrouter | gemini | bedrock

# OpenAI
OPENAI_API_KEY=your_openai_api_key_here

# Ollama (local — no key needed)
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3
OLLAMA_NUM_PREDICT=700

# Generation latency controls
LLM_REQUEST_TIMEOUT_SECONDS=45
SCRIPT_GENERATION_TIMEOUT_SECONDS=180
SKIP_REVIEW_FOR_OLLAMA=true

# OpenRouter
OPENROUTER_API_KEY=your_openrouter_api_key_here
OPENROUTER_MODEL=openai/gpt-4o

# Google Gemini
GOOGLE_API_KEY=your_google_api_key_here

# AWS Bedrock
AWS_ACCESS_KEY_ID=your_aws_access_key_id
AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key
AWS_REGION_NAME=us-east-1

.env is git-ignored. Never commit real API keys.

If local generation feels slow, reduce OLLAMA_NUM_PREDICT, keep SKIP_REVIEW_FOR_OLLAMA=true, or switch to a smaller/faster Ollama model.

---

API Reference

Once running, visit:

URL	Description
http://localhost:8000/docs	Swagger UI (interactive)
http://localhost:8000/redoc	ReDoc
http://localhost:8000/health	Health check

Core Workflow

1. Create a Project (AUT)

POST /api/v1/projects/

{
  "name": "My Web App",
  "aut_base_url": "https://example.com",
  "default_framework": "playwright_python",
  "selector_preference": "role",
  "auth_hints": "Login with admin/admin on /login"
}

2. Add a Test Case

POST /api/v1/projects/{project_id}/test-cases/

{
  "title": "TC-001 Successful Login",
  "format": "step_based",
  "content": "Step 1: Navigate to /login\nStep 2: Enter username 'admin'\nStep 3: Enter password 'admin123'\nStep 4: Click Login button\nExpected: User is redirected to /dashboard and sees 'Welcome' message",
  "preconditions": "User account exists in the system",
  "test_data_hints": "username=admin, password=admin123"
}

3. Generate a Script

POST /api/v1/projects/{project_id}/test-cases/{tc_id}/scripts/generate

{
  "llm_provider": "openrouter",
  "llm_model": "openai/gpt-4o",
  "framework": "playwright_python"
}

Returns 202 Accepted immediately. The agent runs in the background.

4. Poll for the Result

GET /api/v1/projects/{project_id}/test-cases/{tc_id}/scripts/{script_id}

Status values: pending → generating → completed | failed

5. Run a Generated Playwright Script

POST /api/v1/projects/{project_id}/test-cases/{tc_id}/scripts/{script_id}/run

Returns a persisted run record with:

• status (completed | failed | timed_out)
• stdout, stderr
• exit_code, duration_seconds

Execution safeguards:

• Script content is statically validated before execution.
• Unsafe imports and unsafe builtin calls are rejected and persisted as failed runs.
• Runtime uses Python isolated mode with a restricted environment.

6. List Script Run History

GET /api/v1/projects/{project_id}/test-cases/{tc_id}/scripts/{script_id}/runs

7. Bulk Generate Scripts (Project-level)

POST /api/v1/projects/{project_id}/scripts/bulk-generate

{
  "llm_provider": "openrouter",
  "llm_model": "openai/gpt-4o",
  "framework": "playwright_python",
  "test_case_ids": [1, 2, 3]
}

8. Bulk Run Latest Completed Scripts

POST /api/v1/projects/{project_id}/scripts/bulk-run

9. Poll Bulk Job Status

GET /api/v1/projects/{project_id}/scripts/bulk-jobs/{job_id}

10. Get Run Analytics (Project-level)

GET /api/v1/projects/{project_id}/analytics/runs

Returns aggregate execution metrics and latest failure details.

---

LangGraph Agent Pipeline

┌─────────────────┐     ┌──────────────────┐     ┌───────────────┐
│  parse_intent   │────▶│ generate_script  │────▶│ review_script │
│                 │     │                  │     │               │
│ Extracts:       │     │ Produces full    │     │ QA checks:    │
│ • Business goal │     │ framework-       │     │ • Assertions  │
│ • Actions list  │     │ specific script  │     │ • TODO markers│
│ • Assertions    │     │                  │     │ • Rewrites if │
│ • Preconditions │     │                  │     │   needed      │
└─────────────────┘     └──────────────────┘     └───────────────┘

---

Supported Frameworks

Key	Framework
playwright_python	Playwright for Python (default)
selenium_python	Selenium WebDriver Python
uft_vbscript	UFT / QTP VBScript
cypress_js	Cypress JavaScript

---

Project Structure

scriptgini/
├── app/
│   ├── main.py                   # FastAPI application
│   ├── config.py                 # Settings loaded from .env
│   ├── database.py               # SQLAlchemy engine + session
│   ├── models/
│   │   ├── project.py            # Project / AUT model
│   │   ├── test_case.py          # Test case model
│   │   └── generated_script.py  # Script history model
│   ├── schemas/                  # Pydantic request/response schemas
│   ├── routers/
│   │   ├── projects.py           # CRUD — projects
│   │   ├── test_cases.py         # CRUD — test cases
│   │   └── scripts.py            # Generate + history
│   ├── agents/
│   │   ├── script_gini_agent.py  # LangGraph graph definition
│   │   └── prompts.py            # All prompt templates
│   └── llm/
│       └── provider.py           # LLM provider factory
├── alembic/                      # Database migration scripts
├── alembic.ini
├── requirements.txt
├── .env.example                  # Template — copy to .env
├── start.bat                     # Windows launcher
└── start.sh                      # Linux / macOS launcher

---

Database Migrations

Migrations are handled automatically by start.bat / start.sh.

To run manually:

# Apply all pending migrations
alembic upgrade head

# Create a new migration after model changes
alembic revision --autogenerate -m "description"

# Rollback one step
alembic downgrade -1

---

Quality Gate Policy

Every check-in is expected to pass:

1. Unit tests
2. 100% coverage on app/
3. pip-audit
4. Trivy filesystem scan

Local commands:

test.bat
audit.bat
trivy.bat

./test.sh
./audit.sh
./trivy.sh

A CI gate is configured in .github/workflows/quality-gate.yml to enforce the same checks on push/PR.

---

Adding a New LLM Provider

1. Add config keys to app/config.py
2. Add a new _provider() function in app/llm/provider.py
3. Register it in get_llm() and the LLMProvider type alias
4. Add the corresponding key to .env.example

---

Security Notes

• .env is git-ignored — never commit API keys
• The API has no authentication by default — add an API key middleware before exposing to a network
• UI validation only — the agent never makes live requests to the AUT

---

License

MIT