Skip to content

Commit f98b058

Browse files
author
Fernando López
committed
Adding Refactoring Plan for the QA Analysis
1 parent 2c6560c commit f98b058

1 file changed

Lines changed: 157 additions & 0 deletions

File tree

‎doc/Refactoring.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# Refactoring Plan
2+
3+
## Overview
4+
5+
This refactoring plan aims to improve modularity, maintainability, test clarity, and automation of the `qa-fiware-tutorials` repository. The repository implements behavior-driven tests (BDD) for various FIWARE tutorials, with support for both NGSI-v2 and NGSI-LD APIs.
6+
7+
---
8+
9+
## 🔍 1. Project Analysis & Baseline
10+
11+
**Goal:** Understand current structure, execution flow, and test coverage.
12+
13+
- [ ] Run tests locally using `behave` and Docker Compose.
14+
- Evaluate:
15+
- [ ] Test coverage & stability
16+
- [ ] Code duplication
17+
- [ ] Docker reliability
18+
- [ ] BDD feature file readability
19+
20+
---
21+
22+
## 📦 2. Modularize & Clarify Structure
23+
24+
**Goal:** Streamline code and separate concerns for clarity and reuse.
25+
26+
- [ ] Split `commons/`:
27+
- `docker_utils.py`, `http_utils.py`, `json_utils.py`, etc.
28+
- Refactor `config/`:
29+
- [ ] NGSI-v2 and NGSI-LD split
30+
- [ ] Rename `config.json` → `ngsi_v2.json`, `ngsi_ld.json`
31+
- [ ] Group `.feature` files:
32+
features/
33+
├── ngsi_v2/
34+
└── ngsi_ld/
35+
- [ ] Unify or reuse shared step definitions.
36+
37+
---
38+
39+
## 🔧 3. Clean & Simplify Shell Scripts
40+
41+
**Goal:** Improve automation, clarity, and reusability.
42+
43+
- [ ] Audit and clean: `ngsiv2.sh`, `ngsild.sh`, `generate_allure_documents.sh`
44+
- [ ] Extract reusable logic (e.g., for cURL validation).
45+
- Improve script UX:
46+
- [ ] Add CLI flags and help
47+
- [ ] Add error checking: `set -euo pipefail`
48+
- [ ] Add `bootstrap.sh` or `init.sh` for local test setup.
49+
50+
---
51+
52+
## ⚙️ 4. Improve Configuration Management
53+
54+
**Goal:** Support flexible environments and secure sensitive data.
55+
56+
- Add `.env` support for:
57+
- [ ] `OPENWEATHER_API_KEY`
58+
- [ ] FIWARE service URLs
59+
- [ ] Use sample config templates `config.sample.json`
60+
- [ ] Centralize configuration parsing in Python.
61+
62+
---
63+
64+
## 🧪 5. Enhance BDD Tests & Data Management
65+
66+
**Goal:** Make feature files more reusable, modular, and clear.
67+
68+
- [ ] Refactor repetitive steps into `Scenario Outline`.
69+
- [ ] Add reusable data fixtures:
70+
- [ ] Move JSON payloads to `features/data/`
71+
- [ ] Improve step reuse with shared libraries
72+
- [ ] Add tags: `@ngsi_v2`, `@ngsi_ld`, `@weather`, etc.
73+
- [ ] Add retry logic or health checks for dependent services.
74+
75+
---
76+
77+
## 🤖 6. GenAI-Assisted Feature File Generation
78+
79+
**Goal:** Automatically generate `.feature` files from HTML documentation using GenAI.
80+
81+
- **Use case:** HTML docs with `curl` examples (requests + responses).
82+
- **Tooling:**
83+
- Use ChatGPT API or local LLM to:
84+
1. [ ] Parse HTML documentation.
85+
2. [ ] Extract `curl` requests + responses.
86+
3. [ ] Generate `.feature` files in Gherkin syntax (with `Given`, `When`, `Then` steps).
87+
- **Workflow:**
88+
- [ ] Create `tools/genai_from_html.py`
89+
- [ ] Input: URL or HTML file.
90+
- [ ] Output: Suggested `.feature` files saved under `features/generated/`
91+
- **Review process:**
92+
- [ ] Generated scenarios reviewed by dev or QA before merge.
93+
- **Benefits:**
94+
- Fast onboarding for new tutorials.
95+
- Coverage parity with updated FIWARE docs.
96+
97+
---
98+
99+
## 🧹 7. Code Cleanup & Linting
100+
101+
**Goal:** Enforce code style and readability.
102+
103+
- [ ] Use `black`, `flake8` (Python), and `shellcheck` (bash).
104+
- [ ] Clean unused code, outdated data files.
105+
- [ ] Add `.gitignore` to exclude:
106+
- [ ] `.venv/`, `__pycache__/`, `.allure-results/`, Docker logs
107+
108+
---
109+
110+
## 🚀 8. CI/CD Enhancement
111+
112+
**Goal:** Ensure automated testing and build hygiene.
113+
114+
- Use GitHub Actions to:
115+
- [ ] Run `behave` tests for NGSI-v2 and NGSI-LD
116+
- [ ] Lint shell and Python code
117+
- [ ] Generate and upload Allure reports
118+
- [ ] Add badges to `README.md`:
119+
- [ ] Build status, code quality, Python version
120+
121+
---
122+
123+
## 📚 9. Documentation Improvements
124+
125+
**Goal:** Improve developer onboarding and usage clarity.
126+
127+
- Rewrite `README.md`:
128+
- [ ] Overview
129+
- [ ] Quickstart
130+
- [ ] Environment setup
131+
- [ ] Running tests
132+
- [ ] Add `CONTRIBUTING.md`
133+
- [ ] Document GenAI-assisted test generation
134+
- [ ] Optional: Generate Sphinx or MkDocs documentation
135+
136+
---
137+
138+
## 📦 10. Package & Distribute (Optional)
139+
140+
**Goal:** Allow reuse of helper modules via pip package.
141+
142+
- Add `setup.py` or `pyproject.toml`
143+
- Versioning for releases
144+
- Publish on PyPI (optional)
145+
146+
---
147+
148+
## 🧩 11. Final Review & Maintenance
149+
150+
**Goal:** Wrap up and ensure long-term quality.
151+
152+
- Peer review of refactored code
153+
- Merge changes incrementally
154+
- Document maintenance cycles and long-term goals
155+
156+
---
157+

0 commit comments

Comments
 (0)