---
title: "Generating Reports"
description: "Create traceability matrices, coverage reports, and project analytics"
---

# Generating Reports

TraceRTM provides comprehensive reporting to visualize your traceability data, identify gaps, and track project health.

## Report Types

| Report | Purpose | Format |
|--------|---------|--------|
| **Traceability Matrix** | Requirements to tests/code mapping | HTML, CSV, JSON |
| **Coverage Report** | Test coverage by feature | HTML, JSON |
| **Impact Report** | Change impact analysis | HTML, JSON |
| **Gap Analysis** | Missing links and orphans | HTML, CSV |
| **Progress Report** | Status distribution over time | HTML, JSON |
| **Audit Trail** | Change history | JSON, CSV |

## Traceability Matrix

The classic RTM showing relationships between artifact types:

### CLI

```bash
# Generate feature-to-test matrix
tracertm report matrix --rows feature --cols test

# Export to HTML
tracertm report matrix --rows feature --cols test --output matrix.html

# Export to CSV
tracertm report matrix --rows feature --cols test --format csv --output matrix.csv

# Include multiple column types
tracertm report matrix --rows feature --cols test,code --output full-matrix.html
```

### Output Example

```
Requirements Traceability Matrix
Generated: 2024-12-07T10:00:00Z
Project: my-web-app

                    Tests                           Code
Feature         TEST-001  TEST-002  TEST-003    CODE-001  CODE-002
────────────────────────────────────────────────────────────────────
FEAT-001           ✓         ✓                     ✓
FEAT-002           ✓         ✓         ✓           ✓         ✓
FEAT-003                                                     ✓
────────────────────────────────────────────────────────────────────
Coverage          66%       66%       33%         66%       66%
```

### Python SDK

```python
from tracertm import TraceRTMClient

client = TraceRTMClient()

# Generate matrix
matrix = client.generate_report(
    report_type="matrix",
    row_type="feature",
    col_types=["test", "code"],
    project_id="proj-001"
)

# Access programmatically
for row in matrix.rows:
    print(f"{row.id}: {row.title}")
    print(f"  Test coverage: {row.coverage['test']}%")
    print(f"  Code coverage: {row.coverage['code']}%")

# Export
matrix.export("matrix.html", format="html")
matrix.export("matrix.csv", format="csv")
```

## Coverage Report

Analyze how well your requirements are covered:

### CLI

```bash
# Test coverage report
tracertm report coverage --type test

# Output:
# Test Coverage Report
# ════════════════════════════════════════════
#
# Summary
# ────────────────────────────────────────────
# Total Features: 25
# Fully Covered:  18 (72%)
# Partially:       4 (16%)
# No Coverage:     3 (12%)
#
# Features Missing Tests
# ────────────────────────────────────────────
# FEAT-015: Payment Processing     [critical]
# FEAT-021: Email Notifications    [medium]
# FEAT-023: Export to PDF          [low]
#
# Features with Partial Coverage
# ────────────────────────────────────────────
# FEAT-003: User Profile (2/5 tests)
# FEAT-008: Search (1/3 tests)
```

### Python SDK

```python
coverage = client.generate_report(
    report_type="coverage",
    coverage_type="test",
    project_id="proj-001"
)

print(f"Coverage: {coverage.summary['percentage']}%")
print(f"Fully covered: {coverage.summary['full_count']}")
print(f"Missing coverage: {coverage.summary['missing_count']}")

# Get uncovered items
for item in coverage.uncovered:
    print(f"⚠ {item.id}: {item.title} [{item.priority}]")
```

## Impact Report

Analyze what's affected when something changes:

### CLI

```bash
# Impact analysis for a feature
tracertm report impact FEAT-001

# Output:
# Impact Analysis Report
# ════════════════════════════════════════════
# Source: FEAT-001 (User Authentication)
#
# Direct Impact (1 hop)
# ────────────────────────────────────────────
# CODE:
#   CODE-001: auth/login.py
#   CODE-002: auth/session.py
# TEST:
#   TEST-001: test_login_valid
#   TEST-002: test_login_invalid
#   TEST-003: test_session_management
#
# Indirect Impact (2+ hops)
# ────────────────────────────────────────────
# FEATURE:
#   FEAT-005: Dashboard (depends_on FEAT-001)
#   FEAT-012: User Profile (depends_on FEAT-001)
# TEST:
#   TEST-010: test_dashboard_auth (tests FEAT-005)
#
# Summary
# ────────────────────────────────────────────
# Total artifacts affected: 9
# Tests to re-run: 4
# Estimated review effort: Medium

# Save to file
tracertm report impact FEAT-001 --output impact-report.html
```

### Python SDK

```python
impact = client.generate_report(
    report_type="impact",
    source_id="FEAT-001",
    max_depth=3
)

print(f"Artifacts affected: {impact.total_count}")
print(f"Tests to update: {len(impact.tests)}")

# Group by type
for item_type, items in impact.by_type.items():
    print(f"\n{item_type.upper()}:")
    for item in items:
        print(f"  {item.id}: {item.title}")
```

## Gap Analysis

Find missing links and orphaned artifacts:

### CLI

