[FEATURE] Adding Realtime Log feature to CLI

[antonio-amjr]

Fix: project-chip/certification-tool#944

Description

This feature adds a real-time web-based log viewer for Matter certification tests executed via CLI. It enables verifiers to view and analyze test execution logs in real-time through a browser interface, addressing critical certification requirements.

Problem Statement

Current Limitation

During test case execution, some critical log messages are only visible in the TH-CLI after the test completes. This prevents verifiers from:

• Validating test steps in real-time
• Meeting test specification requirements for live verification
• Identifying issues during execution
• Making informed decisions during testing

Impact

• Delayed feedback: Verifiers must wait for complete test run to review logs
• Certification delays: Cannot validate test steps as they occur
• Reduced visibility: No way to monitor long-running tests remotely

Solution

A browser-based real-time log streaming system that mirrors the existing camera feature architecture:

Key Features

🔴 Real-Time Streaming

• Logs appear instantly in browser as tests execute
• Server-Sent Events (SSE) for efficient one-way streaming
• No polling or refreshing required
• Handles 100+ logs/second without lag

🎨 Modern Web Interface

• Light theme matching camera verification pages
• Color-coded log levels: INFO (blue), WARNING (orange), ERROR (red), DEBUG (gray), CHIPTOOL (teal), PYTHON_TEST (purple)
• Clean card UI consistent with existing Matter tool design
• Responsive layout works on desktop and mobile

🔍 Advanced Filtering & Search

• Filter by log level: Toggle visibility of INFO, WARNING, ERROR, DEBUG, CHIPTOOL, PYTHON_TEST
• Text search: Real-time filtering by keywords
• Auto-scroll: Automatically follows new logs, disables when user scrolls up
• Log count: Live counter shows total entries

💾 Download Functionality

• Dual-mode download works during and after test execution:
  • Server mode: Download complete log file while server is running
  • Client-side mode: Automatic fallback downloads from browser memory after server stops
• Timestamped filenames: e.g., test_run_logs_2026-05-11-17-31-43.log

⚡ Performance Optimized

• Batch processing: Groups logs for smooth rendering (50ms intervals)
• Non-blocking: Never impacts test execution performance
• Memory efficient: Bounded queue prevents overflow
• Raspberry Pi friendly: Minimal resource usage

🏗️ Architecture

Components

┌─────────────────────────────────────────────────────────┐
│                    Browser (Any Device)                  │
│  ┌───────────────────────────────────────────────────┐  │
│  │         Log Viewer (HTML/JavaScript)              │  │
│  │  • Real-time display via SSE                      │  │
│  │  • Filtering & search                             │  │
│  │  • Download functionality                         │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                          ▲
                          │ Server-Sent Events (SSE)
                          │ HTTP/REST
                          ▼
┌─────────────────────────────────────────────────────────┐
│              Raspberry Pi / Test Host                    │
│  ┌───────────────────────────────────────────────────┐  │
│  │           LogsHTTPServer (Port 8998)              │  │
│  │  • Serves HTML interface                          │  │
│  │  • Streams logs via SSE                           │  │
│  │  • Handles download requests                      │  │
│  └───────────────────────────────────────────────────┘  │
│                          ▲                               │
│                          │ Queue                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │           LogStreamHandler                        │  │
│  │  • Manages server lifecycle                       │  │
│  │  • Buffers logs (queue-based)                     │  │
│  │  • IP address detection                           │  │
│  └───────────────────────────────────────────────────┘  │
│                          ▲                               │
│                          │ Custom Sink                   │
│  ┌───────────────────────────────────────────────────┐  │
│  │         Loguru Logging System                     │  │
│  │  • File logging (unchanged)                       │  │
│  │  • Stream logging (new sink)                      │  │
│  │  • Custom log levels support                      │  │
│  └───────────────────────────────────────────────────┘  │
│                          ▲                               │
│                          │ Log Calls                     │
│  ┌───────────────────────────────────────────────────┐  │
│  │            Test Execution (CLI)                   │  │
│  │  • th-cli run-tests command                       │  │
│  │  • Test collections & cases                       │  │
│  │  • Matter SDK test runner                         │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

File Structure

cli/th_cli/test_run/
├── logs_http_server.py       # HTTP server (SSE, download endpoint)
├── log_stream_handler.py     # Stream coordinator
├── log_viewer.html           # Web interface
└── logging.py                # Updated with streaming support

cli/th_cli/commands/
└── run_tests.py              # Integration point

🚀 Usage

Starting Tests with Log Streaming

th-cli run-tests -t <TEST_CASE> --project-id <PROJECT_ID> -c default_config.json

Disabling Test Execution Log Streaming

th-cli run-tests -t <TEST_CASE> --project-id <PROJECT_ID> -c default_config.json --no-streaming

CLI Output

═══════════════════════════════════════════════════════════
  📋 Real-Time Log Viewer Available
═══════════════════════════════════════════════════════════
  View logs in real-time at:
  http://192.168.1.100:8998
  Logs will stream automatically as tests execute
═══════════════════════════════════════════════════════════

Accessing the Log Viewer

1. Open browser on any device on the same network
2. Navigate to the displayed URL (e.g., http://192.168.1.100:8998)
3. View logs streaming in real-time as tests execute

Log Viewer Interface

Header:

• Status indicator (🟢 Connected / 🔴 Disconnected / 🔴 Stream Ended)
• CLI badge
• Version info

Controls:

• Clear: Remove all logs from display
• Auto-scroll: Toggle automatic scrolling (enabled by default)
• Download Logs: Download log file (works always!)
• Search box: Filter logs by text
• Log count: Live counter

Filter Buttons:

• INFO (blue) - Active by default ✓
• WARN (orange) - Active by default ✓
• ERROR (red) - Active by default ✓
• DEBUG (gray) - Inactive by default (reduces clutter)
• CHIP (bluish green) - Active by default ✓
• PYTHON (purple) - Active by default ✓

🧪 Testing

Manual Testing Checklist

• Start tests, verify logs appear in real-time
• Test all filter buttons (INFO, WARNING, ERROR, DEBUG, CHIP, PYTHON)
• Test search functionality
• Test auto-scroll behavior
• Test clear logs button
• Test download during execution
• Test download after execution
• Test multiple browser connections
• Test page refresh during streaming
• Verify no impact on test execution

📸 Screenshots

Log Viewer Interface

[gemini-code-assist]

Code Review

This pull request introduces a real-time log display feature for the CLI, utilizing the "rich" library to provide live feedback during specific test execution steps. The implementation includes a new RealtimeLogDisplay manager, integration with the websocket communication layer, dependency updates in pyproject.toml, and a suite of unit tests. Review feedback suggests several optimizations, including more robust timestamp handling, the removal of dead code, and performance improvements for the rendering logic.

[antonio-amjr]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces real-time log streaming for test runs, enabling users to view live logs in a browser interface via a new HTTP server and Server-Sent Events (SSE). The implementation includes a dedicated HTML/JavaScript log viewer, a LogStreamHandler for coordination, and updates to the CLI to display the viewer URL and manage the streaming lifecycle. Feedback focuses on improving efficiency by streaming log downloads in chunks to prevent memory exhaustion and replacing hardcoded values for the port and streaming enablement with configuration-based settings.