PSO Weekly Testing Reports

System Architecture

Understanding how the PSO reporting system works:

Show Architecture Diagram

Accessing Reports

• Click on any report card from the dashboard to open that specific report
• All reports are available as standalone HTML files that can be viewed in any modern browser
• Reports are automatically updated through the GitLab CI/CD pipeline

Keyboard Shortcuts

• Ctrl+Click - Select text and add comment (hold Ctrl while selecting text)
• Ctrl+A - Open Admin Modal (requires password, available in reports)
• Ctrl+D - Mark all comments as resolved (requires password, available in reports)
• Esc - Close modals and dialogs

Automated Data Collection

Reports are automatically generated through the following process:

• JIRA Data: Python scripts fetch test execution data, bug counts, and metrics from JIRA using REST API
• GitLab Data: Test results, pipeline status, and code changes are collected from GitLab
• SonarQube Data: Code quality metrics, security vulnerabilities, and technical debt from SonarQube API
• JSON Storage: All collected data is stored in JSON files located in reports/json_collector/

Update Frequency

• Reports are generated weekly through scheduled GitLab pipelines
• Manual updates can be triggered through the Admin Modal (see Pipeline Runner section)
• Data reflects the current week's testing activities

Adding New Comments

Text Selection with Ctrl+Click

• Hold Ctrl and select any text in the report with your mouse
• A comment modal will automatically open
• The selected text will be highlighted in yellow
• Type your comment in the text area
• Click "Save Comment" to save it
• The text remains highlighted with a visual marker () showing the comment
• Click on any highlighted text to view or reply to the comment

Viewing Comments

• Highlighted Text: Text with comments appears highlighted in yellow with a visual marker ()
• Click to View: Click on any highlighted text to open and view the associated comment
• Review History: Click the "📋 Review History" button in the bottom-right corner to see all comments in a sidebar
• Filter by Status: Comments can be Active or Resolved - use the filter in Review History to see specific types

Editing Comments

• Click on any highlighted text to open the comment
• Click the Edit button (pencil icon) in the comment modal
• Modify the comment text
• Click "Save Comment" to update it

Replying to Comments

• Click on any highlighted text to open the comment
• Click "Reply" button at the bottom of the comment modal
• Type your reply in the text area
• Click "Save Reply" to add it
• Replies appear threaded under the original comment

Deleting Comments

• Individual Delete: Open the comment and click the Delete button (trash icon) to remove it permanently
• Resolve Comment: Click the "Resolve" button (✓) to mark a comment as resolved without deleting it
• Mark All as Resolved: Press Ctrl+D to mark all comments as resolved (requires password)
• Bulk Delete: Use Admin Modal → Remove All Comments option to permanently delete all comments (requires password)

Saving Comments to GitLab

• All comment actions (add, edit, delete, resolve) are automatically saved to GitLab
• Comments are stored in JSON files in reports/comments/ directory
• Changes are committed automatically to the GitLab repository
• All users viewing the reports will see the updated comments after GitLab sync
• No "Save" or "Publish" button needed - everything is automatic!

Accessing Admin Modal

• Press Ctrl+A from any report page
• Enter the admin password when prompted
• The Admin Modal will open with 5 main options

Option 1: Sections Visibility Control

Show or hide entire sections of the report:

• Toggle checkboxes to show/hide main sections and sub-sections
• Changes are saved locally and persist across sessions
• Click "Save Changes" to apply visibility settings
• Use "Reload" to reset to saved settings

Option 2: JIRA Queries Editor

View and customize JIRA queries used for data collection:

• View Queries: Displays all JIRA queries organized by report sections
• Current Query: Shows the active JQL (JIRA Query Language) query for each section
• Custom Query: Enter a custom JQL query in the textarea to override the default
• Test in JIRA: Click "🔗 Open JIRA" to test the query directly in JIRA (opens in new tab)
• Revert Changes: Click "🔄 Revert" to restore the original query
• Save Changes: Click "💾 Save Queries" to commit changes to GitLab
• Automatic Validation: System validates JQL syntax and auto-corrects common errors
• Note: Changes take effect in the next pipeline run - you must run the pipeline to see updated data

Option 3: Remove All Comments

Permanently delete all comments from the current report:

• Enter admin password to confirm
• Click "Delete All Comments"
• Confirm the action in the popup dialog
• ⚠️ Warning: This action cannot be undone and permanently removes ALL comments!
• Note: This is different from Ctrl+D which only marks comments as resolved