```bash
# Full gap analysis
tracertm report gaps

# Output:
# Gap Analysis Report
# ════════════════════════════════════════════
#
# Features Without Tests (3)
# ────────────────────────────────────────────
# FEAT-015: Payment Processing     [critical] ⚠
# FEAT-021: Email Notifications    [medium]
# FEAT-023: Export to PDF          [low]
#
# Code Without Implementation Links (2)
# ────────────────────────────────────────────
# CODE-045: utils/helpers.py
# CODE-046: utils/validators.py
#
# Orphaned Tests (1)
# ────────────────────────────────────────────
# TEST-089: test_deprecated_feature
#
# Broken Links (1)
# ────────────────────────────────────────────
# TEST-023 -> FEAT-099 (target deleted)
#
# Recommendations
# ────────────────────────────────────────────
# 1. Add tests for critical feature FEAT-015
# 2. Review orphaned test TEST-089
# 3. Fix broken link in TEST-023
```

### Python SDK

```python
gaps = client.generate_report(
    report_type="gaps",
    project_id="proj-001"
)

# Critical gaps
critical = [g for g in gaps.features_without_tests if g.priority == "critical"]
if critical:
    print("CRITICAL: These features need tests immediately:")
    for item in critical:
        print(f"  {item.id}: {item.title}")

# Export for tracking
gaps.export("gaps.json", format="json")
```

## Progress Report

Track project health over time:

### CLI

```bash
# Weekly progress report
tracertm report progress --period week

# Output:
# Progress Report (Last 7 Days)
# ════════════════════════════════════════════
#
# Status Distribution
# ────────────────────────────────────────────
# Features:
#   Draft:        5  ████░░░░░░  20%
#   In Progress:  8  ████████░░  32%
#   Done:        12  ████████████ 48%
#
# Tests:
#   Passed:      45  █████████░  90%
#   Failed:       3  ██░░░░░░░░   6%
#   Skipped:      2  █░░░░░░░░░   4%
#
# Activity
# ────────────────────────────────────────────
# Items created:     12
# Items updated:     34
# Links created:     28
# Transitions:       15
#
# Coverage Trend
# ────────────────────────────────────────────
# Week 1: 65% ──▶ Week 2: 72% (+7%)
```

### Python SDK

```python
progress = client.generate_report(
    report_type="progress",
    period="week",
    project_id="proj-001"
)

print(f"Features completed this week: {progress.completed_count}")
print(f"Test pass rate: {progress.test_pass_rate}%")
print(f"Coverage change: {progress.coverage_delta:+.1f}%")

# Trend data for charts
for point in progress.trend:
    print(f"{point.date}: {point.coverage}% coverage")
```

## Audit Trail

Review all changes for compliance:

### CLI

```bash
# Get audit log
tracertm report audit --days 30

# Filter by actor
tracertm report audit --actor alice@example.com

# Filter by event type
tracertm report audit --events item_created,item_updated

# Export for compliance
tracertm report audit --days 90 --output audit-q4.json
```

### Python SDK

```python
audit = client.generate_report(
    report_type="audit",
    start_date="2024-10-01",
    end_date="2024-12-31",
    event_types=["item_created", "item_updated", "link_created"]
)

for event in audit.events:
    print(f"{event.timestamp} | {event.actor} | {event.event_type}")
    print(f"  {event.entity_type}: {event.entity_id}")
    if event.diff:
        print(f"  Changes: {event.diff}")
```

## Custom Reports

Create custom reports with queries:

```python
# Custom query
results = client.query("""
    SELECT
        f.id as feature_id,
        f.title as feature_title,
        COUNT(t.id) as test_count,
        SUM(CASE WHEN t.status = 'passed' THEN 1 ELSE 0 END) as passed
    FROM items f
    LEFT JOIN links l ON f.id = l.target_id AND l.link_type = 'tests'
    LEFT JOIN items t ON l.source_id = t.id
    WHERE f.type = 'feature'
    GROUP BY f.id
""")

# Export to DataFrame
import pandas as pd
df = pd.DataFrame(results)
df.to_excel("custom-report.xlsx")
```

## Scheduled Reports

Set up automated report generation:

```yaml
# .tracertm/reports.yaml
schedules:
  - name: weekly-coverage
    report: coverage
    frequency: weekly
    day: monday
    time: "09:00"
    recipients:
      - team@example.com
    format: html

  - name: daily-gaps
    report: gaps
    frequency: daily
    time: "08:00"
    webhook: https://slack.com/webhook/xxx
    format: json
```

## Report Export Formats

| Format | Use Case |
|--------|----------|
| `html` | Human-readable, shareable |
| `json` | API integration, processing |
| `csv` | Spreadsheet analysis |
| `pdf` | Formal documentation |
| `markdown` | Documentation sites |

```bash
# Export in different formats
tracertm report matrix --format html --output matrix.html
tracertm report matrix --format csv --output matrix.csv
tracertm report matrix --format json --output matrix.json
tracertm report matrix --format pdf --output matrix.pdf
```

## Best Practices

### 1. Regular Gap Analysis

Run gap analysis weekly to catch issues early:

```bash
# Add to CI/CD
tracertm report gaps --fail-on-critical
```

### 2. Track Coverage Trends

Monitor coverage over time, not just snapshots:

```python
# Store coverage history
coverage = client.generate_report("coverage")
client.record_metric("test_coverage", coverage.percentage)
```

### 3. Automate Compliance Reports

Schedule audit reports for regulatory needs:

```yaml
schedules:
  - name: monthly-audit
    report: audit
    frequency: monthly
    retention: 7years
```

### 4. Share Reports with Stakeholders

Generate executive summaries:

```bash
tracertm report summary --format html --output status.html
```

## Related Topics

- [Traceability](/docs/getting-started/first-project/traceability) - Building the graph
- [Impact Analysis](/docs/wiki/concepts/impact-analysis) - Deep dive
- [API Reference](/docs/api-reference) - Report API endpoints

