# Reporting Examples

This document provides comprehensive examples for generating reports using the SerDes Validation Framework's reporting system.

## Basic Reporting

### Example 1: Simple Compliance Report

```python
from serdes_validation_framework.reporting import USB4TestReporter
from serdes_validation_framework.reporting import TestSession, ReportType
from serdes_validation_framework.protocols.usb4.constants import USB4SignalMode
from datetime import datetime

# Initialize reporter
reporter = USB4TestReporter()

# Create test session
session = TestSession(
    session_id="usb4_compliance_001",
    timestamp=datetime.now(),
    test_type=ReportType.COMPLIANCE,
    signal_mode=USB4SignalMode.GEN3_X2,
    device_info={
        "vendor": "Example Corp",
        "model": "USB4-DEV-001",
        "serial": "SN123456789",
        "firmware": "1.2.3"
    },
    operator="Test Engineer"
)

reporter.add_test_session(session)

# Add test results (assuming you have compliance_results from validation)
reporter.add_compliance_results(session.session_id, compliance_results)

# Generate HTML report
html_report = reporter.generate_compliance_report(
    session_id=session.session_id,
    template_name='compliance_html'
)

print(f"Compliance report generated: {html_report}")
```

### Example 2: Certification Report

```python
# Generate Thunderbolt 4 certification report
cert_report = reporter.generate_certification_report(
    session_id=session.session_id,
    template_name='certification_pdf'
)

print(f"Certification report generated: {cert_report}")
```

## Custom Report Templates

### Example 3: Creating Custom Templates

```python
from serdes_validation_framework.reporting import ReportTemplate, ReportFormat

# Create custom HTML template
custom_template = ReportTemplate(
    name="Custom USB4 Validation Report",
    format=ReportFormat.HTML,
    sections=[
        'executive_summary',
        'device_information',
        'test_configuration',
        'signal_analysis',
        'compliance_results',
        'performance_metrics',
        'recommendations',
        'appendix'
    ],
    include_charts=True,
    include_raw_data=False,
    custom_css="""
        body { font-family: 'Arial', sans-serif; margin: 20px; }
        .header { background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); 
                 color: white; padding: 20px; border-radius: 8px; }
        .summary-card { background: #f8f9fa; border-left: 4px solid #007bff; 
                       padding: 15px; margin: 10px 0; }
        .pass { color: #28a745; font-weight: bold; }
        .fail { color: #dc3545; font-weight: bold; }
        .warning { color: #ffc107; font-weight: bold; }
        table { width: 100%; border-collapse: collapse; margin: 20px 0; }
        th, td { border: 1px solid #dee2e6; padding: 12px; text-align: left; }
        th { background-color: #e9ecef; }
        .chart-container { margin: 20px 0; text-align: center; }
    """,
    custom_header="""
        <div class="header">
            <h1>USB4 Validation Report</h1>
            <p>Comprehensive USB4/Thunderbolt 4 Compliance Testing</p>
        </div>
    """,
    custom_footer="""
        <footer style="margin-top: 40px; padding: 20px; background: #f8f9fa; 
                      border-top: 1px solid #dee2e6; text-align: center;">
            <p>Generated by SerDes Validation Framework | 
               Report Date: {generation_time} | 
               Confidential and Proprietary</p>
        </footer>
    """
)

# Generate report with custom template
custom_report = reporter.generate_compliance_report(
    session_id=session.session_id,
    custom_template=custom_template
)

print(f"Custom report generated: {custom_report}")
```

### Example 4: JSON Report Template

```python
# Create JSON template for API integration
json_template = ReportTemplate(
    name="USB4 API Report",
    format=ReportFormat.JSON,
    sections=['summary', 'results', 'metadata'],
    include_charts=False,
    include_raw_data=True
)

# Generate JSON report
json_report = reporter.generate_compliance_report(
    session_id=session.session_id,
    custom_template=json_template
)

# Load and process JSON data
import json
with open(json_report, 'r') as f:
    report_data = json.load(f)

print(f"JSON report contains {len(report_data['test_results'])} test results")
```

## Advanced Reporting Features

