History tab: show full activity timeline (tags, folders, metadata) not just content versions

[elitea-ai]

Problem

The History tab on test case detail view only shows content version changes (title, steps, description, etc). Other important actions are tracked in audit events but invisible to the user:

• Tag additions/removals
• Folder (suite) additions/removals
• Metadata-only changes (status, owner, execution_type, test_category)

Users have no visibility into the full lifecycle of a test case.

Current State

What's shown in History tab:

• TestCaseVersion records — immutable snapshots created when content fields change
• Version diff viewer (side-by-side comparison)
• Author, timestamp, change_reason per version

What's written to test_audit_events but NOT shown:

• tags_modified — tag add/remove
• test_cases_added / test_case_removed — folder membership changes
• updated — metadata-only changes (status, owner, etc)
• moved — bulk move between folders

Solution

Extend the History tab to show a unified timeline combining:

1. Version changes (existing) — with diff viewer
2. Audit events for this test case — rendered as timeline entries

Timeline entry types:

Event	Display
version_created	"v2 created by @user — Title changed, 3 steps modified" (with Diff button)
updated	"Status changed from Draft → Ready by @user"
tags_modified	"Tags: +regression, -draft by @user"
test_cases_added	"Added to suite 'Smoke Tests' by @user"
test_case_removed	"Removed from suite 'Old Suite' by @user"
moved	"Moved to folder 'Regression' by @user"
created	"Test case created by @user"

Implementation Notes

Backend:

• New API endpoint: GET /test-cases/{test_case_id}/history — returns merged timeline of versions + audit events, sorted by timestamp
• Or: GET /test-cases/{test_case_id}/audit-events — returns audit events only (frontend merges with versions)

Frontend:

• TestCaseDetail.jsx History tab (line 762) — replace version-only list with unified timeline
• Keep the Diff button/viewer for version changes
• Simpler display for non-version events (inline text, no diff needed)

Acceptance Criteria

• History tab shows all event types, not just content versions
• Events are sorted chronologically (newest first)
• Version events retain Diff viewer functionality
• Non-version events show actor, timestamp, and change summary
• Tag changes show which tags were added/removed
• Folder changes show suite name

[elitea-ai]

🔍 Root Cause Analysis Report — Investigation Started

Investigator: RCA Agent
Issue: History tab: show full activity timeline (tags, folders, metadata) not just content versions

---

Executive Summary

The History tab limitation is a feature gap, not a bug. The backend has a fully functional audit event system (test_audit_events table) that tracks 25+ action types across test cases, folders, tags, and bulk operations. However, no API endpoint exists to retrieve audit events for a test case, and the frontend only calls the /versions endpoint. All infrastructure pieces exist — they just need to be connected.

Issue Classification

• Category: Feature Gap (Backend endpoint missing + Frontend display limitation)
• Severity Assessment: Medium — Functional impact on user visibility, no data loss
• Scope: Moderate — Requires backend API addition + frontend UI rework

---

Root Cause Details

Primary Cause

The History tab was built during the initial test case versioning feature, which only addressed content versioning (title, steps, description changes). The audit event system was added later as a cross-cutting concern for all entity operations, but was never wired to the frontend for display purposes.

Two specific gaps:

1. Backend: No REST endpoint exposes test_audit_events for a given test case
2. Frontend: History tab only fetches GET /test-cases/{id}/versions and renders version records

Code Location(s)

File	Line(s)	Description
services/test-management/src/onetest/test_management/db/repository.py	1576-1601	AuditRepository.list_by_entity() — exists but not exposed via API
services/test-management/src/onetest/test_management/models.py	729-752	AuditEventResponse + AuditListResponse — response models exist, unused
core/src/pages/TestCaseDetail.jsx	785-901	History tab — only renders version list + diff viewer
core/src/store/slices/testManagementSlice.js	94-114	Redux thunks — only fetchTestCaseVersions + fetchVersionDiff
core/src/services/testManagementApi.js	132-148	API layer — only getTestCaseVersions() + compareVersions()

---

Evidence: What's Already Built

✅ Backend Audit Infrastructure (Fully Functional)

Database Table: test_audit_events (migration 001_core_entities.sql, lines 230-256)

CREATE TABLE test_audit_events (
    id UUID PRIMARY KEY,
    entity_type VARCHAR(50) NOT NULL,     -- 'test_case', 'test_case_version', 'folder', 'tag'
    entity_id UUID NOT NULL,
    action VARCHAR(50) NOT NULL,          -- 'created', 'updated', 'tagged', etc.
    actor VARCHAR(255) NOT NULL,
    before_snapshot JSONB,
    after_snapshot JSONB,
    diff JSONB,
    metadata JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT now()
);

