scriptgini 0.1.2__tar.gz

scriptgini-0.1.2/PKG-INFO

@@ -0,0 +1,381 @@
+Metadata-Version: 2.4
+Name: scriptgini
+Version: 0.1.2
+Summary: Agentic AI system that converts functional test cases into automation test scripts.
+Author: ScriptGini Team
+License: Proprietary
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# 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
+
+```bat
+start.bat
+```
+
+### Linux / macOS
+
+```bash
+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:
+
+```bash
+cp .env.example .env
+```
+
+```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)
+
+```http
+POST /api/v1/projects/
+```
+
+```json
+{
+  "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
+
+```http
+POST /api/v1/projects/{project_id}/test-cases/
+```
+
+```json
+{
+  "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
+
+```http
+POST /api/v1/projects/{project_id}/test-cases/{tc_id}/scripts/generate
+```
+
+```json
+{
+  "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
+
+```http
+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
+
+```http
+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
+
+```http
+GET /api/v1/projects/{project_id}/test-cases/{tc_id}/scripts/{script_id}/runs
+```
+
+#### 7. Bulk Generate Scripts (Project-level)
+
+```http
+POST /api/v1/projects/{project_id}/scripts/bulk-generate
+```
+
+```json
+{
+  "llm_provider": "openrouter",
+  "llm_model": "openai/gpt-4o",
+  "framework": "playwright_python",
+  "test_case_ids": [1, 2, 3]
+}
+```
+
+#### 8. Bulk Run Latest Completed Scripts
+
+```http
+POST /api/v1/projects/{project_id}/scripts/bulk-run
+```
+
+#### 9. Poll Bulk Job Status
+
+```http
+GET /api/v1/projects/{project_id}/scripts/bulk-jobs/{job_id}
+```
+
+#### 10. Get Run Analytics (Project-level)
+
+```http
+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:
+
+```bash
+# 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:
+
+```bat
+test.bat
+audit.bat
+trivy.bat
+```
+
+```bash
+./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