### Example 5: Trend Analysis Report

```python
from serdes_validation_framework.reporting import TrendDataPoint

# Add trend data points from multiple test sessions
trend_data = []

# Simulate historical data
import random
from datetime import timedelta

base_time = datetime.now() - timedelta(days=30)

for day in range(30):
    timestamp = base_time + timedelta(days=day)
    
    # Simulate eye height measurements over time
    eye_height = 0.8 + random.gauss(0, 0.05)  # Base 0.8 with noise
    trend_data.append(TrendDataPoint(
        timestamp=timestamp,
        test_name="eye_diagram_height",
        measured_value=eye_height,
        limit_value=0.7,  # Minimum requirement
        status=TestResult.PASS if eye_height >= 0.7 else TestResult.FAIL,
        session_id=f"daily_test_{day:02d}",
        metadata={"temperature": 25 + random.gauss(0, 2)}
    ))
    
    # Simulate jitter measurements
    jitter_rms = 0.02 + random.gauss(0, 0.005)
    trend_data.append(TrendDataPoint(
        timestamp=timestamp,
        test_name="jitter_rms",
        measured_value=jitter_rms,
        limit_value=0.05,  # Maximum allowed
        status=TestResult.PASS if jitter_rms <= 0.05 else TestResult.FAIL,
        session_id=f"daily_test_{day:02d}",
        metadata={"temperature": 25 + random.gauss(0, 2)}
    ))

# Add trend data to reporter
reporter.add_trend_data(trend_data)

# Generate trend analysis report
trend_report = reporter.generate_trend_analysis_report(
    test_names=["eye_diagram_height", "jitter_rms"],
    time_range_days=30,
    template_name='trend_analysis'
)

print(f"Trend analysis report generated: {trend_report}")
```

### Example 6: Regression Testing Report

```python
# Compare two test sessions for regression analysis
baseline_session_id = "baseline_test_001"
current_session_id = "current_test_001"

# Create baseline session
baseline_session = TestSession(
    session_id=baseline_session_id,
    timestamp=datetime.now() - timedelta(days=7),
    test_type=ReportType.COMPLIANCE,
    signal_mode=USB4SignalMode.GEN3_X2,
    device_info={"version": "1.0.0"}
)

# Create current session
current_session = TestSession(
    session_id=current_session_id,
    timestamp=datetime.now(),
    test_type=ReportType.COMPLIANCE,
    signal_mode=USB4SignalMode.GEN3_X2,
    device_info={"version": "1.1.0"}
)

reporter.add_test_session(baseline_session)
reporter.add_test_session(current_session)

# Add results for both sessions (assuming you have the results)
reporter.add_compliance_results(baseline_session_id, baseline_results)
reporter.add_compliance_results(current_session_id, current_results)

# Generate regression report
regression_report = reporter.generate_regression_report(
    baseline_session_id=baseline_session_id,
    current_session_id=current_session_id,
    template_name='summary_json'
)

print(f"Regression report generated: {regression_report}")
```

## Multi-Format Reporting

### Example 7: Generate Multiple Report Formats

```python
def generate_comprehensive_reports(session_id):
    """Generate reports in multiple formats"""
    
    reports = {}
    
    # HTML report for web viewing
    reports['html'] = reporter.generate_compliance_report(
        session_id=session_id,
        template_name='compliance_html'
    )
    
    # PDF report for documentation
    pdf_template = ReportTemplate(
        name="USB4 Compliance Report",
        format=ReportFormat.PDF,
        sections=['executive_summary', 'test_results', 'recommendations'],
        include_charts=True
    )
    
    reports['pdf'] = reporter.generate_compliance_report(
        session_id=session_id,
        custom_template=pdf_template
    )
    
    # JSON report for API integration
    json_template = ReportTemplate(
        name="USB4 API Data",
        format=ReportFormat.JSON,
        sections=['summary', 'results'],
        include_raw_data=True
    )
    
    reports['json'] = reporter.generate_compliance_report(
        session_id=session_id,
        custom_template=json_template
    )
    
    # XML report for system integration
    xml_template = ReportTemplate(
        name="USB4 XML Report",
        format=ReportFormat.XML,
        sections=['summary', 'results']
    )
    
    reports['xml'] = reporter.generate_compliance_report(
        session_id=session_id,
        custom_template=xml_template
    )
    
    return reports

# Generate all report formats
all_reports = generate_comprehensive_reports(session.session_id)

for format_type, report_path in all_reports.items():
    print(f"{format_type.upper()} report: {report_path}")
```

