Reklamator/specs/003-render-ai-analyis/MANUAL_TESTING_GUIDE.md

# Manual Testing Guide: Markdown Rendering Feature

**Feature**: 003-render-ai-analyis - Render AI Analysis as Formatted HTML
**Tasks**: T020 (Security Verification) and T021 (Performance Validation)

---

## Prerequisites

Before you begin, ensure:
- ✅ Virtual environment is activated
- ✅ Dependencies are installed (`pip install -r requirements.txt`)
- ✅ You have the test data generator script: `prepare_markdown_manually.py`

---

## Step 1: Create Test Data

Run the test data generator to create 4 different feedback samples:

```bash
python prepare_markdown_manually.py
```

This creates:
1. **Rich Formatting Test** - Headings, lists, tables, code blocks, links
2. **XSS Security Test** - Script tags, iframes, javascript: protocol
3. **Complex Tables Test** - Nested lists, multiple tables, code samples
4. **Performance Test** - 30 sections with tables, lists, and code

The script will output the feedback IDs created.

---

## Step 2: Start the Flask Application

### Option A: Using run.py (Recommended)

```bash
python run.py
```

### Option B: Using Flask CLI

```bash
export FLASK_APP=app
export FLASK_ENV=development
flask run
```

The application will start on **http://localhost:5000**

---

## Step 3: Login to Dashboard

1. Open your browser and navigate to: **http://localhost:5000/login**

2. Login with default credentials:
   - **Username**: `admin`
   - **Password**: `admin123`

3. You should be redirected to: **http://localhost:5000/dashboard**

---

## Step 4: Verify Markdown Rendering (T020 & T021)

### Test 1: Rich Formatting ✅

**Feedback**: Click on the first test feedback (Rich Markdown Formatting)

**What to verify:**

1. **Headings**
   - [ ] `## Summary` appears as styled `<h2>` heading (not raw markdown)
   - [ ] `### Key Points` appears as styled `<h3>` heading

2. **Text Formatting**
   - [ ] `**highly positive**` appears as **bold** text
   - [ ] `*minor concerns*` appears as *italic* text

3. **Lists**
   - [ ] Bullet points render with actual bullets (•)
   - [ ] Numbered lists show as 1, 2, 3 (not markdown "1.")

4. **Code**
   - [ ] Inline code `Flask` has monospace font and background
   - [ ] Code block shows Python syntax in preformatted block
   - [ ] Code block has distinct background/border

5. **Tables**
   - [ ] Table renders with borders and proper structure
   - [ ] Headers are distinct from data rows
   - [ ] All 4 rows (Score, Sentiment, Response Time, Priority) visible

6. **Links** (SECURITY - T020)
   - [ ] "Flask Documentation" link is clickable
   - [ ] Right-click → Inspect on the link
   - [ ] Verify `target="_blank"` attribute exists
   - [ ] Verify `rel="noopener noreferrer nofollow"` attribute exists
   - [ ] Click link - should open in NEW TAB

**Browser DevTools Check**:
```
Right-click on link → Inspect → Should see:
<a href="https://flask.palletsprojects.com/"
   target="_blank"
   rel="noopener noreferrer nofollow">Flask Documentation</a>
```

---

### Test 2: XSS Security Testing ✅ (T020 - CRITICAL)

**Feedback**: Click on the second test feedback (XSS Security Testing)

**What to verify** (All should be REMOVED):

1. **Script Tags**
   - [ ] NO `<script>` tags visible in rendered HTML
   - [ ] NO "XSS attempt 1" text visible
   - [ ] NO JavaScript code visible

2. **Iframes**
   - [ ] NO `<iframe>` tags visible
   - [ ] NO "evil.com" visible anywhere

3. **JavaScript Protocol**
   - [ ] "dangerous link" text may be visible BUT
   - [ ] Link should NOT have `javascript:` in href
   - [ ] Right-click → Inspect the link
   - [ ] Verify href is sanitized or link is removed

4. **Images**
   - [ ] NO `<img>` tags visible
   - [ ] NO images loaded from external sources

5. **Safe Content Still Works**
   - [ ] Bold/italic text AFTER dangerous content still renders
   - [ ] Lists still render properly
   - [ ] Heading "Security Analysis" appears as `<h2>`

**Browser DevTools Check**:
```
Press F12 → Elements tab → Search for:
- "script" → Should find NO <script> tags
- "iframe" → Should find NO <iframe> tags
- "javascript:" → Should find NONE in href attributes
```

**Console Check**:
```
Press F12 → Console tab → Should be NO JavaScript errors
```

---

### Test 3: Complex Tables and Lists ✅

**Feedback**: Click on the third test feedback (Complex Tables)

**What to verify:**

1. **Table Rendering**
   - [ ] Pricing table renders with 4 columns
   - [ ] Table has borders/styling
   - [ ] Header row (Free, Pro, Enterprise) is distinct

2. **Nested Lists**
   - [ ] "Primary Features" shows as numbered list
   - [ ] Sub-items indented properly
   - [ ] Mixed list types render correctly

3. **Code Blocks**
   - [ ] Python code block shows with syntax
   - [ ] JavaScript code block shows with syntax
   - [ ] Both blocks have distinct background

