AI BDD Test Generator

This project generates Gherkin .feature files from a live website by combining Playwright, DOM analysis, and LLM-assisted orchestration.

The current workflow supports three entry points:

• main.py for the CLI pipeline
• streamlit_app.py for the browser-based UI
• api.py for the FastAPI backend and browser UI

What the pipeline does

1. Capture and cache a DOM snapshot for the target URL.
2. Use a provider such as Ollama, OpenAI, Gemini, or Groq to select hover and popup candidates.
3. Run interactions with Playwright and record what changed.
4. Write the final Gherkin output and a run report to output/.

Project layout

| File | Purpose | |------|---------| | main.py | CLI entry point and four-stage pipeline orchestration | | dom_analyzer.py | Captures the DOM, injects node tags, and stores cache data | | crew_orchestrator.py | Runs the AI selection and Gherkin generation step | | interaction_engine.py | Executes hover and click interactions and records evidence | | llm_provider.py | Builds provider-specific LLM clients | | streamlit_app.py | Streamlit UI for pasting a URL and generating .feature output | | api.py | FastAPI app with JSON endpoints and a simple HTML UI |

Requirements

• Python 3.11 or newer
• Playwright browser binaries
• A running LLM provider when using the AI path

Installation

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
playwright install chromium

Running the project

CLI pipeline:

python main.py --url https://www.tivdak.com/patient-stories/

Streamlit UI:

streamlit run streamlit_app.py

FastAPI backend:

uvicorn api:app --reload

AI BDD Test Generator

This project generates Gherkin .feature files from a live website by combining Playwright, DOM analysis, and LLM-assisted orchestration.

Entry points

• main.py runs the CLI pipeline.
• streamlit_app.py launches the Streamlit UI.
• api.py exposes the FastAPI backend and HTML UI.

The real implementation now lives in the bdd_generator/ package. The root files are thin wrappers so the original commands still work.

Folder structure

assignment/
├── api.py                # Wrapper for the FastAPI app
├── bdd_generator/        # Main application package
│   ├── __init__.py
│   ├── api.py
│   ├── crew_orchestrator.py
│   ├── dom_analyzer.py
│   ├── interaction_engine.py
│   ├── llm_provider.py
│   ├── main.py
│   └── streamlit_app.py
├── cache/                # Runtime DOM cache and screenshots
├── docs/                 # Project documentation and sample logs
│   └── sample_console_log.txt
├── output/               # Generated feature files, reports, and screenshots
├── README.md
├── requirements.txt
├── main.py               # Wrapper for bdd_generator.main
└── streamlit_app.py      # Wrapper for bdd_generator.streamlit_app

What the pipeline does

1. Capture and cache a DOM snapshot for the target URL.
2. Use a provider such as Ollama, OpenAI, Gemini, or Groq to select hover and popup candidates.
3. Run interactions with Playwright and record what changed.
4. Write the final Gherkin output and a run report to output/.

Requirements

• Python 3.11 or newer
• Playwright browser binaries
• A running LLM provider when using the AI path

Installation

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
playwright install chromium

Running the project

CLI pipeline:

python main.py --url https://www.tivdak.com/patient-stories/

Streamlit UI:

streamlit run streamlit_app.py

FastAPI backend:

uvicorn api:app --reload

Provider options

The pipeline supports these providers through the shared LLM factory:

• ollama
• openai
• gemini
• groq

For Ollama, llama3.2 is the default model.

Output files

The pipeline writes its results to output/:

• tests.feature
• pipeline_report.json
• interaction_log.json
• interaction screenshots for hover and click runs

The DOM cache is stored under cache/, including dom_cache.sqlite and dom_snapshot.json.

Example run

python main.py --url https://www.tivdak.com/patient-stories/ --force-refresh

Notes

• Streamlit uses a separate execution path from FastAPI, but both call into the same pipeline code.
• The Streamlit page icon remains the only emoji in the project by design.

Technical overview

Stage 1: DOM analysis

bdd_generator/dom_analyzer.py launches Playwright, injects node tags, parses the rendered DOM, and caches the result.

Stage 2: AI orchestration

bdd_generator/crew_orchestrator.py selects likely hover and popup targets and writes the initial Gherkin skeleton.

Stage 3: Interaction engine

bdd_generator/interaction_engine.py executes hover and click actions, then compares the DOM before and after each interaction.

Stage 4: Reporting

bdd_generator/main.py combines the stage outputs, writes the final report, and prints a summary.

Sample log

The example console output is stored in docs/sample_console_log.txt.

### "networkidle timeout"

Sites with infinite scroll or WebSocket connections may never reach `networkidle`.
The fallback (`domcontentloaded`) handles this automatically. You can also increase timeout:

```python
# In dom_analyzer.py, line ~90, increase timeout_ms:
analyzer = DOMAnalyzer(headless=True, timeout_ms=60_000)

"No nodes tagged / 0 nodes"

The site may use heavy bot-detection. Try:

python main.py --url <URL> --no-headless

This opens a visible browser which is less likely to be detected as a bot.

"Gherkin content is empty"

Likely Ollama model capacity issue. Try a larger model:

ollama pull llama3.2:7b
python main.py --url <URL> --model llama3.2:7b

Low-RAM machines (< 8 GB)

ollama pull phi4-mini
python main.py --url <URL> --model phi4-mini

---

Project Structure

ai-bdd-test-generator/
├── main.py                  # CLI entry point + pipeline orchestrator
├── dom_analyzer.py          # Stage 1: Playwright + BS4 + SQLite DOM analysis
├── crew_orchestrator.py     # Stage 2: CrewAI + Ollama agent pipeline
├── interaction_engine.py    # Stage 3: Playwright interaction + DOM diffing
├── requirements.txt         # Python dependencies
├── README.md                # This file
├── .env.example             # Example environment variables
├── cache/                   # Auto-created: SQLite DB + JSON snapshots
│   ├── dom_cache.sqlite
│   └── dom_snapshot.json
└── output/                  # Auto-created: Gherkin + logs + screenshots
   ├── hover_tests.feature  # Main deliverable
    ├── pipeline_report.json
    ├── interaction_log.json
    └── *.png                # Interaction screenshots

---

Environment Variables (optional)

Create a .env file to override defaults without CLI flags:

OLLAMA_MODEL=llama3.2
OLLAMA_BASE_URL=http://localhost:11434

Load it by adding from dotenv import load_dotenv; load_dotenv() at the top of main.py.

---

Tech Stack Summary

| Layer | Technology | Why | |-------|-----------|-----| | Browser Automation | Playwright (async) | Faster than Selenium, native async, better JS execution | | HTML Parsing | BeautifulSoup4 + lxml | Lightweight, battle-tested, easy to strip noise tags | | Local LLM | Ollama | Zero API cost, offline, privacy-safe, model-agnostic | | Agent Framework | CrewAI | Clean task/agent abstraction, sequential pipeline support | | LLM Adapter | LangChain-Ollama | Standard interface, easy model swapping | | DOM Fingerprinting | Custom JS injection | Works on any site regardless of framework | | Caching | SQLite + JSON | Crash-safe, fast lookup, human-readable | | Output | Gherkin .feature | Industry-standard BDD format (Cucumber/Behave compatible) |

---

📜 License

MIT License — free to use, modify, and distribute.

---

🤝 References

• Cucumber Gherkin Reference
• Playwright Python Docs
• CrewAI Documentation
• Ollama Model Library
• BeautifulSoup4 Docs