Option 4: Run Pipeline

Manually trigger a new report generation:

• Click "🚀 Start Pipeline" to trigger GitLab CI/CD pipeline
• Monitor progress in real-time through the console output
• Pipeline generates ALL reports (Automation, Manual, Security, etc.)
• Click "⏹️ Stop Pipeline" to cancel the running pipeline
• Use this when you need fresh data outside the scheduled weekly run

Option 5: Restore Deleted Fields

Recover previously deleted editable fields:

• View list of all deleted fields with deletion timestamps
• Click "Restore" next to any field to recover it
• Restored fields appear back in their original sections

Understanding Comment States

Comments can have two states:

• Active: Comment is visible and requires attention
• Resolved: Comment has been addressed but not deleted (archived)

Method 1: Individual Comment Actions

Who can use: Any user viewing the report

• Delete: Click the Delete button on any comment to permanently remove it
• Resolve: Click the Resolve button (✓) to mark comment as resolved without deleting
• Resolved comments can be viewed in the Review History sidebar
• Scope: Affects only the selected comment
• Permissions: No password required

Method 2: Mark All as Resolved (Ctrl+D)

Who can use: Users with admin password

• Press Ctrl+D from any report page
• Enter admin password (pso_admin) to confirm
• Scope: Marks ALL unresolved comments in the current report as resolved
• Effect: Comments are archived but not permanently deleted
• Visibility: Resolved comments can still be viewed in Review History sidebar
• Use case: When comments are addressed and should be archived for future reference

Method 3: Bulk Comment Deletion (Admin Only)

Who can use: Users with admin password

• Press Ctrl+A to open Admin Modal
• Select Option 3: Remove All Comments
• Enter admin password to confirm
• Scope: Permanently deletes ALL comments from the current report
• Use case: When you need to completely clean up and start fresh

Text Highlighting System

When you add a comment using Ctrl+Click, the selected text is automatically highlighted:

• Yellow Highlight: Text with comments appears with a yellow background
• Visual Marker: A small comment icon () appears next to highlighted text
• Persistent Highlighting: Highlights remain visible across page refreshes
• Click to View: Click on any highlighted text to open the associated comment

Review History Sidebar

Access all comments in one place:

• Click the "📋 Review History" button in the bottom-right corner
• Sidebar opens showing all comments with timestamps and authors
• Filter by Status: Toggle between Active and Resolved comments
• Quick Navigation: Click on any comment to jump to its location in the report
• Highlighted Excerpt: Each comment shows the highlighted text for context

Finding Comments

• Visual Markers: Look for yellow highlights throughout the report
• Comment Icons: Small icons indicate commented text
• Review History: Use the sidebar to see all comments chronologically
• Hover Effect: Hover over highlighted text to see a subtle animation

What are Editable Fields?

Some reports contain editable fields that allow you to manually enter or update specific values:

• Automation Report: "Enter Release" field and "Test Cases Updated" field
• Manual Report: Various test execution metrics
• These fields appear as inline text that can be clicked to edit

How to Edit a Field

1. Locate the editable field in the report (usually appears as regular text)
2. Double-click on the field - it will transform into an input box
3. Type the new value in the input box
4. Press Enter or click outside the field
5. The value is saved locally in the report but not yet in GitLab

How to Publish Changes

Important: Local vs GitLab Save

• Local Save: When you press Enter/blur, the value is saved only in the current browser session
• GitLab Save: To persist changes permanently, you need to publish them
• Manual Script Execution: Currently, edited values are saved to GitLab when the next pipeline runs
• Alternatively, an administrator can manually run the Python save scripts:
  • python scripts/data_collectors/save_release_number.py
  • python scripts/data_collectors/save_test_cases_updated.py

Persistence Flow

How edited values are persisted:

1. User Edit: User double-clicks field and enters new value
2. Local Save: Value is updated in the current HTML/browser session
3. Pipeline Run: Administrator runs the report generation pipeline
4. Python Script: During pipeline, Python scripts read the current values and save them to JSON files
5. Git Commit: JSON files are committed to GitLab repository
6. Next Generation: When the report is regenerated, the saved values are injected from JSON

Important Notes