Indexed for retrieval: idx_test_audit_events_entity ON (entity_type, entity_id)

✅ Audit Events Are Being Written

Here's what's currently being tracked with entity_type="test_case":

Action	File	Data Captured
created	test_cases.py:221	after_snapshot: {identifier, title}
updated (metadata)	test_cases.py:901	before_snapshot + after_snapshot of changed fields
deleted	test_cases.py:997	Actor only
tagged	tags.py:228	metadata: {tags_added: [...]}
untagged	tags.py:259	metadata: {tag_removed: "name"}
moved	bulk_operations.py:73	after_snapshot: {folder_id}
tags_modified	bulk_operations.py:149	after_snapshot: {added_tags, removed_tags}
bulk_updated	bulk_operations.py:223	before_snapshot + after_snapshot
archived	bulk_operations.py:279	before_snapshot: {identifier}
restored	bulk_operations.py:334	after_snapshot: {identifier}

With entity_type="test_case_version":

Action	File	Data Captured
version_created	test_cases.py:891	metadata: {test_case_id, version_number}

✅ Response Models Exist But Are Unused

# models.py:729-752
class AuditEventResponse(BaseModel):
    id: UUID
    entity_type: str
    entity_id: UUID
    action: str
    actor: str
    before_snapshot: dict | None
    after_snapshot: dict | None
    diff: dict | None
    metadata: dict
    created_at: datetime

class AuditListResponse(BaseModel):
    items: list[AuditEventResponse]
    total: int
    limit: int
    offset: int

✅ Repository Query Method Exists

# repository.py:1576-1601
async def list_by_entity(self, entity_type, entity_id, limit=50, offset=0):
    # Queries test_audit_events WHERE entity_type = ? AND entity_id = ?
    # Returns (events, total) with pagination, ordered by created_at DESC

---

⚠️ Critical Data Model Issue: Folder Events

This is the most important finding for implementation planning.

Folder membership events (test_cases_added, test_case_removed) are stored with:

• entity_type = "folder"
• entity_id = folder_id (NOT the test case ID!)

# folders.py:461-467
await audit_repo.create(
    entity_type="folder",        # ← Folder, not test_case!
    entity_id=folder_id,         # ← Folder UUID, not test case UUID!
    action="test_cases_added",
    metadata={"count": added},   # ← No individual test case IDs
)

# folders.py:497-503
await audit_repo.create(
    entity_type="folder",
    entity_id=folder_id,
    action="test_case_removed",
    metadata={"test_case_id": str(test_case_id)},  # ← TC ID in metadata only
)

Similarly, version_created uses entity_type="test_case_version" with entity_id=version_uuid, storing test_case_id in metadata.

Implication: A simple list_by_entity("test_case", test_case_id) query will miss:

1. All test_cases_added events (stored under folder entity)
2. All test_case_removed events (stored under folder entity)
3. All version_created events (stored under test_case_version entity)

This requires either:

• Option A: A new composite query that searches across multiple entity types + metadata
• Option B: Dual-write: Also create a test_case-scoped audit event when folder/version changes happen
• Option C: A new list_by_test_case() repository method with a UNION query

---

Impact Analysis

Usage Locations — Backend

File	Lines	Usage	Risk Level
api/test_cases.py	220-226	Creates test_case audit events	None (read-only change)
api/tags.py	227-264	Creates test_case audit events for tagging	None
api/folders.py	461-503	Creates folder audit events (⚠️ gap)	Medium
api/bulk_operations.py	72-339	Creates test_case audit events	None
db/repository.py	1576-1601	list_by_entity() query method	Needs extension
models.py	729-752	Response models	Ready to use

Usage Locations — Frontend

File	Lines	Usage	Risk Level
TestCaseDetail.jsx	785-901	History tab rendering	High (needs rewrite)
testManagementSlice.js	94-114, 1248-1270	Redux thunks + reducers	Medium (needs new thunks)
testManagementApi.js	132-148	API calls	Low (add new endpoint call)
VersionDiffViewer.jsx	1-361	Diff viewer component	None (keep as-is for version diffs)

Regression Risk Matrix

Component	Current Behavior	Post-Change Behavior	Risk	Mitigation
Version list	Shows versions only	Part of unified timeline	Medium	Keep version diff viewer intact
Diff button	Opens version diff	Same, only on version entries	Low	No change needed
Version fetch	GET /versions	Still needed for diff viewer	None	Don't remove, add new endpoint
History tab layout	Two-column (list + diff)	Timeline left, diff panel right	Medium	Progressive enhancement

Test Impact

