Zelqa v1.0

A lightweight, AI-powered QA management framework that bridges the gap between manual testing and full automation — built for solo QA engineers in fast-moving startup environments.

Zelqa transforms raw requirements into structured, risk-assessed test cases using a local LLM (Ollama), tracks the full QA lifecycle from generation to defect resolution, and produces professional HTML dashboards and exportable reports — all without sending your data to the cloud.

---

Table of Contents

• Overview
• Key Features
• Architecture
• Prerequisites
• Installation
• Configuration
• Full Workflow
• Module Reference
• Database Schema
• Export Formats
• Troubleshooting
• Version History

---

Overview

Zelqa v1.0 covers the complete QA lifecycle in a single, self-contained Python project:

Requirements Input
      ↓
LLM Test Case Generation  ←  Ollama (local)
      ↓
Risk Assessment (BVA + RBT)
      ↓
Human Curator Review
      ↓
Test Execution Tracking  →  Defect Management
      ↓
LLM Quality Evaluation   →  RTM (Traceability)
      ↓
Metrics & Analytics      →  Version Control
      ↓
HTML Dashboard + Export (Excel / PDF / CSV)

Design principles:

• Local-first — all LLM inference runs on your machine via Ollama. No API keys, no data leaves your environment.
• Human-in-the-loop — AI generates and assesses, humans approve. Every critical decision goes through curator review.
• Incremental — each module is independent and can be run standalone.
• Solo QA friendly — designed for a single QA engineer managing multiple features without a dedicated team.

---

Key Features

Feature	Description
LLM Test Generation	Paste raw requirements → LLM generates Positive, Negative, Boundary, and Edge Case scenarios
Risk-Based Testing	Risk score (Probability × Impact, max 25) with LLM reasoning per test case
RBT Expansion	LLM generates additional test cases targeting High/Critical risk areas
Testing Approach	LLM recommends testing method per case (Manual, Automation, Security, Performance, etc.)
Curator CLI	Interactive terminal review — Approve/Reject/Skip, prioritized by risk level
Execution Tracker	Log Pass/Fail/Skip/Blocked per sprint with actual results
Defect Manager	Bug reports auto-drafted by LLM from failed test cases
LLM Quality Evaluator	5-criteria rubric scores LLM output quality per batch
RTM	Requirements Traceability Matrix — maps requirements to test cases, shows coverage gaps
Metrics Engine	Pass rate trend, defect density, test coverage — all per sprint
Version Manager	Detects outdated test cases when requirements change, tracks full change history
HTML Dashboard	Dark-mode report with risk matrix, expandable rows, all sections in one page
Multi-format Export	Excel, PDF, CSV for Jira and TestRail

---

Architecture

ZelqaCase/
│
├── data/
│   └── zelqa.db            ← SQLite database (auto-created)
│
├── src/
│   ├── config.py                ← Central configuration
│   ├── ollama_client.py         ← Ollama API wrapper (model-agnostic)
│   ├── setup_db.py              ← Database initialization & schema migration
│   │
│   ├── llm_intake.py            ← Requirements → test case generation
│   ├── risk_engine.py           ← Risk assessment + RBT expansion
│   ├── curator_cli.py           ← Human review interface
│   │
│   ├── execution_tracker.py     ← Test execution logging per sprint
│   ├── defect_manager.py        ← Bug report creation & management
│   │
│   ├── llm_evaluator.py         ← LLM output quality evaluation
│   ├── rtm.py                   ← Requirements Traceability Matrix
│   │
│   ├── metrics_engine.py        ← QA metrics & analytics per sprint
│   ├── version_manager.py       ← Test case versioning & outdated detection
│   │
│   ├── generate_html_report.py  ← Full HTML dashboard generator
│   └── export_manager.py        ← Excel, PDF, CSV export
│
├── exports/                     ← Export output folder (auto-created)
├── requirements.txt
└── README.md

---

Prerequisites

