From cbff2ffafeb39f1d8815347c0285e190d3eac543 Mon Sep 17 00:00:00 2001 From: Maciej Pienczyn Date: Sat, 10 Jan 2026 09:46:11 +0100 Subject: [PATCH] auto-claude: subtask-3-8 - Document development and testing --- README.md | 274 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 274 insertions(+) diff --git a/README.md b/README.md index fb63ffd..6cd23ff 100644 --- a/README.md +++ b/README.md @@ -455,6 +455,280 @@ docker exec -i nordabiz-postgres psql -U nordabiz_app -d nordabiz < database/sch For more detailed database setup and management, see `database/README.md`. +## Testing & Quality Assurance + +The Norda Biznes Hub includes a comprehensive testing framework to ensure code quality, AI accuracy, and feature reliability. The test suite covers unit tests for individual components and specialized AI quality evaluation. + +### Test Suite Overview + +The `tests/` directory contains the following test modules: + +``` +tests/ +├── ai_quality_evaluator.py # AI testing framework +├── ai_quality_test_cases.json # 15 test cases in 8 categories +├── test_admin_seo_dashboard.py # SEO dashboard functionality tests +├── test_gbp_audit_field_checks.py # Google Business Profile audit tests +├── test_it_audit_collaboration.py # IT infrastructure audit tests +├── test_seo_audit.py # SEO audit service tests +├── test_social_media_audit.py # Social media audit tests +└── results/ # Test results and reports (generated) +``` + +### Running Tests + +#### AI Quality Tests + +The AI Quality Testing Framework evaluates the accuracy and relevance of AI chat responses using predefined test cases. + +**Basic Usage:** + +```bash +# Run all AI quality tests (standard output) +python run_ai_quality_tests.py + +# Run with verbose output showing details for each test +python run_ai_quality_tests.py --verbose +# or +python run_ai_quality_tests.py -v + +# Run with verbose output AND save results to JSON file +python run_ai_quality_tests.py -v -s + +# Run only high-priority test cases (quick validation) +python run_ai_quality_tests.py -q +``` + +**Test Results:** + +Test results are displayed in the console and optionally saved to `tests/results/` directory with timestamps: +- `ai_quality_report_20260110_143000.json` - Detailed test results with scores and metrics + +**AI Test Categories:** + +The AI quality tests cover 8 business categories with 15 test cases: +1. **IT/Web Development** - Testing recommendations for IT services, web development +2. **Services/Legal** - Legal services, law firms +3. **Services/Accounting** - Accounting, bookkeeping services +4. **Production/Metal** - Metal production, manufacturing +5. **Construction** - Construction companies, contractors +6. **HVAC** - Heating, ventilation, air conditioning +7. **Energy/Renewable** - Renewable energy, solar panels +8. **IT/Security** - IT security, cybersecurity services + +**Quality Thresholds:** +- **Pass Threshold:** 70% - Tests must achieve at least 70% accuracy to pass +- **Scoring:** Each test case is scored 0.0-1.0 based on: + - Company relevance (did it find the right companies?) + - Response accuracy (is the information correct?) + - Context understanding (did it understand the query intent?) + +#### Unit Tests + +Run unit tests for specific components using pytest: + +```bash +# Run all unit tests +python -m pytest tests/ + +# Run specific test file +python -m pytest tests/test_admin_seo_dashboard.py + +# Run with verbose output +python -m pytest tests/ -v + +# Run with coverage report +python -m pytest tests/ --cov=. +``` + +#### Manual Testing in Production + +**⚠️ IMPORTANT:** Always use test accounts for production verification. + +**Test Accounts:** + +| Account | Email | Purpose | +|---------|-------|---------| +| Test User | `test@nordabiznes.pl` | Test user-facing features (directory, search, chat) | +| Test Admin | `testadmin@nordabiznes.pl` | Test admin features (moderation, audits, management) | + +**Testing Workflow:** + +1. **User Features:** + - Company directory browsing + - Search functionality + - AI chat conversations + - User registration and authentication + - Notifications + +2. **Admin Features:** + - News moderation (`/admin/news`) + - SEO dashboard (`/admin/seo`) + - Social media audit (`/admin/social-media`) + - GBP audit (`/admin/gbp-audit`) + - IT audit (`/admin/it-audit`) + - User management (`/admin/users`) + +### Quality Assurance Process + +#### Pre-Deployment QA Checklist + +Before deploying to production, ensure all quality checks pass: + +1. **Code Quality:** + ```bash + # Check Python syntax + python -m py_compile app.py + + # Check all Python files + find . -name "*.py" -exec python -m py_compile {} \; + ``` + +2. **AI Quality:** + ```bash + # Run AI quality tests with 70% pass threshold + python run_ai_quality_tests.py -v + # Expected: Pass rate ≥ 70% + ``` + +3. **Unit Tests:** + ```bash + # Run all unit tests + python -m pytest tests/ -v + # Expected: All tests pass + ``` + +4. **Database Integrity:** + ```bash + # Verify database schema (development) + psql -U nordabiz_app -d nordabiz -h localhost -p 5433 -c "\dt" + + # Check for data quality issues + python verify_all_companies_data.py + ``` + +5. **API Endpoints:** + ```bash + # Test health endpoint + curl http://localhost:5000/health + # Expected: {"status": "healthy"} + + # Test companies API + curl http://localhost:5000/api/companies | jq '.total' + # Expected: 80 + ``` + +#### Continuous Quality Monitoring + +**Development:** +- Run AI quality tests after chat engine modifications +- Run unit tests after feature changes +- Verify test account functionality weekly + +**Production:** +- Monitor health endpoint: `https://nordabiznes.pl/health` +- Review application logs: `sudo journalctl -u nordabiznes -f` +- Track AI chat analytics: `/admin/chat-analytics` +- Monitor rate limits and API usage + +### Test Coverage + +Current test coverage by feature area: + +| Feature Area | Test Coverage | Test Files | +|--------------|---------------|------------| +| **AI Chat Engine** | ✅ Comprehensive | `ai_quality_evaluator.py`, `ai_quality_test_cases.json` | +| **SEO Audit** | ✅ Comprehensive | `test_admin_seo_dashboard.py`, `test_seo_audit.py` | +| **GBP Audit** | ✅ Comprehensive | `test_gbp_audit_field_checks.py` | +| **IT Audit** | ✅ Comprehensive | `test_it_audit_collaboration.py` | +| **Social Media Audit** | ✅ Comprehensive | `test_social_media_audit.py` | +| **Search Service** | ⚠️ Manual Testing | SearchService integration tests needed | +| **Authentication** | ⚠️ Manual Testing | User registration/login flow tests needed | +| **API Endpoints** | ⚠️ Manual Testing | API integration tests needed | + +### Adding New Tests + +#### AI Quality Test Cases + +To add a new AI quality test case, edit `tests/ai_quality_test_cases.json`: + +```json +{ + "test_id": "new_test_01", + "category": "Services/Consulting", + "priority": "high", + "query": "Szukam firmy doradczej w Wejherowie", + "expected_companies": [ + "Firma A", + "Firma B" + ], + "notes": "Testing consulting service recommendations" +} +``` + +#### Unit Tests + +Create a new test file in `tests/` following the pattern: + +```python +""" +Test module for [feature name] +""" +import pytest +from database import SessionLocal, init_db +# Import modules to test + +def test_feature_functionality(): + """Test basic feature functionality""" + # Arrange + db = SessionLocal() + + # Act + result = feature_function() + + # Assert + assert result is not None + assert result.status == "success" + + db.close() +``` + +### Troubleshooting Tests + +**AI Tests Failing:** + +```bash +# Check Gemini API key is configured +grep GOOGLE_GEMINI_API_KEY .env + +# Verify database has companies data +python -c "from database import SessionLocal, Company; db = SessionLocal(); print(db.query(Company).count())" +# Expected: 80 +``` + +**Database Connection Errors:** + +```bash +# Ensure PostgreSQL is running +docker ps | grep nordabiz-postgres + +# Test database connection +psql -U nordabiz_app -d nordabiz -h localhost -p 5433 -c "SELECT 1;" +``` + +**Import Errors:** + +```bash +# Ensure all dependencies are installed +pip install -r requirements.txt + +# Verify virtual environment is activated +which python +# Expected: /path/to/nordabiz/venv/bin/python +``` + +For detailed test implementation and examples, see the `tests/` directory and individual test modules. + ## Deployment & Production The application is live in production at **https://nordabiznes.pl** since November 23, 2025.