# tcms-artifact-browser

A [Kiwi TCMS](https://kiwitcms.org) plugin that provides a centralized view to
browse, preview, search, and export file attachments across test runs and bugs.

## Features

- **Tree navigation** — Browse artifacts organized by Product > Test Plan > Test Run
- **Bug browser** — Dedicated sidebar panel to browse bug attachments by Product > Bug, with linked test plan/run/case references
- **Grouped attachment view** — Attachments displayed per test execution with status badges
- **File preview** — In-browser preview for images, text files, PDFs, video, and audio
- **Bulk ZIP download** — Select multiple files and download them as a structured ZIP archive
- **Global search** — Search attachments by filename across all test runs
- **Statistics dashboard** — Donut charts showing artifact distribution by file type and source
- **Export reports** — Download artifact reports as CSV, Excel, Word, or PDF
- **Product filter** — Filter both test run and bug trees by product
- **No-attachment indicators** — Tree nodes for runs without attachments are visually dimmed

## Screenshots

### Overview with statistics and tree navigation

![Overview](https://raw.githubusercontent.com/veenone/kiwi-tcms-artifact-browser/master/screenshots/overview.png)

### Attachment detail with grouped test executions

![Attachment Detail](https://raw.githubusercontent.com/veenone/kiwi-tcms-artifact-browser/master/screenshots/attachment_detail.png)

### File preview modal

![Preview Modal](https://raw.githubusercontent.com/veenone/kiwi-tcms-artifact-browser/master/screenshots/preview_modal.png)

### Global search results

![Search Results](https://raw.githubusercontent.com/veenone/kiwi-tcms-artifact-browser/master/screenshots/search_results.png)

### Bug browser with linked test entities

![Bug Browser](https://raw.githubusercontent.com/veenone/kiwi-tcms-artifact-browser/master/screenshots/bug_browser.png)

### No-attachments indicator on tree nodes

![No Attachments](https://raw.githubusercontent.com/veenone/kiwi-tcms-artifact-browser/master/screenshots/tree_no_attachments.png)

## Installation

```bash
pip install -e /path/to/tcms-artifact-browser/
```

Then restart Kiwi TCMS. The plugin auto-registers via the `kiwitcms.plugins` entry
point and appears under **MORE > Artifact Browser > Browse Artifacts** in the navigation menu.

If running in development mode, also run:

```bash
python manage.py collectstatic --noinput
```

## Dependencies

- [openpyxl](https://pypi.org/project/openpyxl/) — Excel report generation
- [python-docx](https://pypi.org/project/python-docx/) — Word report generation
- [reportlab](https://pypi.org/project/reportlab/) — PDF report generation

Charts use D3.js and C3.js which are already included in Kiwi TCMS base static files.

## URL Endpoints

| URL | Description |
|---|---|
| `/tcms_artifact_browser/` | Main browser view |
| `/tcms_artifact_browser/api/run/<id>/attachments/` | Attachments for a test run |
| `/tcms_artifact_browser/api/bug/<id>/attachments/` | Attachments for a bug |
| `/tcms_artifact_browser/api/attachment/<id>/preview/` | File preview metadata |
| `/tcms_artifact_browser/api/search/?q=<query>` | Global search |
| `/tcms_artifact_browser/api/statistics/` | Aggregate statistics |
| `/tcms_artifact_browser/api/download/zip/` | Bulk ZIP download (POST) |
| `/tcms_artifact_browser/api/report/` | CSV report |
| `/tcms_artifact_browser/api/report/excel/` | Excel report |
| `/tcms_artifact_browser/api/report/docx/` | Word report |
| `/tcms_artifact_browser/api/report/pdf/` | PDF report |

## Architecture

```
tcms_artifact_browser/
├── __init__.py          # App config reference
├── apps.py              # ArtifactBrowserConfig
├── menu.py              # Navigation menu registration
├── urls.py              # URL routing (11 endpoints)
├── views.py             # TemplateView + 10 API views + report helpers
├── utils.py             # File classification, attachment gathering, ZIP paths
├── templates/tcms_artifact_browser/
│   ├── browser.html     # Main template (stats + tree + detail panel)
│   └── _preview.html    # Preview modal fragment
└── static/tcms_artifact_browser/
    ├── css/browser.css  # Flexbox layout, responsive styles
    └── js/browser.js    # Tree navigation, AJAX loading, preview, charts
```

### Key design decisions

- **Bulk query strategy** — Attachments are fetched with bulk queries per content type
  (TestRun, TestExecution, TestCase, Bug) instead of N+1 per-object queries
- **Extension-based classification** — Files are categorized by extension (not MIME
  sniffing) for speed and determinism
- **Text preview capped at 100KB** — Prevents browser memory issues with large log files
- **POST for ZIP** — Attachment ID lists can be large; form POST triggers native download

## License

MIT