• Python 3.8 or higher
• Ollama — local LLM runtime (https://ollama.ai)
• A pulled Ollama model (see Configuration)

Installing Ollama

1. Download from https://ollama.ai/download
2. Install and start the service:

   ollama serve

3. Pull a model (in a separate terminal):

   # Recommended for 8GB RAM
   ollama pull gemma3:1b
   
   # Better quality if you have 16GB+
   ollama pull llama3.2

---

Installation

# 1. Navigate to the project folder
cd Zelqa

# 2. Install Python dependencies
pip install -r requirements.txt

# 3. Initialize the database
python src/setup_db.py

requirements.txt:

requests>=2.31.0
flask>=3.0.0
openpyxl>=3.1.0
reportlab>=4.0.0

---

Configuration

All settings live in src/config.py. Edit this file — no other files need to change.

# Ollama
OLLAMA_BASE_URL = "http://localhost:11434"
OLLAMA_MODEL    = "gemma3:1b"   # Change to any model you have pulled
OLLAMA_TIMEOUT  = 120           # Increase if model is slow (seconds)

# Risk thresholds (Probability × Impact score)
RISK_THRESHOLD = {
    "critical": 20,   # score >= 20
    "high":     12,   # score >= 12
    "medium":    6,   # score >= 6
    # below 6 = Low
}

# Generation limits
MAX_GENERATED_CASES_PER_FEATURE = 15
MIN_RISK_TO_EXPAND = "high"     # Expand at this level and above

# Report
REPORT_OUTPUT_PATH = "test_report.html"

Model recommendations by RAM:

RAM	Model	Pull Command
4–8 GB	gemma3:1b	ollama pull gemma3:1b
8–16 GB	llama3.2	ollama pull llama3.2
16 GB+	llama3.2 or mistral	ollama pull mistral

---

Full Workflow

Step 1 — Initialize Database

python src/setup_db.py

Creates all 8 tables. Safe to re-run — existing data is preserved and schema is migrated automatically.

Step 2 — Generate Test Cases

python src/llm_intake.py

Enter a feature name, paste your requirements, type END to finish. The LLM generates Positive, Negative, Boundary, and Edge Case scenarios with risk scores and testing approach tags.

Example input:

Feature Name: User Login

Users must be able to log in using a valid email and password.
Password must be at least 8 characters and no more than 32 characters.
If the wrong password is entered 3 times in a row, the account is locked for 15 minutes.
Email must be in a valid format containing @ and a domain.
Upon successful login, the user is redirected to the dashboard.
END

Step 3 — Risk Engine

python src/risk_engine.py

• Option 1: Re-assess risk for all test cases
• Option 2: Generate additional test cases in High/Critical areas
• Option 3: Both (recommended)

Step 4 — Curator Review

python src/curator_cli.py

Interactive review sorted by risk level. Controls: A Approve · R Reject · S Skip · Q Quit

Step 5 — LLM Quality Evaluation

python src/llm_evaluator.py

Scores each test case on a 5-criteria rubric (1–5 per criterion, total max 25):

Criterion	What it measures
Accuracy	Technically correct and matches the requirement
Relevance	Targets the right feature and scenario
Completeness	Covers happy path, negative, and boundary cases
Clarity	Steps and expected results are unambiguous
Safety	Considers security and data sensitivity

Step 6 — Requirements Traceability Matrix

python src/rtm.py

Paste your requirements (one per line) → LLM maps each to existing approved test cases → displays Covered / Partial / Not Covered with coverage percentage.

Step 7 — Test Execution

python src/execution_tracker.py

Log results per sprint. For each test case: P Pass · F Fail · S Skip · B Blocked. When a test fails, you are prompted to provide the actual result and optionally generate a bug report immediately.

Step 8 — Defect Management

python src/defect_manager.py

View, create, and update bug reports. LLM-drafted defects are marked with a badge. Update status as fixes progress: Open → In Progress → Fixed → Verified → Closed.

Step 9 — Metrics

python src/metrics_engine.py

Prints a per-sprint report: pass rate trend, defect density, test coverage by feature and risk level, LLM quality score trend by batch.

Step 10 — Version Management

python src/version_manager.py

When requirements change, paste the new version → LLM compares against all active test cases → classifies each as valid, needs_update, or outdated → interactive review to Retire, Keep (flag), or Ignore.

Step 11 — Generate HTML Report

python src/generate_html_report.py

Generates test_report.html. Open in any browser. Contains:

• Stats overview (total, approved, pending, rejected)
• QA Metrics per sprint (pass rate + defect density bars, coverage by risk)
• Risk distribution + Risk Matrix heatmap
• Execution results + Defect overview cards
• Version & Outdated tracker
• LLM Quality Evaluation (per batch cards + detail table)
• Defect Log (expandable rows)
• Full Test Scenario table (expandable with testing approach badges)

Step 12 — Export

python src/export_manager.py

Step 1: Choose content — Test Cases / Defects / Both
Step 2: Choose format — All / Excel / PDF / CSV Jira / CSV TestRail

All files saved to exports/ with timestamp in filename.

---

Module Reference

Module	Standalone	Key Function(s)
config.py	—	Settings only
ollama_client.py	✅	generate(), generate_json(), check_ollama_connection()
setup_db.py	✅	setup_database(), get_connection()
llm_intake.py	✅	process_requirements(text, feature, source)
risk_engine.py	✅	assess_all(), expand_risks()
curator_cli.py	✅	run_curator(risk_filter, feature_id)
execution_tracker.py	✅	log_execution(), get_execution_summary()
defect_manager.py	✅	create_defect(), create_defect_from_execution()
llm_evaluator.py	✅	evaluate_batch(), get_eval_summary()
rtm.py	✅	build_rtm(), get_rtm_summary()
metrics_engine.py	✅	get_all_metrics(), get_pass_rate_trend()
version_manager.py	✅	detect_outdated(), retire_scenario(), record_version()
generate_html_report.py	✅	generate_report()
export_manager.py	✅	run_export(formats, content)

---

Database Schema

8 tables in data/zelqa.db:

Table	Description
features	Feature registry
test_scenarios	All test cases with risk, version, and status
requirements_log	Raw requirement inputs
execution_log	Test execution results per sprint
defects	Bug reports linked to test scenarios
llm_eval_log	LLM quality scores per test case per batch
rtm_links	Requirement → test case traceability
tc_versions	Version history snapshots

Key columns in test_scenarios

Column	Type	Values
status	TEXT	Pending / Approved / Rejected / Retired
risk_level	TEXT	Critical / High / Medium / Low / Unassessed
risk_score	INTEGER	1–25 (probability × impact)
probability_of_failure	INTEGER	1–5
business_impact	INTEGER	1–5
testing_approach	TEXT	Comma-separated (e.g. "Manual Testing, Security Testing")
source	TEXT	manual / bva_engine / llm_intake / llm_rbt
version_no	INTEGER	Increments on each change
is_outdated	INTEGER	0 = current, 1 = flagged outdated

---

Export Formats

Excel (.xlsx)

Content	Sheets
Test Cases	Test Cases + Risk Summary
Defects	Defects
Both	Test Cases + Defects + Summary

Colored cells for risk level and status. Auto-filter enabled. Frozen header row.

PDF (.pdf)

Landscape A4. Cover page with timestamp, summary stats, full data table. Page break between sections when exporting both.

CSV — Jira

• Test cases → Issue Type: Test, priority mapped from risk level
• Defects → Issue Type: Bug
• Custom fields: Risk Level, Risk Score, Test Type, Feature, Testing Approach

CSV — TestRail

Standard TestRail import format: Title, Section, Type, Priority, Preconditions, Steps, Expected Result, plus custom columns for risk data.

---

Troubleshooting

Problem	Solution
❌ Cannot connect to Ollama	Run ollama serve in a separate terminal
⏱️ Timeout	Increase OLLAMA_TIMEOUT in config.py or use a smaller model
⚠️ Failed to parse JSON	Switch to a larger model (llama3.2) for better structured output
RTM shows only 1 requirement	Paste requirements one sentence per line — parser uses line count as hint
Score shows > 25	Update to latest llm_intake.py and risk_engine.py — clamp fix included
no such column: status	Replace setup_db.py with v3.0 version and re-run
No test cases match the filter	Run curator_cli.py first to approve test cases

---

Version History

v1.0 (current) — Initial Public Release

Full QA lifecycle from requirements to reporting:

• llm_intake.py — raw requirements → LLM-generated test cases
• risk_engine.py — LLM risk assessment and RBT expansion
• curator_cli.py — human-in-the-loop review interface
• execution_tracker.py — sprint-based test execution logging
• defect_manager.py — bug report management with LLM auto-draft
• llm_evaluator.py — 5-criteria LLM output quality rubric
• rtm.py — Requirements Traceability Matrix
• metrics_engine.py — per-sprint QA analytics
• version_manager.py — test case versioning and outdated detection
• generate_html_report.py — full HTML dashboard with dark theme
• export_manager.py — Excel, PDF, CSV for Jira and TestRail

---

Zelqa v1.0 — AI-powered QA, local-first, built for solo engineers.