---

### Test 4: Performance Testing ✅ (T021)

**Feedback**: Click on the fourth test feedback (Performance Test)

**What to verify:**

1. **Page Load Time** (CRITICAL)
   - [ ] Open Browser DevTools (F12)
   - [ ] Go to Network tab
   - [ ] Click on the feedback
   - [ ] Check "DOMContentLoaded" time in Network tab
   - [ ] **MUST BE < 2 seconds** (per requirement SC-005)

2. **Content Rendering**
   - [ ] Page doesn't freeze or lag
   - [ ] All 30 sections render properly
   - [ ] Can scroll smoothly through content
   - [ ] No "loading" or blank areas

3. **Browser Performance**
   - [ ] No browser warnings
   - [ ] No excessive memory usage
   - [ ] Page remains responsive

**Performance Measurement**:
```
F12 → Network tab → Reload page → Check:
- Load time: _______ ms (should be < 2000ms)
- DOMContentLoaded: _______ ms
- Finish: _______ ms
```

---

## Step 5: Advanced Security Verification (T020)

### Test with Browser Developer Tools

1. **Inspect Rendered HTML**:
   ```
   F12 → Elements tab → Search in page source:
   ```

   **Should NOT find:**
   - `<script>` tags (except legitimate page scripts)
   - `<iframe>` tags (in the analysis section)
   - `javascript:` protocol in any links
   - `<img>` tags in analysis section
   - Any content from "evil.com"

2. **Check Link Security**:
   ```
   F12 → Elements → Find any <a> tag in analysis section
   ```

   **Every link should have:**
   - `target="_blank"`
   - `rel="noopener noreferrer nofollow"`

3. **Test XSS Protection**:
   - View page source (Ctrl+U)
   - Search for "alert("
   - **Should find**: 0 results in analysis section

---

## Step 6: Browser Compatibility (Optional)

Test in multiple browsers:
- [ ] Chrome/Chromium
- [ ] Firefox
- [ ] Safari (if available)
- [ ] Edge

All should render markdown consistently.

---

## Expected Results Summary

### ✅ Markdown Rendering (T020)
- Headings render as `<h2>`, `<h3>` with styling
- Lists render with bullets/numbers
- Tables have borders and proper structure
- Code blocks have monospace font and background
- Links are clickable and styled
- Bold/italic text formatted correctly

### ✅ Security (T020 - CRITICAL)
- Script tags completely removed (tag + content)
- Iframe tags completely removed
- JavaScript protocol sanitized from links
- Images removed from analysis
- All links have `target="_blank"`
- All links have `rel="noopener noreferrer nofollow"`
- No XSS vulnerabilities

### ✅ Performance (T021)
- Page load time < 2 seconds
- Long content (30+ sections) renders smoothly
- No browser lag or freezing
- Responsive scrolling

---

## Troubleshooting

### Issue: Markdown not rendering (shows raw markdown)

**Check**:
1. Filter is registered in `app/__init__.py` line 186
2. Template uses `{{ feedback.analysis|markdown(feedback.feedback_id) }}`
3. No Python errors in console

### Issue: Page returns 404

**Check**:
1. Feedback ID is correct
2. Product is "test-product"
3. You're logged in as admin user

### Issue: Performance test fails

**Possible causes**:
1. Running in debug mode (adds overhead)
2. Browser extensions slowing down page
3. System under heavy load

**Solution**: Run in production mode or disable extensions

---

## Completion Checklist

After completing all tests, mark these as complete:

- [ ] Test 1: Rich Formatting - All markdown elements render correctly
- [ ] Test 2: XSS Security - All dangerous elements removed
- [ ] Test 3: Complex Tables - Tables and lists render properly
- [ ] Test 4: Performance - Page loads in < 2 seconds
- [ ] Links have security attributes (target, rel)
- [ ] No XSS vulnerabilities found
- [ ] Tested in at least 2 browsers

---

## Reporting Results

If you find any issues, document:

1. **What you tested**: (e.g., "XSS protection with script tags")
2. **Expected result**: (e.g., "Script tags should be removed")
3. **Actual result**: (e.g., "Script tag visible in HTML")
4. **Feedback ID**: (e.g., "abc-123-def-456")
5. **Browser**: (e.g., "Chrome 120")
6. **Screenshot**: (if applicable)

---

## Next Steps After Testing

Once all tests pass:

1. Update `tasks.md`:
   - Mark T020 as `[X]` with completion note
   - Mark T021 as `[X]` with performance metrics

2. Consider this feature **COMPLETE** and ready for:
   - Code review
   - Pull request
   - Deployment to staging

---

## Quick Reference

**Start App**: `python run.py`
**Login URL**: http://localhost:5000/login
**Dashboard URL**: http://localhost:5000/dashboard
**Credentials**: admin / admin123

**Test Data Script**: `python prepare_markdown_manually.py`F

**Key Files**:
- Markdown utils: `app/utils/markdown_utils.py`
- Template filter: `app/__init__.py` line 185-186
- Detail template: `app/templates/dashboard/detail.html` line 105

---

**Last Updated**: 2025-10-18
**Feature**: 003-render-ai-analyis
**Status**: Ready for manual testing