### Example 8: Automated Report Distribution

```python
import smtplib
from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText
from email.mime.base import MIMEBase
from email import encoders
import os

def distribute_reports(reports, session_info):
    """Automatically distribute reports via email"""
    
    # Email configuration
    smtp_server = "smtp.company.com"
    smtp_port = 587
    sender_email = "test-reports@company.com"
    sender_password = "password"  # Use secure credential management
    
    # Recipients based on report type
    recipients = {
        'engineering': ['engineer1@company.com', 'engineer2@company.com'],
        'management': ['manager@company.com'],
        'qa': ['qa-team@company.com']
    }
    
    # Create email message
    msg = MIMEMultipart()
    msg['From'] = sender_email
    msg['Subject'] = f"USB4 Test Report - {session_info['device_info']['model']}"
    
    # Email body
    body = f"""
    USB4 Validation Test Report
    
    Device: {session_info['device_info']['model']}
    Test Date: {session_info['timestamp']}
    Session ID: {session_info['session_id']}
    
    Please find the attached test reports in multiple formats.
    
    Best regards,
    Automated Test System
    """
    
    msg.attach(MIMEText(body, 'plain'))
    
    # Attach reports
    for format_type, report_path in reports.items():
        if os.path.exists(report_path):
            with open(report_path, "rb") as attachment:
                part = MIMEBase('application', 'octet-stream')
                part.set_payload(attachment.read())
                encoders.encode_base64(part)
                part.add_header(
                    'Content-Disposition',
                    f'attachment; filename= {os.path.basename(report_path)}'
                )
                msg.attach(part)
    
    # Send to all recipients
    all_recipients = []
    for recipient_list in recipients.values():
        all_recipients.extend(recipient_list)
    
    msg['To'] = ', '.join(all_recipients)
    
    # Send email
    try:
        server = smtplib.SMTP(smtp_server, smtp_port)
        server.starttls()
        server.login(sender_email, sender_password)
        server.sendmail(sender_email, all_recipients, msg.as_string())
        server.quit()
        print("Reports distributed successfully")
    except Exception as e:
        print(f"Failed to distribute reports: {e}")

# Distribute reports
distribute_reports(all_reports, session.__dict__)
```

## Interactive Reporting

### Example 9: Web Dashboard Integration