• Existing tests affected: 0 (no existing tests for History tab)
• New tests recommended:
  • Backend: API endpoint for /test-cases/{id}/history
  • Backend: Composite query across entity types
  • Frontend: Timeline rendering with mixed event types
  • E2E: History tab shows tags, folders, metadata changes

---

Suggested Remediation

Recommended Approach: New Composite History Endpoint

Why: Minimizes regression risk, preserves existing version diff functionality, centralizes the complex multi-entity-type query in the backend.

Backend Changes

1. New repository method (repository.py):

async def list_test_case_history(
    self, test_case_id: UUID, limit: int = 50, offset: int = 0
) -> tuple[list[TestAuditEvent], int]:
    """Get unified history: test_case events + version events + folder events."""
    query = select(TestAuditEvent).where(
        or_(
            # Direct test_case events (created, updated, tagged, moved, etc.)
            and_(
                TestAuditEvent.entity_type == "test_case",
                TestAuditEvent.entity_id == test_case_id,
            ),
            # Version creation events (entity_type=test_case_version, tc_id in metadata)
            and_(
                TestAuditEvent.entity_type == "test_case_version",
                TestAuditEvent.metadata_["test_case_id"].astext == str(test_case_id),
            ),
            # Folder membership events (entity_type=folder, tc_id in metadata)
            and_(
                TestAuditEvent.entity_type == "folder",
                TestAuditEvent.action.in_(["test_cases_added", "test_case_removed"]),
                TestAuditEvent.metadata_["test_case_id"].astext == str(test_case_id),
            ),
        )
    ).order_by(TestAuditEvent.created_at.desc())
    # ... pagination

⚠️ Note on test_cases_added event: Currently stores metadata: {"count": N} without individual test case IDs. This means we cannot retrieve folder-add events for a specific test case. Two options:

1. Change the audit event creation in folders.py:461-467 to emit one event per test case (recommended)
2. Accept the gap and only show folder-remove events

2. New API endpoint (test_cases.py):

GET /test-cases/{test_case_id}/history?limit=50&offset=0

Returns AuditListResponse (model already exists).

Frontend Changes

3. New Redux thunk + API call:

• testManagementApi.getTestCaseHistory(testCaseId, limit, offset)
• fetchTestCaseHistory thunk in slice

4. Refactor History tab (TestCaseDetail.jsx:785-901):

• Replace version-only list with unified timeline
• Each timeline entry renders based on action type
• Version entries retain "Diff" button functionality
• Non-version entries display inline change summary

5. New TimelineEntry component (optional, for clean separation):

• Renders different layouts based on event type
• Uses MUI Timeline or custom card-based layout

Alternative Approaches

Approach	Pros	Cons	Regression Risk
Single composite endpoint (recommended)	Clean API, frontend simplicity	Complex query, needs JSONB index for metadata	Low
Separate audit-events endpoint (frontend merges)	Simpler backend	Frontend complexity, two API calls, merge logic	Medium
Dual-write audit events	Simple queries	Data duplication, migration needed for existing data	Medium

Implementation Safety Checklist

• Existing GET /test-cases/{id}/versions endpoint preserved (diff viewer still needs it)
• No breaking changes to existing audit event creation
• test_cases_added in folders.py updated to include individual test case IDs
• JSONB index on metadata->>'test_case_id' for performance
• Pagination maintained for large histories
• Feature flag recommended: No (additive change, no existing behavior removed)

Files Requiring Modification

File	Change Type	Complexity	Existing Tests
services/test-management/src/onetest/test_management/db/repository.py	New method	Medium	No
services/test-management/src/onetest/test_management/api/test_cases.py	New endpoint	Low	No
services/test-management/src/onetest/test_management/api/folders.py	Fix audit event data	Low	No
core/src/services/testManagementApi.js	New API call	Low	No
core/src/store/slices/testManagementSlice.js	New thunk + state	Low	No
core/src/pages/TestCaseDetail.jsx	Refactor History tab	High	No

---

Additional Observations

1. Data quality gap in test_cases_added: The folder-add audit event (folders.py:461-467) only records {"count": N} — it does NOT record which specific test cases were added. This needs to be fixed to make the history useful.

2. No actor resolution: Audit events store actor as a user ID string. The frontend will need to resolve this to display names (similar to how version author is handled).

3. version_created redundancy: When content changes, both a test_case_version record AND a version_created audit event are created. The unified timeline should use the audit event and cross-reference the version data for the diff viewer.

4. Index recommendation: Add a GIN or BTREE index on test_audit_events.metadata->>'test_case_id' for efficient composite queries.

Investigation Artifacts

• Files examined: 12
• Audit event creation sites found: 15+ across 6 API files
• Response models: Pre-built and ready to use
• Repository methods: list_by_entity() exists, needs composite extension