From c979429deece6aba6fd6eb92a8cd69b033ee8d1b Mon Sep 17 00:00:00 2001
From: antonio-amjr <116589331+antonio-amjr@users.noreply.github.com>
Date: Mon, 25 May 2026 11:28:59 -0300
Subject: [PATCH 1/8] [FEATURE] Adding Realtime Log feature to CLI (#81)

* Adding Real-time log feature access to the CLI via browser

* Changing browser page style and adding download logs feature

* Moving log streaming URL display to closer to the Test Run execution start

* reducing Real-time log description in default config JSON

* Supressing exceptions when no browser is connected

Also fixing the downloaded file to show breakline properly.

* Reading file in chunks for download

Also fixing incomplete log streaming

* Adding run_tests argument option to disable real-time logs
---
 th_cli/commands/run_tests.py          |  28 +-
 th_cli/test_run/log_stream_handler.py | 160 +++++
 th_cli/test_run/log_viewer.html       | 827 ++++++++++++++++++++++++++
 th_cli/test_run/logging.py            |  71 ++-
 th_cli/test_run/logs_http_server.py   | 282 +++++++++
 5 files changed, 1365 insertions(+), 3 deletions(-)
 create mode 100644 th_cli/test_run/log_stream_handler.py
 create mode 100644 th_cli/test_run/log_viewer.html
 create mode 100644 th_cli/test_run/logs_http_server.py

diff --git a/th_cli/commands/run_tests.py b/th_cli/commands/run_tests.py
index 1ba7405..6b7532a 100644
--- a/th_cli/commands/run_tests.py
+++ b/th_cli/commands/run_tests.py
@@ -97,6 +97,11 @@
     is_flag=True,
     help=colorize_help("Disable colored output for test execution status."),
 )
