Bug Report Template - Scola LMS QA¶

Use this template for ALL test failures and production bugs.

Bug ID: [JIRA-####]¶

Title: [Concise, specific title - e.g., "Grade publish button disabled after timeout"]

1. Severity & Priority¶

Field	Value
Severity	`P0 - Blocker` / `P1 - Critical` / `P2 - Important` / `P3 - Minor`
Priority Gate	Local Dev / PR Gate / Nightly / Production
Impact	[e.g., "Blocks all grade publishing", "Affects 50% of teachers"]
Affected Users	Teacher / Student / Parent / Admin / All

Severity Guide: - P0 (Blocker): Breaks core functionality, security issue, data loss, system down - P1 (Critical): Major feature broken, workaround exists but painful - P2 (Important): Minor feature broken, cosmetic issue affecting UX - P3 (Minor): Edge case, low-impact cosmetic issue

2. Spec Reference (Traceability)¶

Source of Truth: [Link to spec clause, e.g., scola_lms_spec.md § 5.5]

Violated Requirement:

[Copy exact text from spec] Example: "Publish Grades button must remain enabled after successful publish and allow re-publish with idempotency safeguards."

Expected Behavior (per spec): - [Bullet point from spec]

Actual Behavior: - [What actually happened]

3. Reproduction Steps¶

Environment: - Database: scola_test / scola_staging / scola_production - Branch: develop / main / feature/xyz - Commit SHA: abc123def - Browser: Chrome 120 / Firefox 115 / Safari 17 - User Role: Teacher / Student / Parent / Admin

Prerequisites: 1. [ ] Database restored to baseline: make qa-reset 2. [ ] Seed data loaded: make qa-seed 3. [ ] Logged in as: [email protected] 4. [ ] Navigated to: /lms/gradebook/1

Steps to Reproduce: 1. Navigate to Gradebook for "Mathematics 101" 2. Click "Publish Grades" button for "Homework 1" 3. Wait for success toast to appear 4. Observe button state

Actual Result: - Button becomes disabled permanently - Console error: TypeError: Cannot read property 'published' of undefined

Expected Result: - Button remains enabled (or changes to "Published" state) - No console errors

4. Evidence¶

Screenshots: - [ ] Before state (attached: bug-001-before.png) - [ ] After state (attached: bug-001-after.png) - [ ] Error message (attached: bug-001-error.png)

Video/GIF: - [ ] Screen recording (attached: bug-001-recording.mp4)

Network Trace: - [ ] HAR file (attached: bug-001-network.har) - [ ] Failed request details:

URL: POST /api/lms/grades/publish
Status: 200 OK
Response: { "published_count": 3, "notification_sent": true }

Console Logs:

[Error] TypeError: Cannot read property 'published' of undefined
  at GradebookComponent.updateButtonState (gradebook.vue:145)
  at GradebookComponent.onPublishSuccess (gradebook.vue:120)

Playwright Trace: - [ ] Trace file (attached: trace.zip) - [ ] Run: npx playwright show-trace trace.zip

Database State:

-- Query to verify state
SELECT id, assignment_id, published_at, published_by 
FROM grade_publish_log 
WHERE assignment_id = 1;

-- Result: Shows publish event exists but UI state is wrong

5. Test Case Mapping¶

Failed Test: tests/e2e/critical/grade_publish_flow.spec.ts :: [CR-001]

Test ID: CR-001

Test Status: - [x] Test failed (blocking PR) - [ ] Test flaky (passed on retry) - [ ] Test skipped (known issue)

Reproducibility: - [x] 100% reproducible - [ ] Intermittent (70% failure rate) - [ ] Rare (<10% failure rate)

6. Root Cause Analysis (Post-Fix)¶

Root Cause: - [To be filled by developer after investigation] - Example: "Button state update logic assumed response.data.published exists, but API returns response.published"

Fix: - [Summary of fix] - Example: "Updated gradebook.vue:145 to check response.published instead of response.data.published"

Commit: def456abc - feat(gradebook): fix button state after publish

Files Changed: - src/views/Gradebook.vue - src/services/gradebook.service.js

7. Verification Steps (QA Sign-Off)¶

Verification Checklist: - [ ] Bug reproduced on original branch - [ ] Fix applied and tested locally - [ ] Automated test updated to catch regression - [ ] Manual exploratory testing passed - [ ] No new bugs introduced

Test Run After Fix:

npx playwright test tests/e2e/critical/grade_publish_flow.spec.ts
# Result: ✅ All tests passed (3/3)

Sign-Off: - Developer: @dev-name (Implemented fix) - QA: @qa-name (Verified fix) - Date: 2026-01-26

8. Regression Prevention¶

New Test Added: - [ ] Yes - tests/e2e/critical/grade_publish_button_state.spec.ts - [ ] No - Existing test coverage sufficient

Documentation Updated: - [ ] API docs updated - [ ] Spec updated (if requirements changed) - [ ] Troubleshooting guide updated

Related Bugs: - JIRA-100: "Publish button race condition" - JIRA-150: "Notification not sent after publish"

9. Labels & Tags¶

Jira Labels: - bug - p0-blocker / p1-critical / p2-important / p3-minor - lms - gradebook - grade-publish - frontend / backend / fullstack - security (if RBAC-related) - performance (if SLA violation) - flaky-test (if test instability)

GitHub Labels: - bug - priority: high - area: lms - needs-triage

10. Communication¶

Reported By: QA Engineer / Playwright CI / User Report

Assigned To: @developer-name

Stakeholders Notified: - [ ] Product Owner - [ ] QA Lead - [ ] Engineering Manager - [ ] Support Team (if production bug)

Slack Channel: #qa-alerts / #eng-bugs

Status Updates: - 2026-01-25 14:30: Bug reported, assigned to @dev-name - 2026-01-25 16:00: Root cause identified - 2026-01-25 18:00: Fix merged to develop - 2026-01-26 09:00: QA verified, closing ticket

Example: Filled Bug Report¶

Bug ID: JIRA-250¶

Title: Grade publish button becomes disabled after network timeout

1. Severity & Priority¶

Field	Value
Severity	P1 - Critical
Priority Gate	PR Gate
Impact	Teachers cannot re-publish grades if network is slow
Affected Users	Teachers (all schools)

2. Spec Reference¶

Source of Truth: scola_lms_spec.md § 5.5.3 - Idempotency

Violated Requirement:

"The publish grades button must support multiple clicks and remain functional even after a successful publish, with backend idempotency preventing duplicate actions."

Expected Behavior: - Button remains clickable after publish - Subsequent clicks trigger API call (backend returns 200 OK with "already published" message)

Actual Behavior: - Button becomes permanently disabled after timeout - No way to retry publish

3. Reproduction Steps¶

Environment: - Database: scola_test - Branch: develop (commit abc123) - Browser: Chrome 120 - User Role: Teacher

Prerequisites: 1. [x] make qa-reset 2. [x] make qa-seed 3. [x] Logged in as [email protected] 4. [x] Navigated to /lms/gradebook/1

Steps: 1. Throttle network to "Slow 3G" in DevTools 2. Click "Publish Grades" for "Homework 1" 3. Wait for request to timeout (30s) 4. Observe button state

Actual Result: - Button disabled, label shows "Publishing..." - Network request times out - Button never re-enables

Expected Result: - Button shows error state - Button becomes clickable again after timeout

4. Evidence¶

Screenshots: - ✅ bug-250-timeout.png - Button stuck in "Publishing..." state

Network Trace: - ✅ bug-250-network.har - Shows timeout after 30s

Console Logs:

[Error] Network timeout after 30000ms
  at fetch (/api/lms/grades/publish)

5. Test Case Mapping¶

Failed Test: tests/e2e/critical/grade_publish_flow.spec.ts :: [CR-001] Reproducibility: 100% reproducible with network throttling

6. Root Cause¶

Cause: Button state is set to disabled=true on request start, but never reset to false on timeout error.

Fix: Added .finally() block to re-enable button regardless of success/failure.

Commit: def456 - fix(gradebook): re-enable publish button on error

7. Verification¶

[x] Bug reproduced
[x] Fix verified locally
[x] Test updated to include timeout scenario
[x] Manual QA passed

QA Sign-Off: @qa-lead - 2026-01-26

8. Regression Prevention¶

[x] New test: tests/e2e/critical/grade_publish_timeout.spec.ts
[x] API docs updated with timeout handling

Status: ✅ RESOLVED (Merged to develop, deployed to staging)

Template Usage Instructions¶

Create Jira ticket using this template
Attach evidence (screenshots, HAR files, traces)
Link to failed Playwright test (if applicable)
Reference spec clause (always!)
Assign severity (P0 = blocker, P1 = critical, P2 = important, P3 = minor)
Tag appropriately (use labels for filtering)
Update status as bug moves through workflow

Jira Workflow: 1. Open → 2. In Progress → 3. In Review → 4. QA Verification → 5. Closed

Document Owner: QA Lead
Review Cycle: Quarterly
Last Updated: January 25, 2026