• Double-Click to Edit: Most editable fields require double-click to activate editing mode
• Local Changes Only: Initial save is local - you must run the pipeline to persist
• No Automatic Publish: There is no automatic GitLab commit for edited fields
• Validation: Some fields may have input validation (e.g., numbers only, minimum values)
• Visual Feedback: Input styling matches surrounding text for seamless appearance
• Override Protection: Once saved to GitLab, manual values are not overwritten by automated data collection

Scheduled Automatic Runs

Pipelines run automatically in these scenarios:

• Weekly Schedule: Every Monday at 6:00 AM (configurable)
• After Code Changes: When test results or metrics are updated

When to Manually Run Pipeline

Trigger a manual pipeline run when:

• Modified JIRA Queries: After changing queries in Admin Modal → JIRA Queries Editor
• Need Fresh Data: When you need updated metrics outside the weekly schedule
• After Major Changes: Following significant test execution or code updates
• Verification: To verify that query changes produce expected results
• Emergency Updates: When stakeholders need immediate report updates

How to Run Pipeline Manually

1. Open Admin Modal (⚙️ icon → enter password)
2. Select "Option 4: Run Pipeline"
3. Click "🚀 Start Pipeline" button
4. Monitor progress in the console (shows each stage)
5. Wait for completion (typically 5-10 minutes)
6. New reports are automatically deployed to GitLab Pages

Overview

The Review History system ensures that weekly reports are only published after internal team review. This guarantees data quality and accuracy before reports are shared with external stakeholders.

Two-Stage Review Process

Complete Flow Diagram

How to Open Review History

1. Click the Review History button (bottom-right corner, purple icon)
2. The modal opens with two tabs: Internal Review and User Acceptance Review

Internal Review Process

Each internal reviewer must verify the reports and mark their review status:

1. Open Review History - Click the clipboard icon
2. Find Your Name - Locate yourself in the Internal Review table
3. Review All Reports - Check each report for accuracy (Automation, Manual, Security, etc.)
4. Mark Status - Click on your row to toggle between:
   • ⏳ Pending - Not yet reviewed
   • ✅ Reviewed - Approved without issues
   • 💬 Reviewed with Comments - Has issues/feedback that must be resolved before final approval
5. Changes Auto-Save - Your status is automatically committed to GitLab

Automatic Weekly Report Generation

When ALL internal reviewers have marked their status as "Reviewed" or "Reviewed with Comments":

1. The system automatically detects all reviews are complete
2. A special pipeline stage is triggered: weekly-report
3. A new folder is created: weekly_reports/W##/ (e.g., W48)
4. This folder contains a permanent snapshot of the reviewed reports
5. The folder is committed to GitLab for historical tracking

Re-generate Weekly Report (Manual)

If you need to regenerate the weekly report folder after all reviews are complete:

1. Click the Re-generate Weekly Report button (bottom-right, blue icon)
2. Enter the admin password: pso_admin
3. The pipeline will run and create/update the weekly folder

User Acceptance Review

After internal review is complete, external stakeholders (clients) can review in the second tab:

• Client reviewers are listed in the "User Acceptance Review" tab
• They can mark reports as reviewed using the same process
• This provides an audit trail of client approvals

Weekly Cycle

Viewing Past Weeks

Historical weekly reports are stored in: weekly_reports/W##/

Each folder contains the exact state of reports at the time of internal review approval.

Common Issues

Q: My comments disappeared after refreshing the page

A: This shouldn't happen as comments are automatically saved to GitLab. Check your network connection and ensure GitLab API is accessible. You can also check the browser console for any error messages.

Q: Text highlighting is not working with Ctrl+Click

A: Make sure you're holding Ctrl while selecting text. Also, avoid selecting text on buttons, links, or input fields. Only regular text content can be highlighted.

Q: Modified JIRA queries don't show new data

A: You need to run a new pipeline after modifying queries. Go to Admin Modal → Run Pipeline.

Q: Can't access Admin Modal

A: Press Ctrl+A and enter the correct admin password (pso_admin).

Q: Pipeline fails to start

A: Check your network connection and ensure you have proper GitLab access permissions. The fallback simulation will run if GitLab API is unavailable.

Q: Charts or data not displaying

A: Try refreshing the page. If the issue persists, check browser console for errors or run a new pipeline to regenerate data.

Q: Highlighted text appears in wrong location

A: If the report structure was significantly modified, XPath references might be outdated. Delete the old comment and add a new one with updated highlighting.