```python
from flask import Flask, render_template, jsonify
import json

app = Flask(__name__)

@app.route('/dashboard')
def dashboard():
    """Web dashboard for test reports"""
    return render_template('dashboard.html')

@app.route('/api/test-results/<session_id>')
def get_test_results(session_id):
    """API endpoint for test results"""
    
    # Generate JSON report
    json_template = ReportTemplate(
        name="Dashboard Data",
        format=ReportFormat.JSON,
        sections=['summary', 'results'],
        include_raw_data=False
    )
    
    json_report = reporter.generate_compliance_report(
        session_id=session_id,
        custom_template=json_template
    )
    
    # Load and return JSON data
    with open(json_report, 'r') as f:
        report_data = json.load(f)
    
    return jsonify(report_data)

@app.route('/api/trend-data')
def get_trend_data():
    """API endpoint for trend analysis data"""
    
    trend_report = reporter.generate_trend_analysis_report(
        time_range_days=30,
        template_name='summary_json'
    )
    
    with open(trend_report, 'r') as f:
        trend_data = json.load(f)
    
    return jsonify(trend_data)

# HTML template for dashboard (save as templates/dashboard.html)
dashboard_html = """
<!DOCTYPE html>
<html>
<head>
    <title>USB4 Test Dashboard</title>
    <script src="https://cdn.plot.ly/plotly-latest.min.js"></script>
    <style>
        body { font-family: Arial, sans-serif; margin: 20px; }
        .metric-card { 
            display: inline-block; 
            background: #f8f9fa; 
            padding: 20px; 
            margin: 10px; 
            border-radius: 8px; 
            min-width: 200px;
        }
        .metric-value { font-size: 2em; font-weight: bold; color: #007bff; }
        .chart-container { margin: 20px 0; }
    </style>
</head>
<body>
    <h1>USB4 Validation Dashboard</h1>
    
    <div id="metrics"></div>
    <div id="charts"></div>
    
    <script>
        // Load and display test results
        fetch('/api/test-results/latest')
            .then(response => response.json())
            .then(data => {
                displayMetrics(data.summary);
                displayCharts(data.test_results);
            });
        
        function displayMetrics(summary) {
            const metricsDiv = document.getElementById('metrics');
            metricsDiv.innerHTML = `
                <div class="metric-card">
                    <div class="metric-value">${summary.total_tests}</div>
                    <div>Total Tests</div>
                </div>
                <div class="metric-card">
                    <div class="metric-value">${summary.passed_tests}</div>
                    <div>Passed</div>
                </div>
                <div class="metric-card">
                    <div class="metric-value">${summary.pass_rate.toFixed(1)}%</div>
                    <div>Pass Rate</div>
                </div>
            `;
        }
        
        function displayCharts(testResults) {
            // Create pass/fail chart
            const passFailData = [{
                values: [testResults.passed, testResults.failed],
                labels: ['Passed', 'Failed'],
                type: 'pie',
                marker: { colors: ['#28a745', '#dc3545'] }
            }];
            
            Plotly.newPlot('charts', passFailData, {
                title: 'Test Results Overview'
            });
        }
    </script>
</body>
</html>
"""

if __name__ == '__main__':
    app.run(debug=True)
```

## Report Customization

### Example 10: Dynamic Report Content

```python
def generate_dynamic_report(session_id, customization_options):
    """Generate report with dynamic content based on options"""
    
    # Base template
    template_sections = ['executive_summary']
    
    # Add sections based on options
    if customization_options.get('include_signal_analysis', True):
        template_sections.extend(['signal_analysis', 'eye_diagram_analysis'])
    
    if customization_options.get('include_compliance_details', True):
        template_sections.append('compliance_results')
    
    if customization_options.get('include_performance_metrics', False):
        template_sections.append('performance_metrics')
    
    if customization_options.get('include_recommendations', True):
        template_sections.append('recommendations')
    
    # Create dynamic template
    dynamic_template = ReportTemplate(
        name=customization_options.get('report_title', 'USB4 Test Report'),
        format=ReportFormat.HTML,
        sections=template_sections,
        include_charts=customization_options.get('include_charts', True),
        include_raw_data=customization_options.get('include_raw_data', False),
        custom_css=customization_options.get('custom_css', ''),
        logo_path=customization_options.get('company_logo', None)
    )
    
    # Generate report
    report_path = reporter.generate_compliance_report(
        session_id=session_id,
        custom_template=dynamic_template
    )
    
    return report_path

# Example usage with different customization options
engineering_options = {
    'report_title': 'Engineering Analysis Report',
    'include_signal_analysis': True,
    'include_compliance_details': True,
    'include_performance_metrics': True,
    'include_recommendations': True,
    'include_charts': True,
    'include_raw_data': True
}

management_options = {
    'report_title': 'Executive Summary Report',
    'include_signal_analysis': False,
    'include_compliance_details': False,
    'include_performance_metrics': False,
    'include_recommendations': True,
    'include_charts': True,
    'include_raw_data': False
}

# Generate different reports for different audiences
eng_report = generate_dynamic_report(session.session_id, engineering_options)
mgmt_report = generate_dynamic_report(session.session_id, management_options)

print(f"Engineering report: {eng_report}")
print(f"Management report: {mgmt_report}")
```

These examples demonstrate the comprehensive reporting capabilities of the framework. The reporting system supports multiple formats, custom templates, trend analysis, and integration with external systems.

For more information on reporting features, see the [Reporting API Documentation](../api/reporting.md).