+@click.option(
+    "--no-streaming",
+    is_flag=True,
+    help=colorize_help("Disable real-time log streaming via web browser (enabled by default)."),
+)
 @async_cmd
 @click.pass_context
 async def run_tests(
@@ -107,6 +112,7 @@ async def run_tests(
     pics_config_folder: str | None = None,
     project_id: int | None = None,
     no_color: bool = False,
+    no_streaming: bool = False,
 ) -> None:
     """Execute a CLI test run from selected test cases.
 
@@ -147,8 +153,9 @@ async def run_tests(
         async_apis = AsyncApis(client)
         test_collections_api = async_apis.test_collections_api
 
-        # Configure new log output for test.
-        log_path = test_logging.configure_logger_for_run(title=title)
+        # Configure new log output for test with real-time streaming (enabled by default)
+        enable_streaming = not no_streaming
+        log_path = test_logging.configure_logger_for_run(title=title, enable_log_streaming=enable_streaming)
 
         # Retrieve CLI project
         cli_project = await _get_cli_project(async_apis, project_id)
@@ -195,6 +202,20 @@ async def run_tests(
 
         click.echo(colorize_key_value("Selected tests", json.dumps(selected_tests_dict, indent=JSON_INDENT)))
 
+        # Display log streaming URL if available
+        log_stream_url = test_logging.get_log_stream_url()
+        if log_stream_url:
+            border = click.style("═" * 60, fg="cyan", bold=True)
+            click.echo("")
+            click.echo(border)
+            click.echo(click.style("  📋 Real-Time Log Viewer Available", fg="cyan", bold=True))
+            click.echo(border)
+            click.echo(click.style("  View logs in real-time at:", fg="bright_white", bold=True))
+            click.echo("  " + click.style(f"{log_stream_url}", fg="cyan", bold=True, underline=True))
+            click.echo(click.style("  Logs will stream automatically as tests execute", fg="bright_white"))
+            click.echo(border)
+            click.echo("")
+
         new_test_run = await _create_new_test_run_cli(
             async_apis,
             selected_tests=selected_tests_dict,
@@ -220,6 +241,9 @@ async def run_tests(
     except Exception as e:
         raise CLIError(f"Unexpected error during test execution: {e}")
     finally:
+        # Stop log streaming
+        test_logging.stop_log_streaming()
+        
         if client:
             await client.aclose()
         if _webrtc_handler:
diff --git a/th_cli/test_run/log_stream_handler.py b/th_cli/test_run/log_stream_handler.py
new file mode 100644
index 0000000..0c56aca
--- /dev/null
+++ b/th_cli/test_run/log_stream_handler.py
@@ -0,0 +1,160 @@
+#
+# Copyright (c) 2026 Project CHIP Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import datetime
+import queue
+import socket
+from typing import Optional
+
+from loguru import logger
+
+from .logs_http_server import LogsHTTPServer
+
+
+class LogStreamHandler:
+    """Main coordinator for real-time log streaming functionality."""
+
+    def __init__(self, port: int = 8998):
+        """Initialize the log stream handler.
+        
+        Args:
+            port: Port number for the HTTP server (default: 8998)
+        """
+        self.port = port
+        self.http_server = LogsHTTPServer(port=port)
+        self.log_queue: queue.Queue = queue.Queue(maxsize=1000)
+        self.is_running = False
+        self.log_file_path: Optional[str] = None
+        
+    def start(self, test_run_title: str = "Test Execution", log_file_path: Optional[str] = None) -> str:
+        """Start the log streaming HTTP server.
+        
+        Args:
+            test_run_title: Title of the test run for display
+            log_file_path: Path to the log file for download functionality
+            
+        Returns:
+            URL where logs can be viewed
+        """
+        if self.is_running:
+            logger.warning("Log stream handler already running")
+            return self._get_log_viewer_url()
+        
+        try:
+            # Store log file path for download functionality
+            self.log_file_path = log_file_path
+            
+            # Get local IP address
+            local_ip = self._get_local_ip()
+            
+            # Start HTTP server
+            self.http_server.start(
+                log_queue=self.log_queue,
+                test_run_title=test_run_title,
+                local_ip=local_ip,
+                log_file_path=log_file_path,
+            )
+            
+            self.is_running = True
+            
+            viewer_url = f"http://{local_ip}:{self.port}"
+            logger.info(f"Log stream viewer started: {viewer_url}")
+            
+            return viewer_url
+            
+        except Exception as e:
+            logger.error(f"Failed to start log stream handler: {e}")
+            raise
+    
+    def stop(self):
+        """Stop the log streaming HTTP server."""
+        if not self.is_running:
+            return
+        
+        try:
+            # Signal end of stream
+            if not self.log_queue.full():
+                try:
+                    self.log_queue.put_nowait(None)
+                except queue.Full:
+                    pass
+            
+            # Stop HTTP server
+            self.http_server.stop()
+            
+            self.is_running = False
+            logger.info("Log stream handler stopped")
+            
+        except Exception as e:
+            logger.error(f"Error stopping log stream handler: {e}")
+    
+    def add_log_entry(
+        self,
+        message: str,
+        level: str = "INFO",
+        timestamp: Optional[str] = None
+    ):
+        """Add a log entry to the stream.
+        
+        Args:
+            message: Log message text
+            level: Log level (INFO, WARNING, ERROR, DEBUG, etc.)
+            timestamp: ISO format timestamp (auto-generated if not provided)
+        """
+        if not self.is_running:
+            return
+        
+        if timestamp is None:
+            timestamp = datetime.datetime.now().isoformat()
+        
+        log_entry = {
+            "message": message,
+            "level": level.upper(),
+            "timestamp": timestamp,
+        }
+        
+        try:
+            # Try to add to queue without blocking
+            self.log_queue.put_nowait(log_entry)
+        except queue.Full:
+            # Queue is full, skip this entry silently to avoid blocking
+            # This is acceptable for real-time streaming when no browser is connected
+            pass
+    
+    def _get_local_ip(self) -> str:
+        """Get the local IP address of the machine.
+        
+        Returns:
+            Local IP address as string, or 'localhost' if unable to determine
+        """
+        try:
+            # Create a socket connection to determine local IP
+            s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+            # Connect to an external host (doesn't actually send data)
+            s.connect(("8.8.8.8", 80))
+            local_ip = s.getsockname()[0]
+            s.close()
+            return local_ip
+        except Exception:
+            return "localhost"
+    
+    def _get_log_viewer_url(self) -> str:
+        """Get the URL for the log viewer.
+        
+        Returns:
+            Log viewer URL
+        """
+        local_ip = self._get_local_ip()
+        return f"http://{local_ip}:{self.port}"
diff --git a/th_cli/test_run/log_viewer.html b/th_cli/test_run/log_viewer.html
new file mode 100644
index 0000000..4e38ca6
--- /dev/null
+++ b/th_cli/test_run/log_viewer.html
@@ -0,0 +1,827 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <title>Real-Time Log Viewer</title>
+    <style>
+        body {{
+            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+            background: #f5f5f5;
+            margin: 0;
+            padding: 0;
+            display: flex;
+            flex-direction: column;
+            min-height: 100vh;
+        }}
+
+        .matter-header {{
+            background: white;
+            border-bottom: 1px solid #e0e0e0;
+            padding: 12px 20px;
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+        }}
+
+        .header-start {{
+            display: flex;
+            align-items: center;
+            gap: 15px;
+        }}
+
+        .header-title {{
+            font-size: 18px;
+            font-weight: 600;
+            color: #333;
+            margin: 0;
+        }}
+
+        .header-end {{
+            display: flex;
+            align-items: center;
+            gap: 15px;
+        }}
+
+        .cli-indicator {{
+            background: #2196F3;
+            color: white;
+            padding: 4px 8px;
+            border-radius: 12px;
+            font-size: 11px;
+            font-weight: 500;
+        }}
+
+        .version-info {{
+            font-size: 12px;
+            color: #666;
+            text-align: right;
+        }}
+
+        .status-indicator {{
+            display: flex;
+            align-items: center;
+            gap: 8px;
+            padding: 4px 10px;
+            border-radius: 12px;
+            font-size: 11px;
+            font-weight: 500;
+        }}
+
+        .status-indicator.connected {{
+            background: #e8f5e9;
+            color: #2e7d32;
+            border: 1px solid #4caf50;
+        }}
+
+        .status-indicator.disconnected {{
+            background: #ffebee;
+            color: #c62828;
+            border: 1px solid #f44336;
+        }}
+
+        .status-dot {{
+            width: 8px;
+            height: 8px;
+            border-radius: 50%;
+            animation: pulse 2s infinite;
+        }}
+
+        .status-indicator.connected .status-dot {{
+            background: #4caf50;
+        }}
+
+        .status-indicator.disconnected .status-dot {{
+            background: #f44336;
+        }}
+
+        @keyframes pulse {{
+            0%, 100% {{ opacity: 1; }}
+            50% {{ opacity: 0.5; }}
+        }}
+
+        .main-content {{
+            flex: 1;
+            padding: 20px;
+            display: flex;
+            justify-content: center;
+            align-items: flex-start;
+            overflow: hidden;
+        }}
+
+        .p-dialog {{
+            background: white;
+            border-radius: 8px;
+            box-shadow: 0 4px 20px rgba(0,0,0,0.15);
+            width: 95%;
+            max-width: 1400px;
+            margin: 20px;
+            display: flex;
+            flex-direction: column;
+            max-height: calc(100vh - 120px);
+        }}
+
+        .p-dialog-header {{
+            padding: 16px 20px;
+            border-bottom: 1px solid #e0e0e0;
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            background: #fafafa;
+            border-radius: 8px 8px 0 0;
+            flex-shrink: 0;
+        }}
+
+        .p-dialog-title {{
+            font-size: 18px;
+            font-weight: 600;
+            color: #333;
+        }}
+
+        .p-dialog-content {{
+            padding: 20px;
+            flex: 1;
+            overflow: hidden;
+            display: flex;
+            flex-direction: column;
+        }}
+
+        .subheader {{
+            font-size: 16px;
+            color: #555;
+            margin-bottom: 15px;
+            font-weight: 500;
+        }}
+
+        .controls {{
+            background: #fafafa;
+            border: 1px solid #e0e0e0;
+            border-radius: 4px;
+            padding: 12px;
+            margin-bottom: 15px;
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            flex-wrap: wrap;
+            gap: 10px;
+            flex-shrink: 0;
+        }}
+
+        .control-group {{
+            display: flex;
+            gap: 10px;
+            align-items: center;
+            flex-wrap: wrap;
+        }}
+
+        .btn {{
+            background: white;
+            color: #333;
+            border: 1px solid #ccc;
+            padding: 6px 14px;
+            border-radius: 4px;
+            font-size: 13px;
+            cursor: pointer;
+            transition: all 0.2s;
+            font-weight: 500;
+        }}
+
+        .btn:hover {{
+            background: #f0f0f0;
+            border-color: #999;
+        }}
+
+        .btn.active {{
+            background: #2196F3;
+            border-color: #2196F3;
+            color: white;
+        }}
+
+        .btn.download {{
+            background: #4caf50;
+            border-color: #4caf50;
+            color: white;
+        }}
+
+        .btn.download:hover {{
+            background: #45a049;
+        }}
+
+        .log-count {{
+            font-size: 12px;
+            color: #666;
+            padding: 0 10px;
+        }}
+
+        .filter-group {{
+            display: flex;
+            gap: 6px;
+            flex-wrap: wrap;
+        }}
+
+        .filter-btn {{
+            padding: 4px 10px;
+            font-size: 11px;
+            border-radius: 4px;
+            border: 1px solid #ddd;
+            cursor: pointer;
+            transition: all 0.2s;
+            font-weight: 500;
+        }}
+
+        .filter-btn.level-info {{
+            background: #e3f2fd;
+            color: #1976d2;
+            border-color: #90caf9;
+        }}
+
+        .filter-btn.level-warning {{
+            background: #fff3e0;
+            color: #f57c00;
+            border-color: #ffb74d;
+        }}
+
+        .filter-btn.level-error {{
+            background: #ffebee;
+            color: #c62828;
+            border-color: #ef5350;
+        }}
+
+        .filter-btn.level-debug {{
+            background: #fafafa;
+            color: #757575;
+            border-color: #e0e0e0;
+        }}
+
+        .filter-btn.level-chiptool {{
+            background: #e0f2f1;
+            color: #00796b;
+            border-color: #4db6ac;
+        }}
+
+        .filter-btn.level-python {{
+            background: #f3e5f5;
+            color: #6a1b9a;
+            border-color: #ba68c8;
+        }}
+
+        .filter-btn.active {{
+            opacity: 1;
+            font-weight: 600;
+            border-width: 2px;
+        }}
+
+        .filter-btn:not(.active) {{
+            opacity: 0.4;
+        }}
+
+        .filter-btn:hover {{
+            opacity: 1;
+        }}
+
+        .log-container {{
+            flex: 1;
+            overflow-y: auto;
+            font-family: 'Consolas', 'Monaco', 'Courier New', monospace;
+            font-size: 13px;
+            line-height: 1.5;
+            background: #fafafa;
+            border: 1px solid #e0e0e0;
+            border-radius: 4px;
+            padding: 10px;
+        }}
+
+        .log-entry {{
+            padding: 4px 8px;
+            margin: 2px 0;
+            border-left: 3px solid transparent;
+            word-wrap: break-word;
+            white-space: pre-wrap;
+            transition: background 0.1s;
+            background: white;
+            border-radius: 2px;
+        }}
+
+        .log-entry:hover {{
+            background: #f5f5f5;
+        }}
+
+        .log-entry.level-info {{
+            border-left-color: #2196F3;
+        }}
+
+        .log-entry.level-warning {{
+            border-left-color: #ff9800;
+            background: #fff8e1;
+        }}
+
+        .log-entry.level-error {{
+            border-left-color: #f44336;
+            background: #ffebee;
+        }}
+
+        .log-entry.level-debug {{
+            border-left-color: #9e9e9e;
+            background: #fafafa;
+        }}
+
+        .log-entry.level-success {{
+            border-left-color: #4caf50;
+            background: #e8f5e9;
+        }}
+
+        .log-entry.level-chiptool {{
+            border-left-color: #009688;
+            background: #e0f2f1;
+        }}
+
+        .log-entry.level-python_test {{
+            border-left-color: #9c27b0;
+            background: #f3e5f5;
+        }}
+
+        .log-timestamp {{
+            color: #666;
+            font-weight: 500;
+            margin-right: 10px;
+        }}
+
+        .log-level {{
+            font-weight: 700;
+            margin-right: 10px;
+            padding: 2px 6px;
+            border-radius: 3px;
+            font-size: 10px;
+            display: inline-block;
+            min-width: 50px;
+            text-align: center;
+        }}
+
+        .log-level.INFO {{
+            background: #2196F3;
+            color: white;
+        }}
+
+        .log-level.WARNING {{
+            background: #ff9800;
+            color: white;
+        }}
+
+        .log-level.ERROR {{
+            background: #f44336;
+            color: white;
+        }}
+
+        .log-level.DEBUG {{
+            background: #9e9e9e;
+            color: white;
+        }}
+
+        .log-level.SUCCESS {{
+            background: #4caf50;
+            color: white;
+        }}
+
+        .log-level.CHIPTOOL {{
+            background: #009688;
+            color: white;
+        }}
+
+        .log-level.PYTHON_TEST {{
+            background: #9c27b0;
+            color: white;
+        }}
+
+        .log-message {{
+            color: #333;
+        }}
+
+        .empty-state {{
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            height: 100%;
+            color: #999;
+            font-size: 14px;
+        }}
+
+        .empty-state-icon {{
+            font-size: 48px;
+            margin-bottom: 16px;
+            opacity: 0.5;
+        }}
+
+        .log-container::-webkit-scrollbar {{
+            width: 10px;
+        }}
+
+        .log-container::-webkit-scrollbar-track {{
+            background: #f1f1f1;
+        }}
+
+        .log-container::-webkit-scrollbar-thumb {{
+            background: #ccc;
+            border-radius: 5px;
+        }}
+
+        .log-container::-webkit-scrollbar-thumb:hover {{
+            background: #999;
+        }}
+
+        .search-box {{
+            padding: 6px 10px;
+            background: white;
+            border: 1px solid #ccc;
+            border-radius: 4px;
+            color: #333;
+            font-size: 13px;
+            font-family: inherit;
+            width: 200px;
+        }}
+
+        .search-box:focus {{
+            outline: none;
+            border-color: #2196F3;
+        }}
+
+        .highlight {{
+            background: #ffeb3b;
+            color: #000;
+            padding: 0 2px;
+            border-radius: 2px;
+        }}
+
+        .status-info {{
+            background: #e8f5e9;
+            border: 1px solid #4caf50;
+            padding: 10px;
+            border-radius: 4px;
+            margin-bottom: 15px;
+            font-size: 13px;
+            color: #2e7d32;
+        }}
+    </style>
+</head>
+<body>
+    <div class="matter-header">
+        <div class="header-start">
+            <div class="header-title">Matter Certification Tool</div>
+        </div>
+        <div class="header-end">
+            <div id="statusIndicator" class="status-indicator disconnected">
+                <span class="status-dot"></span>
+                <span id="statusText">Connecting...</span>
+            </div>
+            <div class="cli-indicator">CLI</div>
+            <div class="version-info">
+                <div>Log Viewer</div>
+                <div style="font-size: 10px; color: #999;">Real-Time Stream</div>
+            </div>
+        </div>
+    </div>
+
+    <div class="main-content">
+        <div class="p-dialog" role="dialog">
+            <div class="p-dialog-header">
+                <span class="p-dialog-title">📋 Real-Time Log Viewer - {test_run_title}</span>
+            </div>
+
+            <div class="p-dialog-content">
+                <div class="status-info">
+                    &#128268; Live logs streaming in real-time from test execution
+                </div>
+
+                <div class="controls">
+                    <div class="control-group">
+                        <button id="clearBtn" class="btn" onclick="clearLogs()">Clear</button>
+                        <button id="autoScrollBtn" class="btn active" onclick="toggleAutoScroll()">Auto-scroll</button>
+                        <button id="downloadBtn" class="btn download" onclick="downloadLogs()">Download Logs</button>
+                        <input type="text" id="searchBox" class="search-box" placeholder="Search logs..." oninput="filterLogs()">
+                        <span class="log-count">Logs: <span id="logCount">0</span></span>
+                    </div>
+                    <div class="filter-group">
+                        <button class="filter-btn level-info active" onclick="toggleFilter('INFO')">INFO</button>
+                        <button class="filter-btn level-warning active" onclick="toggleFilter('WARNING')">WARN</button>
+                        <button class="filter-btn level-error active" onclick="toggleFilter('ERROR')">ERROR</button>
+                        <button class="filter-btn level-debug" onclick="toggleFilter('DEBUG')">DEBUG</button>
+                        <button class="filter-btn level-chiptool active" onclick="toggleFilter('CHIPTOOL')">CHIP</button>
+                        <button class="filter-btn level-python active" onclick="toggleFilter('PYTHON_TEST')">PYTHON</button>
+                    </div>
+                </div>
+
+                <div class="log-container" id="logContainer">
+                    <div class="empty-state">
+                        <div class="empty-state-icon">📡</div>
+                        <div>Waiting for logs...</div>
+                        <div style="font-size: 12px; margin-top: 8px; color: #bbb;">Logs will appear here in real-time as tests execute</div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <script>
+        let eventSource = null;
+        let autoScroll = true;
+        let logCount = 0;
+        let activeFilters = new Set(['INFO', 'WARNING', 'ERROR', 'CHIPTOOL', 'PYTHON_TEST', 'SUCCESS']);
+        let allLogs = [];
+        let logBatchQueue = [];
+        let batchProcessing = false;
+        let lastBatchTime = 0;
+        const BATCH_INTERVAL_MS = 50;
+        const MAX_BATCH_SIZE = 50;
+
+        function connectToLogStream() {{
+            const statusIndicator = document.getElementById('statusIndicator');
+            const statusText = document.getElementById('statusText');
+            
+            eventSource = new EventSource('/api/logs/stream');
+            
+            eventSource.addEventListener('connected', function(e) {{
+                console.log('Connected to log stream');
+                statusIndicator.className = 'status-indicator connected';
+                statusText.textContent = 'Connected';
+            }});
+            
+            eventSource.addEventListener('log', function(e) {{
+                const logEntry = JSON.parse(e.data);
+                logBatchQueue.push(logEntry);
+                scheduleBatchProcessing();
+            }});
+            
+            eventSource.addEventListener('keepalive', function(e) {{
+                // Silent keepalive
+            }});
+            
+            eventSource.addEventListener('end', function(e) {{
+                console.log('Log stream ended');
+                statusIndicator.className = 'status-indicator disconnected';
+                statusText.textContent = 'Stream Ended';
+                eventSource.close();
+                processBatchImmediately();
+            }});
+            
+            eventSource.onerror = function(e) {{
+                console.error('EventSource error:', e);
+                statusIndicator.className = 'status-indicator disconnected';
+                statusText.textContent = 'Disconnected';
+                
+                processBatchImmediately();
+                
+                setTimeout(() => {{
+                    if (eventSource.readyState === EventSource.CLOSED) {{
+                        console.log('Attempting to reconnect...');
+                        statusText.textContent = 'Reconnecting...';
+                        connectToLogStream();
+                    }}
+                }}, 3000);
+            }};
+        }}
+
+        function scheduleBatchProcessing() {{
+            if (batchProcessing) return;
+            
+            const now = Date.now();
+            const timeSinceLastBatch = now - lastBatchTime;
+            
+            if (timeSinceLastBatch >= BATCH_INTERVAL_MS || logBatchQueue.length >= MAX_BATCH_SIZE) {{
+                processBatch();
+            }} else {{
+                batchProcessing = true;
+                setTimeout(processBatch, BATCH_INTERVAL_MS - timeSinceLastBatch);
+            }}
+        }}
+
+        function processBatchImmediately() {{
+            if (logBatchQueue.length > 0) {{
+                processBatch();
+            }}
+        }}
+
+        function processBatch() {{
+            if (logBatchQueue.length === 0) {{
+                batchProcessing = false;
+                return;
+            }}
+            
+            const container = document.getElementById('logContainer');
+            const emptyState = container.querySelector('.empty-state');
+            
+            if (emptyState) {{
+                container.innerHTML = '';
+            }}
+            
+            const fragment = document.createDocumentFragment();
+            const batchSize = Math.min(logBatchQueue.length, MAX_BATCH_SIZE);
+            const batch = logBatchQueue.splice(0, batchSize);
+            
+            batch.forEach(entry => {{
+                allLogs.push(entry);
+                logCount++;
+                
+                const logDiv = createLogElement(entry);
+                fragment.appendChild(logDiv);
+            }});
+            
+            container.appendChild(fragment);
+            
+            document.getElementById('logCount').textContent = logCount;
+            
+            if (autoScroll) {{
+                container.scrollTop = container.scrollHeight;
+            }}
+            
+            lastBatchTime = Date.now();
+            batchProcessing = false;
+            
+            if (logBatchQueue.length > 0) {{
+                scheduleBatchProcessing();
+            }}
+        }}
+
+        function createLogElement(entry) {{
+            const logDiv = document.createElement('div');
+            const level = entry.level || 'INFO';
+            logDiv.className = `log-entry level-${{level.toLowerCase()}}`;
+            logDiv.dataset.level = level;
+            logDiv.dataset.message = entry.message || '';
+            
+            const timestamp = entry.timestamp || new Date().toISOString();
+            const timeStr = new Date(timestamp).toLocaleTimeString('en-US', {{ hour12: false }});
+            
+            logDiv.innerHTML = `<span class="log-timestamp">${{timeStr}}</span><span class="log-level ${{level}}">${{level}}</span><span class="log-message">${{escapeHtml(entry.message || '')}}</span>`;
+            
+            if (!activeFilters.has(level)) {{
+                logDiv.style.display = 'none';
+            }}
+            
+            return logDiv;
+        }}
+
+        function addLogEntry(entry) {{
+            logBatchQueue.push(entry);
+            scheduleBatchProcessing();
+        }}
+
+        function clearLogs() {{
+            const container = document.getElementById('logContainer');
+            container.innerHTML = `
+                <div class="empty-state">
+                    <div class="empty-state-icon">📋</div>
+                    <div>Logs cleared</div>
+                </div>
+            `;
+            allLogs = [];
+            logCount = 0;
+            document.getElementById('logCount').textContent = '0';
+        }}
+
+        function toggleAutoScroll() {{
+            autoScroll = !autoScroll;
+            const btn = document.getElementById('autoScrollBtn');
+            btn.classList.toggle('active', autoScroll);
+            
+            if (autoScroll) {{
+                const container = document.getElementById('logContainer');
+                container.scrollTop = container.scrollHeight;
+            }}
+        }}
+
+        function toggleFilter(level) {{
+            if (activeFilters.has(level)) {{
+                activeFilters.delete(level);
+            }} else {{
+                activeFilters.add(level);
+            }}
+            
+            const btn = event.target;
+            btn.classList.toggle('active');
+            
+            filterLogs();
+        }}
+
+        function filterLogs() {{
+            const searchText = document.getElementById('searchBox').value.toLowerCase();
+            const logEntries = document.querySelectorAll('.log-entry');
+            
+            logEntries.forEach(entry => {{
+                const level = entry.dataset.level;
+                const message = entry.dataset.message.toLowerCase();
+                
+                const levelMatch = activeFilters.has(level);
+                const searchMatch = !searchText || message.includes(searchText);
+                
+                entry.style.display = (levelMatch && searchMatch) ? 'block' : 'none';
+                
+                if (searchText && searchMatch) {{
+                    const messageEl = entry.querySelector('.log-message');
+                    const originalText = entry.dataset.message;
+                    const regex = new RegExp(`(${{escapeRegex(searchText)}})`, 'gi');
+                    messageEl.innerHTML = escapeHtml(originalText).replace(regex, '<span class="highlight">$1</span>');
+                }} else {{
+                    const messageEl = entry.querySelector('.log-message');
+                    messageEl.textContent = entry.dataset.message;
+                }}
+            }});
+        }}
+
+        function downloadLogs() {{
+            // First try server download (if server is still running)
+            fetch('/download_logs')
+                .then(response => {{
+                    if (response.ok) {{
+                        return response.blob();
+                    }}
+                    throw new Error('Server not available');
+                }})
+                .then(blob => {{
+                    // Server download successful
+                    const url = window.URL.createObjectURL(blob);
+                    const a = document.createElement('a');
+                    a.href = url;
+                    a.download = 'test_run_logs.log';
+                    document.body.appendChild(a);
+                    a.click();
+                    window.URL.revokeObjectURL(url);
+                    document.body.removeChild(a);
+                }})
+                .catch(error => {{
+                    // Server not available, use client-side download
+                    console.log('Server unavailable, using client-side download');
+                    downloadLogsClientSide();
+                }});
+        }}
+
+        function downloadLogsClientSide() {{
+            // Build log content from stored logs
+            let logContent = '';
+            allLogs.forEach(entry => {{
+                const timestamp = entry.timestamp || new Date().toISOString();
+                const level = entry.level || 'INFO';
+                const message = entry.message || '';
+                // Replace literal \n strings with actual newlines, then add entry
+                const cleanMessage = message.replace(/\\n/g, '\n');
+                logContent += `${{timestamp}} [${{level}}] ${{cleanMessage}}\n`;
+            }});
+
+            if (logContent === '') {{
+                alert('No logs to download');
+                return;
+            }}
+
+            // Create blob and download
+            const blob = new Blob([logContent], {{ type: 'text/plain;charset=utf-8' }});
+            const url = window.URL.createObjectURL(blob);
+            const a = document.createElement('a');
+            a.href = url;
+            
+            // Generate filename with current timestamp
+            const now = new Date();
+            const dateStr = now.toISOString().slice(0,19).replace(/[T:]/g, '-');
+            a.download = `test_run_logs_${{dateStr}}.log`;
+            
+            document.body.appendChild(a);
+            a.click();
+            window.URL.revokeObjectURL(url);
+            document.body.removeChild(a);
+            
+            console.log(`Downloaded ${{allLogs.length}} log entries client-side`);
+        }}
+
+        function escapeHtml(text) {{
+            const div = document.createElement('div');
+            div.textContent = text;
+            return div.innerHTML;
+        }}
+
+        function escapeRegex(text) {{
+            return text.replace(/[.*+?^${{}}()|[\\]\\\\]/g, '\\\\$&');
+        }}
+
+        document.getElementById('logContainer').addEventListener('scroll', function() {{
+            const container = this;
+            const isNearBottom = container.scrollHeight - container.scrollTop - container.clientHeight < 100;
+            
+            if (!isNearBottom && autoScroll) {{
+                autoScroll = false;
+                document.getElementById('autoScrollBtn').classList.remove('active');
+            }} else if (isNearBottom && !autoScroll) {{
+                autoScroll = true;
+                document.getElementById('autoScrollBtn').classList.add('active');
+            }}
+        }});
+
+        window.addEventListener('load', function() {{
+            connectToLogStream();
+        }});
+
+        window.addEventListener('beforeunload', function() {{
+            if (eventSource) {{
+                eventSource.close();
+            }}
+        }});
+    </script>
+</body>
+</html>
diff --git a/th_cli/test_run/logging.py b/th_cli/test_run/logging.py
index 67b21b2..05fdcd6 100644
--- a/th_cli/test_run/logging.py
+++ b/th_cli/test_run/logging.py
@@ -15,6 +15,7 @@
 #
 import datetime
 import os
+from typing import Optional
 
 from loguru import logger
 
@@ -28,8 +29,22 @@
 PYTHON_TEST_LEVEL = "PYTHON_TEST"
 logger.level(PYTHON_TEST_LEVEL, no=22, icon="🐍", color="<cyan>")
 
+# Global reference to log stream handler (if enabled)
+_log_stream_handler: Optional["LogStreamHandler"] = None
 
-def configure_logger_for_run(title: str) -> str:
+
+def configure_logger_for_run(title: str, enable_log_streaming: bool = False) -> str:
+    """Configure logger for a test run.
+    
+    Args:
+        title: Title of the test run
+        enable_log_streaming: Whether to enable real-time log streaming
+        
+    Returns:
+        Path to the log file
+    """
+    global _log_stream_handler
+    
     # Reset (Remove all sinks from logger)
     logger.remove()
 
@@ -41,4 +56,58 @@ def configure_logger_for_run(title: str) -> str:
 
     logger.add(log_path, enqueue=True, format=config.log_config.format, mode="w")
 
+    # Add streaming sink if enabled
+    if enable_log_streaming:
+        try:
+            from th_cli.test_run.log_stream_handler import LogStreamHandler
+
+            _log_stream_handler = LogStreamHandler(port=8998)
+            viewer_url = _log_stream_handler.start(test_run_title=title, log_file_path=log_path)
+            # Add custom sink that forwards logs to the stream handler
+            def stream_sink(message):
+                """Custom sink that forwards logs to the HTTP stream."""
+                try:
+                    record = message.record
+                    _log_stream_handler.add_log_entry(
+                        message=record["message"],
+                        level=record["level"].name,
+                        timestamp=record["time"].isoformat()
+                    )
+                except Exception:
+                    # Silently fail to avoid disrupting logging
+                    pass
+
+            # Add sink with enqueue=True to prevent re-entrancy and catch=True to suppress errors
+            logger.add(stream_sink, format="{message}", catch=True)
+            logger.info(f"Real-time log streaming enabled: {viewer_url}")
+
+        except Exception as e:
+            logger.warning(f"Failed to enable log streaming: {e}")
+            _log_stream_handler = None
+
     return log_path
+
+
+def stop_log_streaming():
+    """Stop the log streaming server if it's running."""
+    global _log_stream_handler
+    
+    if _log_stream_handler:
+        try:
+            _log_stream_handler.stop()
+            logger.info("Log streaming stopped")
+        except Exception as e:
+            logger.warning(f"Error stopping log streaming: {e}")
+        finally:
+            _log_stream_handler = None
+
+
+def get_log_stream_url() -> Optional[str]:
+    """Get the URL for the log viewer if streaming is enabled.
+    
+    Returns:
+        URL string or None if streaming is not enabled
+    """
+    if _log_stream_handler and _log_stream_handler.is_running:
+        return _log_stream_handler._get_log_viewer_url()
+    return None
diff --git a/th_cli/test_run/logs_http_server.py b/th_cli/test_run/logs_http_server.py
new file mode 100644
index 0000000..3a14027
--- /dev/null
+++ b/th_cli/test_run/logs_http_server.py
@@ -0,0 +1,282 @@
+#
+# Copyright (c) 2026 Project CHIP Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import html
+import json
+import queue
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Optional
+
+from loguru import logger
+
+# HTTP Endpoints
+ENDPOINT_ROOT = "/"
+ENDPOINT_LOGS_STREAM = "/api/logs/stream"
+ENDPOINT_DOWNLOAD_LOGS = "/download_logs"
+
+
+class LogStreamingHandler(BaseHTTPRequestHandler):
+    """HTTP handler for streaming log data in real-time."""
+
+    def do_GET(self):
+        """Handle GET requests for log streaming."""
+        if self.path == ENDPOINT_ROOT:
+            self.serve_log_viewer()
+        elif self.path == ENDPOINT_LOGS_STREAM:
+            self.stream_logs()
+        elif self.path == ENDPOINT_DOWNLOAD_LOGS:
+            self.download_logs()
+        else:
+            logger.warning(f"404 for GET {self.path}")
+            self.send_error(404)
+    
+    def download_logs(self):
+        """Serve the log file for download using chunked streaming."""
+        log_file_path = getattr(self.server, "log_file_path", None)
+        
+        if not log_file_path or not Path(log_file_path).exists():
+            self.send_error(404, "Log file not found")
+            return
+        
+        try:
+            file_path = Path(log_file_path)
+            filename = file_path.name
+            file_size = file_path.stat().st_size
+            
+            # Send headers
+            self.send_response(200)
+            self.send_header("Content-Type", "text/plain; charset=utf-8")
+            self.send_header("Content-Disposition", f'attachment; filename="{filename}"')
+            self.send_header("Content-Length", str(file_size))
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.end_headers()
+            
+            # Stream file in chunks to avoid loading entire file into memory
+            CHUNK_SIZE = 65536  # 64KB chunks
+            bytes_sent = 0
+
+            with open(log_file_path, 'rb') as f:
+                while chunk := f.read(CHUNK_SIZE):
+                    self.wfile.write(chunk)
+                    bytes_sent += len(chunk)
+
+            logger.info(f"Log file downloaded: {filename} ({bytes_sent} bytes)")
+            
+        except (BrokenPipeError, ConnectionResetError, ConnectionAbortedError):
+            # Client disconnected during download - normal, not an error
+            logger.debug("Client disconnected during log file download")
+        except Exception as e:
+            logger.error(f"Error serving log file: {e}")
+            # Note: Can't send error response because headers were already sent
+
+    def stream_logs(self):
+        """Stream logs using Server-Sent Events (SSE)."""
+        logger.info("Client connected for log stream")
+        
+        # Send SSE headers
+        self.send_response(200)
+        self.send_header("Content-Type", "text/event-stream")
+        self.send_header("Cache-Control", "no-cache")
+        self.send_header("Connection", "keep-alive")
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.end_headers()
+
+        # Get the log queue from the server
+        log_queue = getattr(self.server, "log_queue", None)
+        if not log_queue:
+            logger.error("No log queue found on server for streaming")
+            return
+
+        logger.info("Starting to stream logs to client via SSE")
+        sent_count = 0
+        client_disconnected = False
+        
+        try:
+            # Send initial connection message
+            if not self._send_sse_event("connected", {"message": "Log stream connected"}):
+                logger.debug("Client disconnected during initial connection")
+                return
+            
+            while not client_disconnected:
+                try:
+                    # Get log entry from queue with timeout
+                    log_entry = log_queue.get(timeout=1.0)
+                    
+                    if log_entry is None:  # Signal to stop
+                        logger.info("Received end-of-stream signal for logs")
+                        self._send_sse_event("end", {"message": "Log stream ended"})
+                        break
+
+                    # Send log entry as SSE event
+                    if not self._send_sse_event("log", log_entry):
+                        logger.debug("Client disconnected while streaming")
+                        client_disconnected = True
+                        break
+                        
+                    sent_count += 1
+                    
+                    if sent_count % 100 == 0:
+                        logger.debug(f"Sent {sent_count} log entries to client")
+
+                except queue.Empty:
+                    # Send keepalive to prevent connection timeout
+                    if not self._send_sse_event("keepalive", {"timestamp": time.time()}):
+                        logger.debug("Client disconnected during keepalive")
+                        client_disconnected = True
+                        break
+                    continue
+                except Exception as e:
+                    logger.debug(f"Error streaming log: {e}")
+                    break
+
+        except BrokenPipeError:
+            logger.debug("Client disconnected (broken pipe)")
+        except Exception as e:
+            logger.debug(f"Log streaming error: {e}")
+
+        logger.info(f"Log stream ended, total entries sent: {sent_count}")
+
+    def _send_sse_event(self, event_type: str, data: dict) -> bool:
+        """Send a Server-Sent Event.
+        
+        Returns:
+            True if event was sent successfully, False if client disconnected
+        """
+        try:
+            event_data = f"event: {event_type}\ndata: {json.dumps(data)}\n\n"
+            self.wfile.write(event_data.encode('utf-8'))
+            self.wfile.flush()
+            return True
+        except (BrokenPipeError, ConnectionResetError, ConnectionAbortedError):
+            # Client disconnected - this is normal, not an error
+            return False
+        except Exception as e:
+            logger.debug(f"Error sending SSE event: {e}")
+            return False
+
+    def serve_log_viewer(self):
+        """Serve the log viewer HTML page."""
+        # Get configuration from server
+        test_run_title = getattr(self.server, "test_run_title", "Test Execution")
+        
+        # Read HTML template from file
+        try:
+            template_path = Path(__file__).parent / "log_viewer.html"
+            with open(template_path, "r", encoding="utf-8") as f:
+                html_template = f.read()
+
+            # Replace placeholders
+            html_content = html_template.format(
+                test_run_title=html.escape(test_run_title)
+            )
+        except Exception as e:
+            logger.error(f"Failed to load HTML template: {e}")
+            # Fallback to simple HTML
+            html_content = f"""
+            <html>
+            <head><title>Log Viewer Error</title></head>
+            <body>
+                <h1>Error loading log viewer interface</h1>
+                <p>Template error: {html.escape(str(e))}</p>
+                <p>Test Run: {html.escape(test_run_title)}</p>
+            </body>
+            </html>
+            """
+
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        # Prevent caching
+        self.send_header("Cache-Control", "no-store, no-cache, must-revalidate, max-age=0")
+        self.send_header("Pragma", "no-cache")
+        self.send_header("Expires", "0")
+        self.send_header("ETag", f'"{int(time.time())}"')
+        self.end_headers()
+        self.wfile.write(html_content.encode("utf-8"))
+
+    def log_message(self, format, *args):
+        """Suppress HTTP access logs to avoid clutter."""
+        pass
+
+
+class LogsHTTPServer:
+    """Manages HTTP server for real-time log streaming."""
+
+    def __init__(self, port: int = 8998):
+        """Initialize the logs HTTP server.
+        
+        Args:
+            port: Port number for the HTTP server (default: 8998)
+        """
+        self.port = port
+        self.server: Optional[ThreadingHTTPServer] = None
+        self.server_thread: Optional[threading.Thread] = None
+
+    def start(
+        self,
+        log_queue: queue.Queue,
+        test_run_title: str = "Test Execution",
+        local_ip: Optional[str] = None,
+        log_file_path: Optional[str] = None,
+    ):
+        """Start HTTP server for log streaming.
+        
+        Args:
+            log_queue: Queue containing log entries to stream
+            test_run_title: Title of the test run for display
+            local_ip: Local IP address for display (defaults to localhost)
+            log_file_path: Path to log file for download functionality
+        """
+        try:
+            # Use ThreadingHTTPServer for better concurrency
+            self.server = ThreadingHTTPServer(("0.0.0.0", self.port), LogStreamingHandler)
+            self.server.allow_reuse_address = True
+
+            # Set required attributes on the server
+            self.server.log_queue = log_queue
+            self.server.test_run_title = test_run_title
+            self.server.local_ip = local_ip or "localhost"
+            self.server.log_file_path = log_file_path
+
+            logger.info(f"Logs HTTP server configured for test run: {test_run_title}")
+
+            def run_server():
+                logger.info(f"Starting logs HTTP server on port {self.port}")
+                try:
+                    self.server.serve_forever()
+                except Exception as e:
+                    logger.error(f"Logs HTTP server error: {e}")
+
+            self.server_thread = threading.Thread(target=run_server, daemon=True)
+            self.server_thread.start()
+            logger.info(f"Logs HTTP server thread started on port {self.port}")
+
+        except Exception as e:
+            logger.error(f"Failed to start logs HTTP server: {e}")
+            raise
+
+    def stop(self):
+        """Stop HTTP server."""
+        if self.server:
+            try:
+                self.server.shutdown()
+                logger.info("Logs HTTP server stopped")
+            except Exception as e:
+                logger.debug(f"Error stopping logs HTTP server: {e}")
+            finally:
+                self.server = None
+                self.server_thread = None

From ed93760f65ec9964f75816602bd7079bdddc5840 Mon Sep 17 00:00:00 2001
From: abhisheksingh-esp <abhishek.singh@espressif.com>
Date: Tue, 26 May 2026 17:03:36 +0530
Subject: [PATCH 2/8] [Fix] th-cli --version Surfaces Backend And SDK Versions
 (#999) (#85)

* [Fix] th-cli --version Surfaces Backend And SDK Versions (#999)

* Update th_cli/utils.py

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
---
 th_cli/utils.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/th_cli/utils.py b/th_cli/utils.py
index 6aebdf7..fde074c 100644
--- a/th_cli/utils.py
+++ b/th_cli/utils.py
@@ -426,7 +426,7 @@ def get_versions() -> dict:
         sync_apis = SyncApis(client)
         version_api = sync_apis.version_api
         versions_info = version_api.get_test_harness_backend_version_api_v1_version_get()
-        return versions_info
+        return versions_info.model_dump(mode='json')
     except CLIError:
         raise  # Re-raise CLI Errors as-is
     except UnexpectedResponse:

From 19c41e3c0354fac7f5fc18abf996476c596d7e4e Mon Sep 17 00:00:00 2001
From: antonio-amjr <116589331+antonio-amjr@users.noreply.github.com>
Date: Tue, 26 May 2026 14:59:06 -0300
Subject: [PATCH 3/8] [Feature] Config Output To Project Command (#84)

* Adding config output for CLI project command

* Improving __print_config() method and adding short flags
---
 th_cli/commands/project.py | 16 ++++++++++++++--
 th_cli/utils.py            |  5 +++++
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/th_cli/commands/project.py b/th_cli/commands/project.py
index 336875d..5fe6ed3 100644
--- a/th_cli/commands/project.py
+++ b/th_cli/commands/project.py
@@ -34,7 +34,7 @@
     italic,
 )
 from th_cli.exceptions import CLIError, handle_api_error, handle_file_error
-from th_cli.utils import __print_json, read_pics_config
+from th_cli.utils import __print_config, __print_json, read_pics_config
 from th_cli.validation import validate_directory_path
 
 TABLE_FORMAT = "{:<5} {:25} {:28}"
@@ -125,20 +125,29 @@ def create(name: str, config: str | None, pics_config_folder: str | None) -> Non
 )
 @click.option(
     "--json",
+    "-j",
     is_flag=True,
     default=False,
     help=colorize_help("Print JSON response for more details"),
 )
+@click.option(
+    "--config",
+    "-c",
+    is_flag=True,
+    default=False,
+    help=colorize_help("Print project configuration in JSON format")
+)
 def list_projects(
     id: int | None,
     skip: int | None,
     limit: int | None,
     archived: bool,
     json: bool,
+    config: bool,
 ) -> None:
     """List projects"""
     with get_sync_apis("list") as sync_apis:
-        _list_projects(sync_apis, id, archived, skip, limit, json)
+        _list_projects(sync_apis, id, archived, skip, limit, json, config)
 
 
 # Click command to update an existing project
@@ -253,6 +262,7 @@ def _list_projects(
     skip: int | None,
     limit: int | None,
     json: bool,
+    config: bool,
 ) -> None:
     """List projects"""
 
@@ -300,6 +310,8 @@ def __print_project(project: dict) -> None:
 
     if json:
         __print_json(projects)
+    elif config:
+        __print_config(projects)
     else:
         __print_table(projects)
 
diff --git a/th_cli/utils.py b/th_cli/utils.py
index fde074c..80c3d91 100644
--- a/th_cli/utils.py
+++ b/th_cli/utils.py
@@ -38,6 +38,11 @@
 def __print_json(object: Any) -> None:
     click.echo(colorize_dump(__json_string(object)))
 
+def __print_config(project: Any) -> None:
+    if isinstance(project, list):
+        raise CLIError("Please provide a single project ID (using --id) to print the configuration.")
+    config = project.config if project.config is not None else {}
+    click.echo(colorize_dump(json.dumps(config, indent=4, default=str)))
 
 def __json_string(object: Any) -> str:
     if object is None:

From e56bf4c444b40fdbda918dcce0a8f5fd28af0c5a Mon Sep 17 00:00:00 2001
From: Romulo Quidute Filho <116586593+rquidute@users.noreply.github.com>
Date: Tue, 9 Jun 2026 17:36:37 -0300
Subject: [PATCH 4/8] Add CI workflow to run pytest on every PR (#95)

* Add CI workflow to run pytest on every PR

Adds .github/workflows/python-tests.yml which:
- Triggers on all pull requests (any target branch)
- Sets up Python 3.10 and installs dependencies via Poetry (with venv cache)
- Runs ./scripts/run_pytest.py (existing test runner)
- Fails if coverage drops below 85% (enforced by pyproject.toml)
- Uploads coverage.xml and htmlcov/ as artifacts on every run

Tracks: https://github.com/project-chip/certification-tool/issues/1020

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Fix CI: bump action versions to v4/v5

actions/upload-artifact@v3 was deprecated and disabled by GitHub in
November 2024, causing the job setup to fail before any steps ran.

Bump all actions to their current major versions:
- actions/checkout: v3 -> v4
- actions/setup-python: v4 -> v5
- actions/cache: v3 -> v4
- actions/upload-artifact: v3 -> v4

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Fix CI: correct test runner script name (run_pytest.sh not .py)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Fix failing test and align coverage threshold with actual coverage

- Fix test_test_run_execution_log_whitespace_content: Click prepends a
  DeprecationWarning line when invoking a deprecated option (--log).
  Strip DeprecationWarning lines before asserting on output content.

- Lower --cov-fail-under from 85 to 65 to match the actual coverage
  achieved by the current test suite (65.54%). The 85% target was
  aspirational and not yet reached; using it as a hard gate would
  permanently block CI on every PR.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Fix CI: use Python 3.12 to match development environment

Python 3.10's unittest.mock._dot_lookup resolves dotted patch paths
differently from 3.12: it walks the path with getattr, finds the
imported Click Command object at 'th_cli.commands.abort_testing' (due
to 'from .abort_testing import abort_testing' in __init__.py), and
then fails trying to get 'get_client' off the Command object.

Python 3.12 correctly resolves the patch target via sys.modules,
finding the module rather than the imported name.

All tests pass locally on 3.12; switching CI to match eliminates
the AttributeError failures across all command modules.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Revert coverage threshold back to 85%

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 .github/workflows/python-tests.yml | 48 ++++++++++++++++++++++++++++++
 tests/test_test_run_execution.py   |  6 +++-
 2 files changed, 53 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/python-tests.yml

diff --git a/.github/workflows/python-tests.yml b/.github/workflows/python-tests.yml
new file mode 100644
index 0000000..7c9d550
--- /dev/null
+++ b/.github/workflows/python-tests.yml
@@ -0,0 +1,48 @@
+name: Python Tests
+
+on:
+  pull_request:
+
+jobs:
+  run-tests:
+    name: Run unit tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out Git repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+          installer-parallel: true
+
+      - name: Load cached venv
+        id: cached-poetry-dependencies
+        uses: actions/cache@v4
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-${{ hashFiles('**/poetry.lock') }}
+
+      - name: Install dependencies
+        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+        run: poetry install --no-interaction --no-root
+
+      - name: Run tests
+        run: ./scripts/run_pytest.sh
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: coverage-report
+          path: |
+            coverage.xml
+            htmlcov/
diff --git a/tests/test_test_run_execution.py b/tests/test_test_run_execution.py
index f66c251..3b6141b 100644
--- a/tests/test_test_run_execution.py
+++ b/tests/test_test_run_execution.py
@@ -693,8 +693,12 @@ def test_test_run_execution_log_whitespace_content(
 
         # Assert
         assert result.exit_code == 0
+        # Click prepends a DeprecationWarning line for deprecated options; strip it before comparing
+        output_without_warning = "\n".join(
+            line for line in result.output.splitlines() if not line.startswith("DeprecationWarning:")
+        )
         # Should still output the whitespace content as-is
-        assert result.output.strip() == log_content.rstrip()
+        assert output_without_warning.strip() == log_content.rstrip()
 
     def test_test_run_execution_log_generic_exception(
         self,

From 34de9c312feea29e1069f5d821be4eaae2f78b02 Mon Sep 17 00:00:00 2001
From: Romulo Quidute Filho <116586593+rquidute@users.noreply.github.com>
Date: Mon, 22 Jun 2026 17:19:01 -0300
Subject: [PATCH 5/8] feat: add project export and import CLI commands (#1025)
 (#98)

* feat: add project export and import CLI commands (#1025)

Add 'project export' and 'project import' subcommands to the CLI,
wiring up the existing backend endpoints:
- GET /api/v1/projects/{id}/export
- POST /api/v1/projects/import

project export:
- Downloads the project config as a JSON file
- Defaults to '<project-name>-project-config.json' if no output file is given
- Accepts --output-file / -o to specify a custom path

project import:
- Accepts --file / -f pointing to a previously exported JSON file
- Sends the file bytes to the backend and prints the new project ID

Also adds full unit test coverage in tests/test_project_commands.py
(TestExportProjectCommand and TestImportProjectCommand).

Closes #1025

* fix: resolve unit test failures in project export/import and logger tests

- Add missing 'import json' to test_project_commands.py
- Update test_run_tests_logger_configuration to include enable_log_streaming=True
  in the expected configure_logger_for_run call, matching the actual call signature

* fix: apply code review suggestions from PR #98

- Use model_dump_json(indent=2) instead of model_dump() + json.dumps()
  to correctly serialize Pydantic models with non-standard types
- Split OSError handling in _import_project into FileNotFoundError
  and generic OSError to avoid broken error messages from wrapping
  OSError in FileNotFoundError
---
 tests/test_project_commands.py | 211 ++++++++++++++++++++++++++++++++-
 tests/test_run_tests.py        |   2 +-
 th_cli/commands/project.py     |  84 ++++++++++++-
 3 files changed, 294 insertions(+), 3 deletions(-)

diff --git a/tests/test_project_commands.py b/tests/test_project_commands.py
index 70c1879..662589e 100644
--- a/tests/test_project_commands.py
+++ b/tests/test_project_commands.py
@@ -13,8 +13,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-"""Tests for the project commands (create, delete, list, update)."""
+"""Tests for the project commands (create, delete, list, update, export, import)."""
 
+import json
 from pathlib import Path
 from unittest.mock import Mock, patch
 
@@ -519,3 +520,211 @@ def test_update_project_help_message(self, cli_runner: CliRunner) -> None:
         assert "update" in result.output
         assert "--id" in result.output
         assert "--config" in result.output
+
+
+@pytest.mark.unit
+@pytest.mark.cli
+class TestExportProjectCommand:
+    """Test cases for the project export command."""
+
+    def test_export_project_success_default_filename(
+        self,
+        cli_runner: CliRunner,
+        mock_sync_apis: Mock,
+        sample_project: api_models.Project,
+        temp_dir: Path,
+    ) -> None:
+        """Test successful project export with auto-generated filename."""
+        # Arrange
+        project_create = api_models.ProjectCreate(
+            name="Test Project",
+            config=sample_project.config,
+            pics=api_models.PICS(clusters={}),
+        )
+        mock_sync_apis.projects_api.export_project_config_api_v1_projects__id__export_get.return_value = (
+            project_create
+        )
+
+        with patch("th_cli.commands.project.SyncApis", return_value=mock_sync_apis):
+            with cli_runner.isolated_filesystem(temp_dir=temp_dir):
+                # Act
+                result = cli_runner.invoke(project, ["export", "--id", "1"])
+
+        # Assert
+        assert result.exit_code == 0
+        assert "exported to" in result.output
+        mock_sync_apis.projects_api.export_project_config_api_v1_projects__id__export_get.assert_called_once_with(id=1)
+
+    def test_export_project_success_custom_filename(
+        self,
+        cli_runner: CliRunner,
+        mock_sync_apis: Mock,
+        sample_project: api_models.Project,
+        temp_dir: Path,
+    ) -> None:
+        """Test successful project export to a specified output file."""
+        # Arrange
+        project_create = api_models.ProjectCreate(
+            name="Test Project",
+            config=sample_project.config,
+            pics=api_models.PICS(clusters={}),
+        )
+        mock_sync_apis.projects_api.export_project_config_api_v1_projects__id__export_get.return_value = (
+            project_create
+        )
+        output_path = str(temp_dir / "my_export.json")
+
+        with patch("th_cli.commands.project.SyncApis", return_value=mock_sync_apis):
+            # Act
+            result = cli_runner.invoke(project, ["export", "--id", "1", "--output-file", output_path])
+
+        # Assert
+        assert result.exit_code == 0
+        assert f"exported to '{output_path}'" in result.output
+        assert Path(output_path).exists()
+        saved = json.loads(Path(output_path).read_text())
+        assert saved["name"] == "Test Project"
+
+    def test_export_project_file_content_is_valid_json(
+        self,
+        cli_runner: CliRunner,
+        mock_sync_apis: Mock,
+        sample_project: api_models.Project,
+        temp_dir: Path,
+    ) -> None:
+        """Test that the exported file contains valid JSON matching the project config."""
+        # Arrange
+        project_create = api_models.ProjectCreate(
+            name="My Device",
+            config=sample_project.config,
+            pics=api_models.PICS(clusters={}),
+        )
+        mock_sync_apis.projects_api.export_project_config_api_v1_projects__id__export_get.return_value = (
+            project_create
+        )
+        output_path = str(temp_dir / "export.json")
+
+        with patch("th_cli.commands.project.SyncApis", return_value=mock_sync_apis):
+            result = cli_runner.invoke(project, ["export", "--id", "42", "--output-file", output_path])
+
+        assert result.exit_code == 0
+        data = json.loads(Path(output_path).read_text())
+        assert data["name"] == "My Device"
+        assert "config" in data
+
+    def test_export_project_api_error(
+        self,
+        cli_runner: CliRunner,
+        mock_sync_apis: Mock,
+    ) -> None:
+        """Test project export with API error."""
+        # Arrange
+        mock_sync_apis.projects_api.export_project_config_api_v1_projects__id__export_get.side_effect = (
+            UnexpectedResponse(status_code=404, content=b"Not Found")
+        )
+
+        with patch("th_cli.commands.project.SyncApis", return_value=mock_sync_apis):
+            result = cli_runner.invoke(project, ["export", "--id", "99"])
+
+        assert result.exit_code == 1
+        assert "Error: Failed to export project ID '99' (Status: 404) - Not Found" in result.output
+
+    def test_export_project_help_message(self, cli_runner: CliRunner) -> None:
+        """Test the help message for the export command."""
+        result = cli_runner.invoke(project, ["export", "--help"])
+
+        assert result.exit_code == 0
+        assert "--id" in result.output
+        assert "--output-file" in result.output
+
+
+@pytest.mark.unit
+@pytest.mark.cli
+class TestImportProjectCommand:
+    """Test cases for the project import command."""
+
+    def test_import_project_success(
+        self,
+        cli_runner: CliRunner,
+        mock_sync_apis: Mock,
+        sample_project: api_models.Project,
+        temp_dir: Path,
+    ) -> None:
+        """Test successful project import from a JSON file."""
+        # Arrange
+        import_file = temp_dir / "import.json"
+        import_file.write_text(
+            json.dumps({"name": "Imported Project", "config": sample_project.config, "pics": {"clusters": {}}})
+        )
+        mock_sync_apis.projects_api.importproject_config_api_v1_projects_import_post.return_value = sample_project
+
+        with patch("th_cli.commands.project.SyncApis", return_value=mock_sync_apis):
+            result = cli_runner.invoke(project, ["import", "--file", str(import_file)])
+
+        # Assert
+        assert result.exit_code == 0
+        assert f"Project '{sample_project.name}' imported with ID {sample_project.id}" in result.output
+        mock_sync_apis.projects_api.importproject_config_api_v1_projects_import_post.assert_called_once()
+
+    def test_import_project_file_not_found(
+        self,
+        cli_runner: CliRunner,
+        mock_sync_apis: Mock,
+    ) -> None:
+        """Test project import with a non-existent file (Click validates exists=True)."""
+        with patch("th_cli.commands.project.SyncApis", return_value=mock_sync_apis):
+            result = cli_runner.invoke(project, ["import", "--file", "nonexistent.json"])
+
+        assert result.exit_code == 2
+        assert "does not exist" in result.output
+
+    def test_import_project_api_error(
+        self,
+        cli_runner: CliRunner,
+        mock_sync_apis: Mock,
+        sample_project: api_models.Project,
+        temp_dir: Path,
+    ) -> None:
+        """Test project import with API error."""
+        # Arrange
+        import_file = temp_dir / "import.json"
+        import_file.write_text(
+            json.dumps({"name": "Imported Project", "config": sample_project.config, "pics": {"clusters": {}}})
+        )
+        mock_sync_apis.projects_api.importproject_config_api_v1_projects_import_post.side_effect = (
+            UnexpectedResponse(status_code=422, content=b"Unprocessable Entity")
+        )
+
+        with patch("th_cli.commands.project.SyncApis", return_value=mock_sync_apis):
+            result = cli_runner.invoke(project, ["import", "--file", str(import_file)])
+
+        assert result.exit_code == 1
+        assert "422" in result.output
+
+    def test_import_project_passes_file_bytes_to_api(
+        self,
+        cli_runner: CliRunner,
+        mock_sync_apis: Mock,
+        sample_project: api_models.Project,
+        temp_dir: Path,
+    ) -> None:
+        """Test that the import command sends the file bytes to the API correctly."""
+        # Arrange
+        payload = {"name": "Byte Check Project", "config": sample_project.config, "pics": {"clusters": {}}}
+        import_file = temp_dir / "import.json"
+        import_file.write_text(json.dumps(payload))
+        mock_sync_apis.projects_api.importproject_config_api_v1_projects_import_post.return_value = sample_project
+
+        with patch("th_cli.commands.project.SyncApis", return_value=mock_sync_apis):
+            cli_runner.invoke(project, ["import", "--file", str(import_file)])
+
+        call_args = mock_sync_apis.projects_api.importproject_config_api_v1_projects_import_post.call_args
+        body = call_args.kwargs["body"]
+        assert body.import_file == import_file.read_bytes()
+
+    def test_import_project_help_message(self, cli_runner: CliRunner) -> None:
+        """Test the help message for the import command."""
+        result = cli_runner.invoke(project, ["import", "--help"])
+
+        assert result.exit_code == 0
+        assert "--file" in result.output
diff --git a/tests/test_run_tests.py b/tests/test_run_tests.py
index 3761518..1dc400e 100644
--- a/tests/test_run_tests.py
+++ b/tests/test_run_tests.py
@@ -593,7 +593,7 @@ def test_run_tests_logger_configuration(
 
         # Assert
         assert result.exit_code == 0
-        mock_configure_logger.assert_called_once_with(title="Custom Logger Test")
+        mock_configure_logger.assert_called_once_with(title="Custom Logger Test", enable_log_streaming=True)
         assert "Log output in: /path/to/test_logs/custom_run.log" in result.output
 
     def test_run_tests_default_title_generation(
diff --git a/th_cli/commands/project.py b/th_cli/commands/project.py
index 5fe6ed3..d8db990 100644
--- a/th_cli/commands/project.py
+++ b/th_cli/commands/project.py
@@ -15,6 +15,7 @@
 #
 import json
 from contextlib import contextmanager
+from pathlib import Path
 from typing import Any
 
 import click
@@ -22,7 +23,7 @@
 
 from th_cli.api_lib_autogen.api_client import SyncApis
 from th_cli.api_lib_autogen.exceptions import UnexpectedResponse
-from th_cli.api_lib_autogen.models import PICS, Project, ProjectCreate, ProjectUpdate
+from th_cli.api_lib_autogen.models import PICS, BodyImportprojectConfigApiV1ProjectsImportPost, Project, ProjectCreate, ProjectUpdate
 from th_cli.client import get_client
 from th_cli.colorize import (
     colorize_cmd_help,
@@ -215,6 +216,49 @@ def delete(id: int, yes: bool) -> None:
         _delete_project(sync_apis, id)
 
 
+# Click command to export a project config
+@project.command(
+    "export",
+    short_help=colorize_help("Export a project config to a JSON file"),
+)
+@click.option(
+    "--id",
+    "-i",
+    type=int,
+    required=True,
+    help=colorize_help("Project ID to export"),
+)
+@click.option(
+    "--output-file",
+    "-o",
+    type=click.Path(file_okay=True, dir_okay=False),
+    required=False,
+    help=colorize_help("Output JSON file path (defaults to <project-name>-project-config.json)"),
+)
+def export(id: int, output_file: str | None) -> None:
+    """Export a project config to a JSON file"""
+    with get_sync_apis("export") as sync_apis:
+        _export_project(sync_apis, id, output_file)
+
+
+# Click command to import a project config from a JSON file
+@project.command(
+    "import",
+    short_help=colorize_help("Import a project config from a JSON file"),
+)
+@click.option(
+    "--file",
+    "-f",
+    type=click.Path(file_okay=True, dir_okay=False, exists=True),
+    required=True,
+    help=colorize_help("JSON file previously exported with 'project export'"),
+)
+def import_project(file: str) -> None:
+    """Import a project config from a JSON file"""
+    with get_sync_apis("import") as sync_apis:
+        _import_project(sync_apis, file)
+
+
 def _create_project(sync_apis: SyncApis, name: str, config: str | None, pics_config_folder: str | None) -> None:
     """Create a new project"""
     # Get default config
@@ -383,3 +427,41 @@ def _delete_project(sync_apis: SyncApis, id: int) -> None:
         click.echo(colorize_success(f"Project {id} was deleted."))
     except UnexpectedResponse as e:
         handle_api_error(e, f"delete project ID '{id}'")
+
+
+def _export_project(sync_apis: SyncApis, id: int, output_file: str | None) -> None:
+    """Export a project config to a JSON file"""
+    try:
+        project_create: ProjectCreate = sync_apis.projects_api.export_project_config_api_v1_projects__id__export_get(
+            id=id
+        )
+    except UnexpectedResponse as e:
+        handle_api_error(e, f"export project ID '{id}'")
+
+    if not output_file:
+        safe_name = "".join(c if c.isalnum() or c in "-_" else "_" for c in (project_create.name or f"project-{id}"))
+        output_file = f"{safe_name}-project-config.json"
+
+    try:
+        Path(output_file).write_text(project_create.model_dump_json(indent=2))
+        click.echo(colorize_success(f"Project {id} exported to '{output_file}'"))
+    except OSError as e:
+        raise CLIError(f"Failed to write export file '{output_file}': {e}")
+
+
+def _import_project(sync_apis: SyncApis, file: str) -> None:
+    """Import a project config from a JSON file"""
+    try:
+        file_bytes = Path(file).read_bytes()
+    except FileNotFoundError as e:
+        handle_file_error(e, "import file")
+    except OSError as e:
+        raise CLIError(f"Failed to read import file '{file}': {e}")
+
+    body = BodyImportprojectConfigApiV1ProjectsImportPost(import_file=file_bytes)
+
+    try:
+        response: Project = sync_apis.projects_api.importproject_config_api_v1_projects_import_post(body=body)
+        click.echo(colorize_success(f"Project '{response.name}' imported with ID {response.id}"))
+    except UnexpectedResponse as e:
+        handle_api_error(e, f"import project from '{file}'")

From 79cb7472b016139d5e41d78d27dfdd1b2ae17e85 Mon Sep 17 00:00:00 2001
From: Romulo Quidute Filho <116586593+rquidute@users.noreply.github.com>
Date: Tue, 21 Jul 2026 15:11:50 -0300
Subject: [PATCH 6/8] Fix Push AV Stream Verification player reading stale
 field names (#103)

* Fix Push AV Stream Verification player reading stale field names

The Push AV Server's /streams API returns each stream's uploaded
files under valid_uploads/error_uploads (lists of {file_path,
reasons?}) since the server became session-oriented. The CLI's
push_av_stream_verification.html was never updated and still looked
for files/valid_files/invalid_files, which no longer exist in the
response. As a result, allFiles was always empty, no .mpd/.m4s entry
point was ever found, and the video player stayed blank even when
the DUT successfully uploaded CMAF content to the server.

Add getStreamFilePaths() to read valid_uploads/error_uploads first,
falling back to the legacy files/valid_files/invalid_files shape for
compatibility with older server responses. Also surface per-file
non-conforming reasons in the Non-Conforming Files section using the
reasons field now provided by error_uploads entries.

Add regression tests asserting the rendered template references the
current field names ahead of the legacy fallback.

* Apply defensive null-checks to Push AV upload parsing per code review

Use optional chaining (u?.file_path, u?.reasons) and filter(Boolean)
when mapping valid_uploads/error_uploads entries to file paths and
reasons, so a malformed or null entry in the server response can't
throw a TypeError and block the verification page from rendering.

Update the corresponding test assertion to check for the file_path
field name generically instead of the literal 'u.file_path' loop
variable expression, which no longer appears verbatim once optional
chaining is used.
---
 .../camera/test_camera_http_server.py         | 46 +++++++++++++++++++
 .../camera/push_av_stream_verification.html   | 42 ++++++++++++++---
 2 files changed, 82 insertions(+), 6 deletions(-)

diff --git a/tests/test_run/camera/test_camera_http_server.py b/tests/test_run/camera/test_camera_http_server.py
index acaab32..e0d79d0 100644
--- a/tests/test_run/camera/test_camera_http_server.py
+++ b/tests/test_run/camera/test_camera_http_server.py
@@ -293,6 +293,52 @@ def test_do_post_unknown_path_sends_404(self):
         assert handler._error_code == 404
 
 
+# ---------------------------------------------------------------------------
+# VideoStreamingHandler.serve_player - Push AV Stream Verification template
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+class TestServePlayerPushAVTemplate:
+    """Regression tests for issue #1051: the Push AV Server returns each stream's
+    uploaded files under valid_uploads/error_uploads (list of {file_path, reasons?}),
+    not the legacy files/valid_files/invalid_files shape. The rendered template's
+    JS must read the current field names or the video player stays blank even
+    when the DUT has successfully uploaded content."""
+
+    def _render(self):
+        handler = _make_handler(
+            path="/",
+            server_attrs={
+                "prompt_options": {"PASS": 1, "FAIL": 2},
+                "prompt_text": "Verify the video stream",
+                "is_push_av_verification": True,
+                "push_av_server_url": "https://192.168.0.53:1234",
+            },
+        )
+        handler.serve_player()
+        return handler.wfile.getvalue().decode("utf-8")
+
+    def test_renders_without_template_error(self):
+        html_content = self._render()
+        assert "Template error" not in html_content
+        assert "<!DOCTYPE html>" in html_content or "<html>" in html_content
+
+    def test_reads_valid_and_error_uploads_fields(self):
+        html_content = self._render()
+        assert "stream.valid_uploads" in html_content
+        assert "stream.error_uploads" in html_content
+        assert "file_path" in html_content
+
+    def test_no_longer_relies_solely_on_legacy_file_fields(self):
+        """The old field names may still appear as a fallback, but the current
+        server field names must be checked first."""
+        html_content = self._render()
+        valid_uploads_idx = html_content.index("stream.valid_uploads")
+        valid_files_idx = html_content.index("stream.valid_files")
+        assert valid_uploads_idx < valid_files_idx
+
+
 # ---------------------------------------------------------------------------
 # VideoStreamingHandler.handle_response
 # ---------------------------------------------------------------------------
diff --git a/th_cli/test_run/camera/push_av_stream_verification.html b/th_cli/test_run/camera/push_av_stream_verification.html
index 486f719..e2260c2 100644
--- a/th_cli/test_run/camera/push_av_stream_verification.html
+++ b/th_cli/test_run/camera/push_av_stream_verification.html
@@ -526,6 +526,19 @@
             nonConformingSection.style.display = 'none';
         }}
 
+        // Push AV Server returns each stream's uploaded files as valid_uploads/error_uploads,
+        // each entry being an object with a file_path (and reasons, for error_uploads).
+        // Older server responses used plain filename arrays under files/valid_files/invalid_files -
+        // keep supporting those too so this page degrades gracefully against either shape.
+        function getStreamFilePaths(stream) {{
+            if (stream.valid_uploads || stream.error_uploads) {{
+                const validPaths = (stream.valid_uploads || []).map(u => u?.file_path).filter(Boolean);
+                const invalidPaths = (stream.error_uploads || []).map(u => u?.file_path).filter(Boolean);
+                return [...validPaths, ...invalidPaths];
+            }}
+            return stream.files || [...(stream.valid_files || []), ...(stream.invalid_files || [])];
+        }}
+
         function selectStream(index) {{
             if (!streamsData || !streamsData[index]) {{
                 console.error('Stream data not found for index:', index);
@@ -535,8 +548,7 @@
             const stream = streamsData[index];
             selectedStreamId = stream.id || index;
 
-            // Combine valid_files and invalid_files (or use files if present)
-            const allFiles = stream.files || [...(stream.valid_files || []), ...(stream.invalid_files || [])];
+            const allFiles = getStreamFilePaths(stream);
 
             // Update selected styling
             document.querySelectorAll('.stream-item').forEach(item => {{
@@ -582,9 +594,14 @@
             const streamNum = parseInt(stream.id) + 1;
             streamContentsTitle.textContent = `Stream ${{streamNum}} Contents`;
 
-            // Combine valid and invalid files (or use files if present)
-            const validFiles = stream.valid_files || [];
-            const invalidFiles = stream.invalid_files || [];
+            const hasUploadsShape = !!(stream.valid_uploads || stream.error_uploads);
+            const validFiles = hasUploadsShape
+                ? (stream.valid_uploads || []).map(u => u?.file_path).filter(Boolean)
+                : (stream.valid_files || []);
+            const invalidUploads = hasUploadsShape ? (stream.error_uploads || []) : [];
+            const invalidFiles = hasUploadsShape
+                ? invalidUploads.map(u => u?.file_path).filter(Boolean)
+                : (stream.invalid_files || []);
             const allFiles = stream.files || [...validFiles, ...invalidFiles];
 
             // Display files
@@ -611,13 +628,26 @@
 
             // Display conformance status
             if (invalidFiles.length > 0) {{
-                nonConformingContent.innerHTML = `<div style="color: #c62828; text-align: center;">Found ${{invalidFiles.length}} non-conforming file(s)</div>`;
+                const reasons = invalidUploads
+                    .flatMap(u => u?.reasons || [])
+                    .filter(Boolean);
+                const reasonsHtml = reasons.length > 0
+                    ? `<br><small>${{reasons.map(r => html_escape(r)).join('<br>')}}</small>`
+                    : '';
+                nonConformingContent.innerHTML =
+                    `<div style="color: #c62828; text-align: center;">Found ${{invalidFiles.length}} non-conforming file(s)${{reasonsHtml}}</div>`;
             }} else {{
                 nonConformingContent.innerHTML = '<div class="conforming-message">All files conform to Matter Spec.</div>';
             }}
             nonConformingSection.style.display = 'block';
         }}
 
+        function html_escape(str) {{
+            const div = document.createElement('div');
+            div.textContent = str;
+            return div.innerHTML;
+        }}
+
         let currentDashPlayer = null;  // Track current player instance
 
         function playStream(streamUrl) {{

From 0f00720eb897b411263f9a2e4c63722e4d328c8d Mon Sep 17 00:00:00 2001
From: Romulo Quidute Filho <116586593+rquidute@users.noreply.github.com>
Date: Wed, 22 Jul 2026 16:17:57 -0300
Subject: [PATCH 7/8] Don't misreport successful log uploads as errors after
 WebSocket drop (#1062) (#105)

* Stop misreporting successful log uploads as errors after WebSocket drop

Uploading a large manual test log can keep the backend's event loop
busy long enough that the WebSocket's ping/pong keepalive times out
and the connection is dropped before the CLI can send the prompt
response confirming the upload. Previously this was caught by the
generic exception handler in __upload_file_and_send_response and
reported as 'Unexpected error uploading file: ...', even though the
upload itself had already completed successfully (issue #1062).

- Wrap only the prompt-response send (not the upload) in a dedicated
  try/except for websockets.exceptions.ConnectionClosed, and report
  it as a distinct warning that makes clear the file was already
  uploaded, instead of letting it fall into the same 'unexpected
  error' branch as an actual upload failure.
- Add unit tests covering: successful upload + successful response,
  successful upload with the WebSocket closed before the response
  can be sent, and an actual upload failure (still reported as an
  error, as before).

* Address review: catch any exception, not just ConnectionClosed, after successful upload

Only catching websockets.exceptions.ConnectionClosed left other
post-upload notification failures (e.g. websockets.exceptions.
InvalidState, or a plain OSError from a socket already torn down)
to fall through to the outer except Exception block, which still
misreported them as "Unexpected error uploading file" - the exact
bug this fix targets.

Broaden the inner except to Exception, since by this point the
upload has already succeeded and any exception sending the
confirmation is a notification failure, not an upload failure. The
try block scopes exactly one call (_send_prompt_response), so this
isn't a broad catch-all - it matches the actual invariant at this
point in the function.

Remove the now-unused top-level "import websockets" statement and
add a regression test covering a non-ConnectionClosed exception.

* Strip trailing whitespace/CR from uploaded file path input

__prompt_user_for_file_upload read the raw value from aioconsole.ainput()
and only called .strip() when checking for an empty/skip response, then
passed the *unstripped* value to __valid_file_upload() and returned it
unstripped on success. Some terminals/SSH sessions send a trailing \r
(or other whitespace) with the input line; that stray character made
os.path.isfile() fail even though the file existed exactly where the
user said it did, surfacing as a misleading "Invalid file path or
type" error for an otherwise-correct path.

Strip the input once, immediately after reading it, and use the
stripped value consistently for the emptiness check, validation, and
the returned path.
---
 tests/test_run/test_prompt_manager.py | 186 ++++++++++++++++++++++++++
 th_cli/test_run/prompt_manager.py     |  21 ++-
 2 files changed, 204 insertions(+), 3 deletions(-)

diff --git a/tests/test_run/test_prompt_manager.py b/tests/test_run/test_prompt_manager.py
index f860da1..8f923b4 100644
--- a/tests/test_run/test_prompt_manager.py
+++ b/tests/test_run/test_prompt_manager.py
@@ -20,7 +20,9 @@
 import tempfile
 from unittest.mock import AsyncMock, MagicMock, Mock, patch
 
+import httpx
 import pytest
+import websockets
 
 from th_cli.shared_constants import MessageTypeEnum
 from th_cli.test_run import prompt_manager
@@ -375,6 +377,190 @@ async def test_empty_input_skips_upload(self):
         mock_send.assert_called_once()
         assert mock_send.call_args[1]["response"] == ""
 
+    @pytest.mark.asyncio
+    async def test_strips_trailing_whitespace_from_input(self):
+        """A stray trailing \\r or space from the input stream (e.g. some
+        terminals/SSH sessions send CRLF) must not cause a valid, existing
+        file path to be rejected as invalid."""
+        with tempfile.NamedTemporaryFile(suffix=".log", delete=False) as f:
+            f.write(b"hello")
+            tmp_path = f.name
+
+        try:
+            with patch(
+                "th_cli.test_run.prompt_manager.__upload_file_and_send_response",
+                new_callable=AsyncMock,
+            ) as mock_upload:
+                with patch("aioconsole.ainput", new_callable=AsyncMock, return_value=f"{tmp_path}\r"):
+                    with patch("click.echo"):
+                        await prompt_manager.handle_file_upload_request(
+                            socket=AsyncMock(),
+                            request=MagicMock(prompt="Upload file", timeout=30),
+                        )
+
+            mock_upload.assert_called_once()
+            assert mock_upload.call_args[1]["file_path"] == tmp_path
+        finally:
+            os.unlink(tmp_path)
+
+
+# ---------------------------------------------------------------------------
+# __upload_file_and_send_response
+# ---------------------------------------------------------------------------
+# `__upload_file_and_send_response` is a module-level name, so it is NOT
+# name-mangled. It's accessed here via getattr() to avoid writing the literal
+# dunder-prefixed attribute inside a class body, which *would* be mangled.
+
+
+def _get_upload_file_and_send_response():
+    return getattr(prompt_manager, "__upload_file_and_send_response")
+
+
+class _FakeAsyncClient:
+    """Minimal async context-manager stand-in for httpx.AsyncClient."""
+
+    def __init__(self, response=None, post_error=None):
+        self._response = response or MagicMock(status_code=200)
+        self._response.raise_for_status = Mock()
+        self._post_error = post_error
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        return False
+
+    async def post(self, *args, **kwargs):
+        if self._post_error:
+            raise self._post_error
+        return self._response
+
+
+@pytest.mark.unit
+class TestUploadFileAndSendResponse:
+    """Uploading the file and sending the prompt response are two separate
+    network operations. A failure sending the prompt response after a
+    successful upload must not be reported as an upload failure
+    (see GitHub issue #1062)."""
+
+    @pytest.mark.asyncio
+    async def test_success_sends_prompt_response(self):
+        upload_file_and_send_response = _get_upload_file_and_send_response()
+
+        with tempfile.NamedTemporaryFile(suffix=".txt", delete=False) as f:
+            f.write(b"hello")
+            tmp_path = f.name
+
+        try:
+            with patch("th_cli.test_run.prompt_manager._send_prompt_response", new_callable=AsyncMock) as mock_send:
+                with patch("httpx.AsyncClient", return_value=_FakeAsyncClient()):
+                    with patch("click.echo"):
+                        await upload_file_and_send_response(
+                            socket=AsyncMock(),
+                            file_path=tmp_path,
+                            prompt=MagicMock(message_id=1),
+                        )
+
+            mock_send.assert_called_once()
+            assert mock_send.call_args[1]["response"] == "SUCCESS"
+        finally:
+            os.unlink(tmp_path)
+
+    @pytest.mark.asyncio
+    async def test_websocket_closed_after_successful_upload_reports_warning_not_error(self):
+        """If the upload succeeds but the websocket is closed before the
+        confirmation can be sent, this must be surfaced as a warning about the
+        lost confirmation - not as an upload error - since the file was
+        already uploaded successfully."""
+        upload_file_and_send_response = _get_upload_file_and_send_response()
+
+        with tempfile.NamedTemporaryFile(suffix=".txt", delete=False) as f:
+            f.write(b"hello")
+            tmp_path = f.name
+
+        try:
+            with patch(
+                "th_cli.test_run.prompt_manager._send_prompt_response",
+                new_callable=AsyncMock,
+                side_effect=websockets.exceptions.ConnectionClosedError(None, None, None),
+            ):
+                with patch("httpx.AsyncClient", return_value=_FakeAsyncClient()):
+                    with patch("click.echo") as mock_echo:
+                        await upload_file_and_send_response(
+                            socket=AsyncMock(),
+                            file_path=tmp_path,
+                            prompt=MagicMock(message_id=1),
+                        )
+
+            echoed = " ".join(str(call.args[0]) for call in mock_echo.call_args_list)
+            assert "uploaded successfully" in echoed
+            assert "Unexpected error uploading file" not in echoed
+        finally:
+            os.unlink(tmp_path)
+
+    @pytest.mark.asyncio
+    async def test_other_exception_after_successful_upload_reports_warning_not_error(self):
+        """Any exception sending the confirmation (not just ConnectionClosed -
+        e.g. websockets.exceptions.InvalidState, or a plain OSError) must also
+        be reported as a post-upload notification warning, not an upload
+        error, since the upload already succeeded by this point."""
+        upload_file_and_send_response = _get_upload_file_and_send_response()
+
+        with tempfile.NamedTemporaryFile(suffix=".txt", delete=False) as f:
+            f.write(b"hello")
+            tmp_path = f.name
+
+        try:
+            with patch(
+                "th_cli.test_run.prompt_manager._send_prompt_response",
+                new_callable=AsyncMock,
+                side_effect=OSError("socket already closed"),
+            ):
+                with patch("httpx.AsyncClient", return_value=_FakeAsyncClient()):
+                    with patch("click.echo") as mock_echo:
+                        await upload_file_and_send_response(
+                            socket=AsyncMock(),
+                            file_path=tmp_path,
+                            prompt=MagicMock(message_id=1),
+                        )
+
+            echoed = " ".join(str(call.args[0]) for call in mock_echo.call_args_list)
+            assert "uploaded successfully" in echoed
+            assert "confirmation could not be sent" in echoed
+            assert "Unexpected error uploading file" not in echoed
+        finally:
+            os.unlink(tmp_path)
+
+    @pytest.mark.asyncio
+    async def test_http_error_during_upload_still_reports_error(self):
+        """A failure during the actual upload (before success) must still be
+        reported as an upload error, and the empty response must be sent."""
+        upload_file_and_send_response = _get_upload_file_and_send_response()
+
+        with tempfile.NamedTemporaryFile(suffix=".txt", delete=False) as f:
+            f.write(b"hello")
+            tmp_path = f.name
+
+        try:
+            with patch("th_cli.test_run.prompt_manager._send_prompt_response", new_callable=AsyncMock) as mock_send:
+                with patch(
+                    "httpx.AsyncClient",
+                    return_value=_FakeAsyncClient(post_error=httpx.ConnectError("boom")),
+                ):
+                    with patch("click.echo") as mock_echo:
+                        await upload_file_and_send_response(
+                            socket=AsyncMock(),
+                            file_path=tmp_path,
+                            prompt=MagicMock(message_id=1),
+                        )
+
+            mock_send.assert_called_once()
+            assert mock_send.call_args[1]["response"] == ""
+            echoed = " ".join(str(call.args[0]) for call in mock_echo.call_args_list)
+            assert "Network error during file upload" in echoed
+        finally:
+            os.unlink(tmp_path)
+
 
 # ---------------------------------------------------------------------------
 # _handle_two_way_talk_prompt (via handle_prompt dispatch)
diff --git a/th_cli/test_run/prompt_manager.py b/th_cli/test_run/prompt_manager.py
index e2150dc..1e28540 100644
--- a/th_cli/test_run/prompt_manager.py
+++ b/th_cli/test_run/prompt_manager.py
@@ -480,10 +480,10 @@ async def __prompt_user_for_file_upload(prompt: PromptRequest) -> str:
         click.echo("Enter the path to the file to upload (or press Enter to skip): ")
 
         # Wait for input async
-        file_path = await aioconsole.ainput()
+        file_path = (await aioconsole.ainput()).strip()
 
         # If user just pressed Enter, return empty string
-        if not file_path.strip():
+        if not file_path:
             return ""
 
         # Validate file path and type
@@ -531,7 +531,22 @@ async def __upload_file_and_send_response(
 
                 response.raise_for_status()
                 click.echo("✅ File uploaded successfully")
-                await _send_prompt_response(socket=socket, response="SUCCESS", prompt=prompt)
+
+        # The upload itself succeeded at this point (the HTTP response was already
+        # received above). Uploading a large log can keep the backend's event loop
+        # busy long enough that the WebSocket's keepalive ping/pong times out and
+        # the connection is dropped before we get a chance to send the prompt
+        # response. Any failure sending that response is therefore a post-upload
+        # notification failure, not an upload failure - report it separately so
+        # it isn't mistaken for one (see GitHub issue #1062).
+        try:
+            await _send_prompt_response(socket=socket, response="SUCCESS", prompt=prompt)
+        except Exception as e:
+            click.echo(
+                "⚠️  File was uploaded successfully, but the confirmation could not be sent "
+                f"to the backend: {e}",
+                err=True,
+            )
 
     except httpx.RequestError as e:
         click.echo(f"❌ Network error during file upload: {str(e)}", err=True)

From bf4969409f08f3a8cd11a326b845666e944bdaa9 Mon Sep 17 00:00:00 2001
From: antonio-amjr <116589331+antonio-amjr@users.noreply.github.com>
Date: Fri, 14 Aug 2026 16:50:32 -0300
Subject: [PATCH 8/8] [Fix] Websocket and Log Viewer (#107)

* Max retained logs added for the CLI log viewer.

Also, the websocket closure was postponed for when inactive and now yields to the event loop every 200 records intead of whole batch

* Cap the rendering to 2000 lines and changed log viewer download logs feature

* Log viewer download button now opens no tab and start the download immediately

* Pushing the run_id to the queue that feeds the live stream

* Fixing state verifying to match the backends.
---
 tests/test_run/test_websocket_socket.py |  58 +++++++--
 th_cli/commands/run_tests.py            |   1 +
 th_cli/test_run/log_stream_handler.py   |  52 +++++---
 th_cli/test_run/log_viewer.html         | 162 +++++++++++++-----------
 th_cli/test_run/logging.py              |  13 +-
 th_cli/test_run/logs_http_server.py     |  94 +++++++-------
 th_cli/test_run/websocket.py            |  76 ++++++++---
 7 files changed, 284 insertions(+), 172 deletions(-)

diff --git a/tests/test_run/test_websocket_socket.py b/tests/test_run/test_websocket_socket.py
index daf531c..324b60f 100644
--- a/tests/test_run/test_websocket_socket.py
+++ b/tests/test_run/test_websocket_socket.py
@@ -28,7 +28,14 @@
     TestSuiteExecution,
     TestSuiteMetadata,
 )
-from th_cli.test_run.socket_schemas import TestCaseUpdate, TestRunUpdate, TestStepUpdate, TestSuiteUpdate, TestUpdate
+from th_cli.test_run.socket_schemas import (
+    TestCaseUpdate,
+    TestLogRecord,
+    TestRunUpdate,
+    TestStepUpdate,
+    TestSuiteUpdate,
+    TestUpdate,
+)
 from th_cli.test_run.websocket import TestRunSocket
 
 # ---------------------------------------------------------------------------
@@ -304,7 +311,7 @@ async def test_step_update_routed_correctly(self):
             ),
         )
         with patch.object(s, "_TestRunSocket__log_test_step_update") as mock_fn:
-            await s._TestRunSocket__handle_test_update(socket=AsyncMock(), update=update)
+            await s._TestRunSocket__handle_test_update(update=update)
 
         mock_fn.assert_called_once()
 
@@ -319,7 +326,7 @@ async def test_case_update_routed_correctly(self):
             body=TestCaseUpdate(state="passed", test_case_execution_index=0, test_suite_execution_index=0),
         )
         with patch.object(s, "_TestRunSocket__log_test_case_update") as mock_fn:
-            await s._TestRunSocket__handle_test_update(socket=AsyncMock(), update=update)
+            await s._TestRunSocket__handle_test_update(update=update)
 
         mock_fn.assert_called_once()
 
@@ -333,28 +340,55 @@ async def test_suite_update_routed_correctly(self):
             body=TestSuiteUpdate(state="passed", test_suite_execution_index=0),
         )
         with patch.object(s, "_TestRunSocket__log_test_suite_update") as mock_fn:
-            await s._TestRunSocket__handle_test_update(socket=AsyncMock(), update=update)
+            await s._TestRunSocket__handle_test_update(update=update)
 
         mock_fn.assert_called_once()
 
     @pytest.mark.asyncio
-    async def test_run_update_executing_does_not_close_socket(self):
+    async def test_run_update_executing_leaves_run_not_finished(self):
         s = _make_socket()
-        mock_socket = AsyncMock()
 
         update = TestUpdate(test_type="test_run", body=TestRunUpdate(state="executing", test_run_execution_id=1))
         with patch.object(s, "_TestRunSocket__log_test_run_update", new_callable=AsyncMock):
-            await s._TestRunSocket__handle_test_update(socket=mock_socket, update=update)
+            await s._TestRunSocket__handle_test_update(update=update)
 
-        mock_socket.close.assert_not_called()
+        assert s._run_finished is False
 
     @pytest.mark.asyncio
-    async def test_run_update_non_executing_closes_socket(self):
+    async def test_run_update_non_executing_marks_run_finished(self):
         s = _make_socket()
-        mock_socket = AsyncMock()
 
         update = TestUpdate(test_type="test_run", body=TestRunUpdate(state="passed", test_run_execution_id=1))
         with patch.object(s, "_TestRunSocket__log_test_run_update", new_callable=AsyncMock):
-            await s._TestRunSocket__handle_test_update(socket=mock_socket, update=update)
+            await s._TestRunSocket__handle_test_update(update=update)
+
+        assert s._run_finished is True
+
+    @pytest.mark.asyncio
+    async def test_run_update_pending_leaves_run_not_finished(self):
+        # Regression test: "pending" is non-terminal (backend's TestRun.completed()
+        # excludes both PENDING and EXECUTING), so it must not close the socket.
+        # A prior implementation used a negation check (`state != "executing"`)
+        # that misclassified any non-"executing" state, including "pending", as
+        # terminal.
+        s = _make_socket()
+
+        update = TestUpdate(test_type="test_run", body=TestRunUpdate(state="pending", test_run_execution_id=1))
+        with patch.object(s, "_TestRunSocket__log_test_run_update", new_callable=AsyncMock):
+            await s._TestRunSocket__handle_test_update(update=update)
+
+        assert s._run_finished is False
+
+    @pytest.mark.asyncio
+    async def test_handle_log_record_logs_every_record(self):
+        s = _make_socket()
+        records = [
+            TestLogRecord(level="INFO", timestamp=0.0, message=f"msg{i}") for i in range(3)
+        ]
+
+        with patch("th_cli.test_run.websocket.logger") as mock_logger:
+            await s._TestRunSocket__handle_log_record(records)
 
-        mock_socket.close.assert_called_once()
+        assert mock_logger.log.call_count == 3
+        for record in records:
+            mock_logger.log.assert_any_call(record.level, record.message)
diff --git a/th_cli/commands/run_tests.py b/th_cli/commands/run_tests.py
index 6b7532a..beeac27 100644
--- a/th_cli/commands/run_tests.py
+++ b/th_cli/commands/run_tests.py
@@ -224,6 +224,7 @@ async def run_tests(
             execution_pics=execution_pics,
             project_id=project_id,
         )
+        test_logging.set_download_run_id(new_test_run.id)
         if _contains_webrtc_two_way_talk(selected_tests_dict):
             _webrtc_handler = TwoWayTalkHandler(port=8999)
             _webrtc_handler.start_waiting()
diff --git a/th_cli/test_run/log_stream_handler.py b/th_cli/test_run/log_stream_handler.py
index 0c56aca..dc1cd67 100644
--- a/th_cli/test_run/log_stream_handler.py
+++ b/th_cli/test_run/log_stream_handler.py
@@ -28,7 +28,7 @@ class LogStreamHandler:
 
     def __init__(self, port: int = 8998):
         """Initialize the log stream handler.
-        
+
         Args:
             port: Port number for the HTTP server (default: 8998)
         """
@@ -36,48 +36,64 @@ def __init__(self, port: int = 8998):
         self.http_server = LogsHTTPServer(port=port)
         self.log_queue: queue.Queue = queue.Queue(maxsize=1000)
         self.is_running = False
-        self.log_file_path: Optional[str] = None
-        
-    def start(self, test_run_title: str = "Test Execution", log_file_path: Optional[str] = None) -> str:
+
+    def start(self, test_run_title: str = "Test Execution") -> str:
         """Start the log streaming HTTP server.
-        
+
         Args:
             test_run_title: Title of the test run for display
-            log_file_path: Path to the log file for download functionality
-            
+
         Returns:
             URL where logs can be viewed
         """
         if self.is_running:
             logger.warning("Log stream handler already running")
             return self._get_log_viewer_url()
-        
+
         try:
-            # Store log file path for download functionality
-            self.log_file_path = log_file_path
-            
             # Get local IP address
             local_ip = self._get_local_ip()
-            
+
             # Start HTTP server
             self.http_server.start(
                 log_queue=self.log_queue,
                 test_run_title=test_run_title,
                 local_ip=local_ip,
-                log_file_path=log_file_path,
             )
-            
+
             self.is_running = True
-            
+
             viewer_url = f"http://{local_ip}:{self.port}"
             logger.info(f"Log stream viewer started: {viewer_url}")
-            
+
             return viewer_url
-            
+
         except Exception as e:
             logger.error(f"Failed to start log stream handler: {e}")
             raise
-    
+
+    def set_run_id(self, run_id: int) -> None:
+        """Tell the HTTP server which run's log to link "Download Logs" to,
+        once the run has been created (its id isn't known when the server
+        starts).
+        """
+        if not self.is_running:
+            return
+
+        self.http_server.set_run_id(run_id)
+
+        # A viewer may already be connected (the run_id is typically set
+        # only *after* the viewer URL was printed and likely opened), so
+        # also push it through the existing SSE stream as a control message
+        # - a future/refreshed page load will pick it up from the HTTP
+        # server attribute above, but an already-open one only sees this.
+        try:
+            self.log_queue.put_nowait({"__event__": "run_id", "run_id": run_id})
+        except queue.Full:
+            # Best-effort: a future page load/refresh will still pick up
+            # the run id via the HTTP server attribute set above.
+            pass
+
     def stop(self):
         """Stop the log streaming HTTP server."""
         if not self.is_running:
diff --git a/th_cli/test_run/log_viewer.html b/th_cli/test_run/log_viewer.html
index 4e38ca6..718b45e 100644
--- a/th_cli/test_run/log_viewer.html
+++ b/th_cli/test_run/log_viewer.html
@@ -184,6 +184,8 @@
             cursor: pointer;
             transition: all 0.2s;
             font-weight: 500;
+            display: inline-block;
+            text-decoration: none;
         }}
 
         .btn:hover {{
@@ -496,7 +498,7 @@
                     <div class="control-group">
                         <button id="clearBtn" class="btn" onclick="clearLogs()">Clear</button>
                         <button id="autoScrollBtn" class="btn active" onclick="toggleAutoScroll()">Auto-scroll</button>
-                        <button id="downloadBtn" class="btn download" onclick="downloadLogs()">Download Logs</button>
+                        <a id="downloadBtn" class="btn download" href="#" onclick="return false;" title="Available once the run starts" style="opacity:0.5;cursor:default;">Download Logs</a>
                         <input type="text" id="searchBox" class="search-box" placeholder="Search logs..." oninput="filterLogs()">
                         <span class="log-count">Logs: <span id="logCount">0</span></span>
                     </div>
@@ -522,6 +524,18 @@
     </div>
 
     <script>
+        // Injected server-side: the run's id (or null if the run hasn't been
+        // created yet - reassigned later via the 'run_id' SSE event below if
+        // it arrives after this page has already loaded, which is the
+        // common case: the viewer URL is printed and typically opened
+        // before the run is created) and the backend's configured hostname
+        // (or null if it was just "localhost"/"127.0.0.1" - meaningless
+        // once embedded in a page that may be opened from a different
+        // device than the one running the CLI). See updateDownloadLink()
+        // below.
+        let RUN_ID = {run_id};
+        const BACKEND_HOST = {backend_host};
+
         let eventSource = null;
         let autoScroll = true;
         let logCount = 0;
@@ -532,29 +546,59 @@
         let lastBatchTime = 0;
         const BATCH_INTERVAL_MS = 50;
         const MAX_BATCH_SIZE = 50;
+        // Cap how many entries are kept in memory/rendered in the DOM. A run
+        // can produce hundreds of thousands of log lines; retaining all of
+        // them here (unbounded array + DOM nodes) is what freezes the tab.
+        // The "Download Logs" button reads the full file from disk directly,
+        // so it isn't affected by this cap.
+        const MAX_RETAINED_LOGS = 5000;
+        // Cap how many entries can sit unrendered in the queue. Without this,
+        // a fast burst (hundreds of thousands of lines) makes the queue grow
+        // into a multi-minute backlog: the view still eventually renders
+        // everything, but always shows stale content instead of what's
+        // happening right now - as bad as no live view at all for reading
+        // context to answer a prompt while a test is running. Dropping the
+        // oldest not-yet-rendered entries keeps the view within a few
+        // seconds of real-time, at the cost of some historical entries never
+        // appearing live during a burst (the full history is unaffected -
+        // it's still in the saved log file and via "Download Logs").
+        const MAX_PENDING_QUEUE = 2000;
 
         function connectToLogStream() {{
             const statusIndicator = document.getElementById('statusIndicator');
             const statusText = document.getElementById('statusText');
-            
+
             eventSource = new EventSource('/api/logs/stream');
-            
+
             eventSource.addEventListener('connected', function(e) {{
                 console.log('Connected to log stream');
                 statusIndicator.className = 'status-indicator connected';
                 statusText.textContent = 'Connected';
             }});
-            
+
+            eventSource.addEventListener('run_id', function(e) {{
+                // Arrives once the run is created, which is typically after
+                // this page has already loaded (RUN_ID was baked in as null
+                // at that point) - re-resolve the download link now that
+                // it's known, without requiring a page reload.
+                const data = JSON.parse(e.data);
+                RUN_ID = data.run_id;
+                updateDownloadLink();
+            }});
+
             eventSource.addEventListener('log', function(e) {{
                 const logEntry = JSON.parse(e.data);
                 logBatchQueue.push(logEntry);
+                if (logBatchQueue.length > MAX_PENDING_QUEUE) {{
+                    logBatchQueue.splice(0, logBatchQueue.length - MAX_PENDING_QUEUE);
+                }}
                 scheduleBatchProcessing();
             }});
-            
+
             eventSource.addEventListener('keepalive', function(e) {{
                 // Silent keepalive
             }});
-            
+
             eventSource.addEventListener('end', function(e) {{
                 console.log('Log stream ended');
                 statusIndicator.className = 'status-indicator disconnected';
@@ -616,17 +660,30 @@
             const fragment = document.createDocumentFragment();
             const batchSize = Math.min(logBatchQueue.length, MAX_BATCH_SIZE);
             const batch = logBatchQueue.splice(0, batchSize);
-            
+
             batch.forEach(entry => {{
                 allLogs.push(entry);
                 logCount++;
-                
+
                 const logDiv = createLogElement(entry);
                 fragment.appendChild(logDiv);
             }});
-            
+
             container.appendChild(fragment);
-            
+
+            // Trim oldest entries once past the retention cap, so memory and
+            // DOM size stay bounded regardless of total run volume.
+            if (allLogs.length > MAX_RETAINED_LOGS) {{
+                const excess = allLogs.length - MAX_RETAINED_LOGS;
+                allLogs.splice(0, excess);
+                for (let i = 0; i < excess; i++) {{
+                    const oldest = container.firstElementChild;
+                    if (oldest) {{
+                        container.removeChild(oldest);
+                    }}
+                }}
+            }}
+
             document.getElementById('logCount').textContent = logCount;
             
             if (autoScroll) {{
@@ -727,69 +784,6 @@
             }});
         }}
 
-        function downloadLogs() {{
-            // First try server download (if server is still running)
-            fetch('/download_logs')
-                .then(response => {{
-                    if (response.ok) {{
-                        return response.blob();
-                    }}
-                    throw new Error('Server not available');
-                }})
-                .then(blob => {{
-                    // Server download successful
-                    const url = window.URL.createObjectURL(blob);
-                    const a = document.createElement('a');
-                    a.href = url;
-                    a.download = 'test_run_logs.log';
-                    document.body.appendChild(a);
-                    a.click();
-                    window.URL.revokeObjectURL(url);
-                    document.body.removeChild(a);
-                }})
-                .catch(error => {{
-                    // Server not available, use client-side download
-                    console.log('Server unavailable, using client-side download');
-                    downloadLogsClientSide();
-                }});
-        }}
-
-        function downloadLogsClientSide() {{
-            // Build log content from stored logs
-            let logContent = '';
-            allLogs.forEach(entry => {{
-                const timestamp = entry.timestamp || new Date().toISOString();
-                const level = entry.level || 'INFO';
-                const message = entry.message || '';
-                // Replace literal \n strings with actual newlines, then add entry
-                const cleanMessage = message.replace(/\\n/g, '\n');
-                logContent += `${{timestamp}} [${{level}}] ${{cleanMessage}}\n`;
-            }});
-
-            if (logContent === '') {{
-                alert('No logs to download');
-                return;
-            }}
-
-            // Create blob and download
-            const blob = new Blob([logContent], {{ type: 'text/plain;charset=utf-8' }});
-            const url = window.URL.createObjectURL(blob);
-            const a = document.createElement('a');
-            a.href = url;
-            
-            // Generate filename with current timestamp
-            const now = new Date();
-            const dateStr = now.toISOString().slice(0,19).replace(/[T:]/g, '-');
-            a.download = `test_run_logs_${{dateStr}}.log`;
-            
-            document.body.appendChild(a);
-            a.click();
-            window.URL.revokeObjectURL(url);
-            document.body.removeChild(a);
-            
-            console.log(`Downloaded ${{allLogs.length}} log entries client-side`);
-        }}
-
         function escapeHtml(text) {{
             const div = document.createElement('div');
             div.textContent = text;
@@ -813,7 +807,29 @@
             }}
         }});
 
+        function updateDownloadLink() {{
+            if (RUN_ID === null) {{
+                return;
+            }}
+            // Prefer the backend's own configured hostname when it's a real
+            // address; otherwise fall back to whatever host this page was
+            // actually loaded from (correct whenever the CLI and backend
+            // run on the same machine, which is the common case - see the
+            // comment on BACKEND_HOST above).
+            const host = BACKEND_HOST || window.location.hostname;
+            const btn = document.getElementById('downloadBtn');
+            // download=true tells the backend to send Content-Disposition:
+            // attachment, so the browser downloads the file directly
+            // instead of just rendering the raw log text in the tab.
+            btn.href = `${{window.location.protocol}}//${{host}}/api/v1/test_run_executions/${{RUN_ID}}/log?download=true`;
+            btn.removeAttribute('onclick');
+            btn.title = '';
+            btn.style.opacity = '';
+            btn.style.cursor = '';
+        }}
+
         window.addEventListener('load', function() {{
+            updateDownloadLink();
             connectToLogStream();
         }});
 
diff --git a/th_cli/test_run/logging.py b/th_cli/test_run/logging.py
index 05fdcd6..4d7bdbc 100644
--- a/th_cli/test_run/logging.py
+++ b/th_cli/test_run/logging.py
@@ -62,7 +62,7 @@ def configure_logger_for_run(title: str, enable_log_streaming: bool = False) ->
             from th_cli.test_run.log_stream_handler import LogStreamHandler
 
             _log_stream_handler = LogStreamHandler(port=8998)
-            viewer_url = _log_stream_handler.start(test_run_title=title, log_file_path=log_path)
+            viewer_url = _log_stream_handler.start(test_run_title=title)
             # Add custom sink that forwards logs to the stream handler
             def stream_sink(message):
                 """Custom sink that forwards logs to the HTTP stream."""
@@ -91,7 +91,7 @@ def stream_sink(message):
 def stop_log_streaming():
     """Stop the log streaming server if it's running."""
     global _log_stream_handler
-    
+
     if _log_stream_handler:
         try:
             _log_stream_handler.stop()
@@ -102,6 +102,15 @@ def stop_log_streaming():
             _log_stream_handler = None
 
 
+def set_download_run_id(run_id: int) -> None:
+    """Tell the log viewer which run's log to link the "Download Logs" button
+    to, once the run has been created and its id is known (the log-streaming
+    server starts before the run exists, so this can't be known up front).
+    """
+    if _log_stream_handler:
+        _log_stream_handler.set_run_id(run_id)
+
+
 def get_log_stream_url() -> Optional[str]:
     """Get the URL for the log viewer if streaming is enabled.
     
diff --git a/th_cli/test_run/logs_http_server.py b/th_cli/test_run/logs_http_server.py
index 3a14027..da52907 100644
--- a/th_cli/test_run/logs_http_server.py
+++ b/th_cli/test_run/logs_http_server.py
@@ -24,10 +24,11 @@
 
 from loguru import logger
 
+from th_cli.config import config
+
 # HTTP Endpoints
 ENDPOINT_ROOT = "/"
 ENDPOINT_LOGS_STREAM = "/api/logs/stream"
-ENDPOINT_DOWNLOAD_LOGS = "/download_logs"
 
 
 class LogStreamingHandler(BaseHTTPRequestHandler):
@@ -39,51 +40,10 @@ def do_GET(self):
             self.serve_log_viewer()
         elif self.path == ENDPOINT_LOGS_STREAM:
             self.stream_logs()
-        elif self.path == ENDPOINT_DOWNLOAD_LOGS:
-            self.download_logs()
         else:
             logger.warning(f"404 for GET {self.path}")
             self.send_error(404)
     
-    def download_logs(self):
-        """Serve the log file for download using chunked streaming."""
-        log_file_path = getattr(self.server, "log_file_path", None)
-        
-        if not log_file_path or not Path(log_file_path).exists():
-            self.send_error(404, "Log file not found")
-            return
-        
-        try:
-            file_path = Path(log_file_path)
-            filename = file_path.name
-            file_size = file_path.stat().st_size
-            
-            # Send headers
-            self.send_response(200)
-            self.send_header("Content-Type", "text/plain; charset=utf-8")
-            self.send_header("Content-Disposition", f'attachment; filename="{filename}"')
-            self.send_header("Content-Length", str(file_size))
-            self.send_header("Access-Control-Allow-Origin", "*")
-            self.end_headers()
-            
-            # Stream file in chunks to avoid loading entire file into memory
-            CHUNK_SIZE = 65536  # 64KB chunks
-            bytes_sent = 0
-
-            with open(log_file_path, 'rb') as f:
-                while chunk := f.read(CHUNK_SIZE):
-                    self.wfile.write(chunk)
-                    bytes_sent += len(chunk)
-
-            logger.info(f"Log file downloaded: {filename} ({bytes_sent} bytes)")
-            
-        except (BrokenPipeError, ConnectionResetError, ConnectionAbortedError):
-            # Client disconnected during download - normal, not an error
-            logger.debug("Client disconnected during log file download")
-        except Exception as e:
-            logger.error(f"Error serving log file: {e}")
-            # Note: Can't send error response because headers were already sent
-
     def stream_logs(self):
         """Stream logs using Server-Sent Events (SSE)."""
         logger.info("Client connected for log stream")
@@ -116,20 +76,30 @@ def stream_logs(self):
                 try:
                     # Get log entry from queue with timeout
                     log_entry = log_queue.get(timeout=1.0)
-                    
+
                     if log_entry is None:  # Signal to stop
                         logger.info("Received end-of-stream signal for logs")
                         self._send_sse_event("end", {"message": "Log stream ended"})
                         break
 
+                    if isinstance(log_entry, dict) and log_entry.get("__event__") == "run_id":
+                        # Control message, not a log line - lets an already-
+                        # connected viewer pick up the run id once it's
+                        # known, instead of only a fresh page load.
+                        if not self._send_sse_event("run_id", {"run_id": log_entry["run_id"]}):
+                            logger.debug("Client disconnected while streaming")
+                            client_disconnected = True
+                            break
+                        continue
+
                     # Send log entry as SSE event
                     if not self._send_sse_event("log", log_entry):
                         logger.debug("Client disconnected while streaming")
                         client_disconnected = True
                         break
-                        
+
                     sent_count += 1
-                    
+
                     if sent_count % 100 == 0:
                         logger.debug(f"Sent {sent_count} log entries to client")
 
@@ -173,7 +143,22 @@ def serve_log_viewer(self):
         """Serve the log viewer HTML page."""
         # Get configuration from server
         test_run_title = getattr(self.server, "test_run_title", "Test Execution")
-        
+        run_id = getattr(self.server, "run_id", None)
+
+        # config.hostname is only meaningful to the download link when it's a
+        # real, routable address. This page can be opened from a different
+        # device than the one running the CLI (that's why this server binds
+        # to the LAN IP in the first place) - if config.hostname is just
+        # "localhost" (the common case when the CLI and backend run on the
+        # same machine as each other), embedding it here would tell a remote
+        # browser to download from *itself*. Leave it unset in that case so
+        # the page falls back to whatever host the browser actually used to
+        # reach it (correct whenever the CLI and backend share a machine,
+        # which is the common case); keep it when it's a real configured
+        # address (correct when the CLI talks to a genuinely separate
+        # backend host).
+        backend_host = None if config.hostname in ("localhost", "127.0.0.1") else config.hostname
+
         # Read HTML template from file
         try:
             template_path = Path(__file__).parent / "log_viewer.html"
@@ -182,7 +167,9 @@ def serve_log_viewer(self):
 
             # Replace placeholders
             html_content = html_template.format(
-                test_run_title=html.escape(test_run_title)
+                test_run_title=html.escape(test_run_title),
+                run_id=json.dumps(run_id),
+                backend_host=json.dumps(backend_host),
             )
         except Exception as e:
             logger.error(f"Failed to load HTML template: {e}")
@@ -231,15 +218,13 @@ def start(
         log_queue: queue.Queue,
         test_run_title: str = "Test Execution",
         local_ip: Optional[str] = None,
-        log_file_path: Optional[str] = None,
     ):
         """Start HTTP server for log streaming.
-        
+
         Args:
             log_queue: Queue containing log entries to stream
             test_run_title: Title of the test run for display
             local_ip: Local IP address for display (defaults to localhost)
-            log_file_path: Path to log file for download functionality
         """
         try:
             # Use ThreadingHTTPServer for better concurrency
@@ -250,7 +235,7 @@ def start(
             self.server.log_queue = log_queue
             self.server.test_run_title = test_run_title
             self.server.local_ip = local_ip or "localhost"
-            self.server.log_file_path = log_file_path
+            self.server.run_id = None
 
             logger.info(f"Logs HTTP server configured for test run: {test_run_title}")
 
@@ -269,6 +254,13 @@ def run_server():
             logger.error(f"Failed to start logs HTTP server: {e}")
             raise
 
+    def set_run_id(self, run_id: int) -> None:
+        """Set the run id the "Download Logs" link should point to, once the
+        run has been created (it doesn't exist yet when the server starts).
+        """
+        if self.server is not None:
+            self.server.run_id = run_id
+
     def stop(self):
         """Stop HTTP server."""
         if self.server:
diff --git a/th_cli/test_run/websocket.py b/th_cli/test_run/websocket.py
index e60da91..e946814 100644
--- a/th_cli/test_run/websocket.py
+++ b/th_cli/test_run/websocket.py
@@ -13,6 +13,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+import asyncio
+
 import click
 import websockets
 from loguru import logger
@@ -37,7 +39,7 @@
     colorize_state,
 )
 from th_cli.config import config
-from th_cli.shared_constants import MessageTypeEnum
+from th_cli.shared_constants import MessageTypeEnum, TestStateEnum
 
 from .prompt_manager import handle_file_upload_request, handle_prompt
 from .socket_schemas import (
@@ -56,6 +58,25 @@
 
 WEBSOCKET_MAX_MESSAGE_SIZE = 32 * 1024 * 1024  # 32MB
 
+# After the test run reaches a terminal state, the backend may still have a
+# trailing batch of log records queued/in-flight (it flushes and broadcasts
+# any pending log entries *after* sending the terminal state update - see
+# TestLogHandler.finish()/TestUIObserver.complete_tasks() on the backend).
+# Keep draining for a short grace period instead of closing immediately, so
+# that trailing batch isn't dropped by a socket we already hung up on.
+DRAIN_TIMEOUT_S = 5.0
+
+# Yield to the event loop every N log records while processing one batch, so
+# a very large batch doesn't block the websocket read loop for its entire
+# duration.
+LOG_RECORD_YIELD_INTERVAL = 200
+
+# TestRun states that are not yet finished, mirroring the backend's own
+# TestRun.completed() contract (state not in [PENDING, EXECUTING]). Anything
+# else is terminal - checked explicitly rather than negating "executing" so
+# this can't misclassify a non-terminal state (e.g. PENDING) as terminal.
+NON_TERMINAL_RUN_STATES = (TestStateEnum.PENDING, TestStateEnum.EXECUTING)
+
 
 class TestRunSocket:
     def __init__(
@@ -68,6 +89,7 @@ def __init__(
         self.project_config_dict = project_config_dict or {}
         self.two_way_talk_handler = two_way_talk_handler
         self._chip_server_info_displayed = False
+        self._run_finished = False
         # Track test step errors for logging
         # Key: (suite_index, case_index), Value: list of error strings from all steps
         self.test_case_step_errors: dict[tuple[int, int], list[str]] = {}
@@ -85,9 +107,19 @@ async def connect_websocket(self) -> None:
                 try:
                     while True:
                         try:
-                            message = await socket.recv()
+                            if self._run_finished:
+                                # Drain any trailing messages for a short grace
+                                # period instead of closing the instant the
+                                # terminal state update arrives.
+                                message = await asyncio.wait_for(socket.recv(), timeout=DRAIN_TIMEOUT_S)
+                            else:
+                                message = await socket.recv()
                         except websockets.exceptions.ConnectionClosedOK:
                             break
+                        except asyncio.TimeoutError:
+                            # No more trailing messages arrived during the
+                            # drain grace period - safe to close now.
+                            break
 
                         # skip messages that are bytes, as we're expecting a string.\
                         if not isinstance(message, str):
@@ -103,7 +135,13 @@ async def connect_websocket(self) -> None:
                             click.echo(colorize_error(f"Received invalid socket message: {message}"), err=True)
                             click.echo(colorize_error(e.json()), err=True)
                 finally:
-                    pass  # Cleanup if needed
+                    if self._run_finished:
+                        try:
+                            await socket.close()
+                        except websockets.exceptions.ConnectionClosedError:
+                            # Backend closed connection without completing handshake
+                            # This is acceptable as test run completed successfully
+                            pass
         except websockets.exceptions.ConnectionClosed:
             # Handle case where backend doesn't complete close handshake properly
             # This can happen with long-running test executions
@@ -112,7 +150,7 @@ async def connect_websocket(self) -> None:
 
     async def __handle_incoming_socket_message(self, socket: WebSocketClientProtocol, message: SocketMessage) -> None:
         if isinstance(message.payload, TestUpdate):
-            await self.__handle_test_update(socket=socket, update=message.payload)
+            await self.__handle_test_update(update=message.payload)
         elif isinstance(message.payload, PromptRequest):
             # Debug: log the message type
             logger.debug(f"Received prompt with type: {message.type}")
@@ -129,7 +167,7 @@ async def __handle_incoming_socket_message(self, socket: WebSocketClientProtocol
                     two_way_talk_handler=self.two_way_talk_handler,
                 )
         elif message.type == MessageTypeEnum.TEST_LOG_RECORDS and isinstance(message.payload, list):
-            self.__handle_log_record(message.payload)
+            await self.__handle_log_record(message.payload)
         elif isinstance(message.payload, TimeOutNotification):
             # ignore time_out_notification as we handle timeout our selves
             pass
@@ -139,7 +177,7 @@ async def __handle_incoming_socket_message(self, socket: WebSocketClientProtocol
                 err=True,
             )
 
-    async def __handle_test_update(self, socket: WebSocketClientProtocol, update: TestUpdate) -> None:
+    async def __handle_test_update(self, update: TestUpdate) -> None:
         if isinstance(update.body, TestStepUpdate):
             self.__log_test_step_update(update.body)
         elif isinstance(update.body, TestCaseUpdate):
@@ -148,14 +186,13 @@ async def __handle_test_update(self, socket: WebSocketClientProtocol, update: Te
             self.__log_test_suite_update(update.body)
         elif isinstance(update.body, TestRunUpdate):
             await self.__log_test_run_update(update.body)
-            if update.body.state != "executing":
-                # Test run ended disconnect.
-                try:
-                    await socket.close()
-                except websockets.exceptions.ConnectionClosedError:
-                    # Backend closed connection without completing handshake
-                    # This is acceptable as test run completed successfully
-                    pass
+            if update.body.state not in NON_TERMINAL_RUN_STATES:
+                # Test run ended. Don't close immediately - the backend may
+                # still be flushing/broadcasting a trailing batch of log
+                # entries after this message; let the read loop keep
+                # draining for a short grace period (see DRAIN_TIMEOUT_S)
+                # before actually closing.
+                self._run_finished = True
 
     async def __log_test_run_update(self, update: TestRunUpdate) -> None:
         # Display CHIP server info when test run starts executing (SDK container already running)
@@ -284,9 +321,16 @@ def __log_test_step_update(self, update: TestStepUpdate) -> None:
             self.test_case_step_errors.setdefault(case_key, []).extend(update.errors)
             logger.debug(f"Tracked {len(update.errors)} error(s) for test case {case_key}: {update.errors}")
 
-    def __handle_log_record(self, records: list[TestLogRecord]) -> None:
-        for record in records:
+    async def __handle_log_record(self, records: list[TestLogRecord]) -> None:
+        # Batches can contain tens of thousands of entries after a large test
+        # case run. Yield periodically instead of logging the whole batch in
+        # one uninterrupted stretch, so the websocket read loop (and any
+        # other pending work, e.g. prompt handling) doesn't stall for the
+        # entire duration of processing one message.
+        for i, record in enumerate(records):
             logger.log(record.level, record.message)
+            if (i + 1) % LOG_RECORD_YIELD_INTERVAL == 0:
+                await asyncio.sleep(0)
 
     def __suite(self, index: int) -> TestSuiteExecution:
         return self.run.test_suite_executions[index]