Metadata-Version: 2.4
Name: velvet-report
Version: 2.1.2
Summary: VelvetReport — Universal JUnit XML to self-contained offline HTML test reporter. Works with pytest, Playwright, Maven, Jest, Cypress, Robot Framework.
Home-page: https://github.com/velvetreport/velvet-report
Author: VelvetReport Contributors
Author-email: hello@velvetreport.dev
Keywords: velvet-report test-report junit pytest playwright html-report offline allure-alternative extent-report robot-framework ci-report test-results velvetreport
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Pytest
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: requires-python
Dynamic: summary

# VelvetReport — Universal Test Reporter

[![PyPI](https://img.shields.io/pypi/v/velvet-report?color=3b82f6&label=pip)](https://pypi.org/project/velvet-report/)
[![npm](https://img.shields.io/npm/v/velvet-report?color=22c55e&label=npm)](https://www.npmjs.com/package/velvet-report)
[![Maven Central](https://img.shields.io/maven-central/v/dev.velvetreport/velvet-report?color=f59e0b)](https://central.sonatype.com/artifact/dev.velvetreport/velvet-report)
[![License: MIT](https://img.shields.io/badge/license-MIT-a855f7)](LICENSE)
[![Tests](https://img.shields.io/badge/self--tests-25%2F25%20passing-22c55e)](scripts/build.js)

**One install. Any language. Beautiful reports. Zero server.**

VelvetReport turns any JUnit XML into a stunning, self-contained HTML dashboard — automatically after every test run. No upload. No internet required. 100% offline.

**New in 2.1 — zero-config pytest auto-capture.** `pip install velvet-report`, run `pytest`, and the report auto-fills environment, marks, setup/call/teardown timings, fixtures, steps, screenshots, and xdist worker distribution. Allure-quality detail, zero config, zero server.

---

## Project Structure & Platform Server

```text
VelvetReport Project Structure:
├── website/             # Product landing page (http://localhost:4100/)
├── offlineReport/       # Core reporting engine library (core source, packages, platform, plugins, reports, scratch, shared)
├── ai/                  # AI agent fleet instructions (agents.ai.md), AST symbol map (symbol-map.ai.md)
├── docs/                # Technical documentation
└── scripts/             # Build system (build.js), line-limit auditor (check-line-limits.js), symbol mapper (map-symbols.js)
```

### Application Flow & Server Commands

1. **Run Local Ingestion & Dashboard Platform Server**:
   ```bash
   node offlineReport/platform/server.js
   ```

2. **Access Flow in Browser**:
   - `http://localhost:4100/` ──▶ **Website Landing Page** (defaults to clean light theme)
   - `http://localhost:4100/about` ──▶ **About Us Page**
   - `http://localhost:4100/sample-report` ──▶ **Interactive Offline Demo Report**
   - `http://localhost:4100/dashboard` ──▶ **Platform Ingestion Dashboard UI**

3. **Build & Verify Offline Report Packages**:
   ```bash
   node scripts/build.js --verify
   ```

---

## Testing the Local Platform & Ingestion Server

To verify the platform server endpoints, Ingestion APIs, and Client upload interactions:

### 1. Automated Platform Tests
Run the entire platform test suite (server endpoints, ingestion validation, and client upload logic):
```bash
npm run test:platform
```

### 2. Manual End-to-End Ingestion Flow
1. Start the platform server:
   ```bash
   node offlineReport/platform/server.js
   # Server runs on http://localhost:4100
   ```
2. Ingest a JUnit XML report by making a `POST` request to `/api/v1/ingest`:
   ```bash
   # Using curl to upload a sample xml
   curl -X POST -H "Content-Type: application/xml" -H "x-file-name: test_run.xml" -H "x-report-title: Enterprise Checkout Run" --data-binary @offlineReport/platform/sample.xml http://localhost:4100/api/v1/ingest
   ```
3. The server will return a JSON response containing the generated report ID:
   ```json
   { "id": "rep-abc123xyz", "url": "/r/rep-abc123xyz", "stats": { "total": 12, "passed": 6 } }
   ```
4. Access the hosted report in the browser at: `http://localhost:4100/r/rep-abc123xyz`.

---

## Install

```bash
pip install velvet-report                        # Python
npm install velvet-report --save-dev             # Node.js
# Java: dev.velvetreport:velvet-report:2.1.2 in pom.xml
```

---

## Testing Frameworks Integration & Reporting

VelvetReport acts as a modern, self-contained reporting system. While **test execution** runs your test scripts (performing assertions, API requests, and browser interactions), **test reporting** structures these outcomes into an easily readable, interactive dashboard containing diagnostics, logs, trends, and attachments.

---

### Python (pytest / Playwright) Integration

VelvetReport provides native, zero-config reporting for Python testing using `pytest`. The `velvet-report` pytest plugin automatically hooks into your tests to capture run telemetry and environment info.

#### 1. Why Reporting is Required
- **Analyze Failures**: Instantly pinpoint why a python browser or API test failed.
- **Diagnostics**: View duration, error stack traces, and system-under-test environments.
- **Evidence Collection**: Access screenshots and logs associated with failed tests.
- **CI/CD Insights**: Track execution trends over multiple builds using historical data.

#### 2. Prerequisites & Installation
Ensure you have Python **>= 3.8**. Install the required packages via `pip`:
```bash
# Install pytest, playwright, and the VelvetReport collector
pip install pytest pytest-playwright velvet-report

# Install browser binaries for Playwright
playwright install
```

#### 3. Reporting Configuration
VelvetReport is configured directly in your `pytest.ini` file at the root of your project:
```ini
[pytest]
# Direct pytest to output JUnit XML to the reports folder
addopts = --junitxml=reports/results.xml

# VelvetReport specific configurations
vReport_Title               = Playwright Python Suite
vReport_output              = reports
vReport_history             = reports/.history
vReport_open                = false
vReport_embed_max           = 2M
vReport_email_report_enable = false
```
* **vReport_Title**: Custom title shown in the report topbar.
* **vReport_output**: The directory where the final `velvetreport.html` is built (default: `reports`).
* **vReport_history**: History trend logs directory (default: `reports/.history`).
* **vReport_embed_max**: Limits the maximum file size (e.g. `2M` for 2 megabytes) of attachments embedded directly as base64 inside the offline HTML.

#### 4. Supported Capabilities
- **Execution Timings**: Timings of setup, call, and teardown test phases, including fixture overheads.
- **Worker/Platform Dist**: Track test distribution across multiple workers (when using `pytest-xdist`).
- **Assertion vs. Timeout Identification**: Auto-categorizes errors into Assertion, Timeout, Network, or Script.
- **Automatic Attachment Discovery (Playwright)**: On failed tests, VelvetReport automatically scans the Playwright `test-results/` directory, extracts screenshots, and encodes them directly into the report.
- **Manual Attachments**: Manually attach logs, videos, or screenshots in code:
  ```python
  import velvet_report.get_pytest_data as vr

  def test_homepage(page):
      page.goto("https://playwright.dev")
      # Add step metadata
      with vr.step("Capture screenshot"):
          vr.attach(page.screenshot(), name="home.png", mime="image/png")
  ```

#### 5. Run Tests and Generate Report
To run your test suite and automatically generate the VelvetReport HTML dashboard:
```bash
# Run pytest (VelvetReport executes as a plugin and compiles the HTML dashboard)
pytest
```
The report is generated at: **`reports/velvetreport.html`**

#### 6. Open the Report
Open the generated HTML dashboard file directly in any browser — no local server is required:
```bash
# On Windows
start reports/velvetreport.html

# On macOS
open reports/velvetreport.html
```
Click on any failed test in the suite tree to inspect step logs, stack traces, and embedded screenshots.

#### 7. Customization Options
- **Command Line Overrides**:
  ```bash
  pytest --vReport-title "Staging Regression Run" --vReport-output custom-reports --vReport-open
  ```
- **Filter and Search**: The UI supports full tag filters (e.g. `@smoke`, `@regression`), text search, and test status toggles.

#### 8. CI/CD Usage
In CI/CD (such as GitHub Actions), run tests, archive the generated HTML report, and review the dashboard in pipeline artifacts.
```yaml
# .github/workflows/test.yml snippet
- name: Run Pytest Suite
  run: pytest
- name: Archive Test Report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: velvetreport
    path: reports/velvetreport.html
```

---

## Why VelvetReport?

| | VelvetReport | Allure | pytest-html |
|---|:---:|:---:|:---:|
| Works fully **offline** | ✅ | ⚠️ needs `allure serve` | ✅ |
| **Zero server / single file** | ✅ one `.html` | ❌ static site + server | ✅ |
| **Zero config** (pytest) | ✅ | ⚠️ decorators + CLI | ⚠️ flags |
| Any JUnit XML (any language) | ✅ | ⚠️ adapters | ❌ pytest only |
| History & flaky trends built in | ✅ | ⚠️ plugin | ❌ |
| Marks · fixtures · steps · screenshots · xdist workers | ✅ auto | ✅ manual | partial |

---

## Report Features

### Metrics & KPIs
- **12 KPI cards** — Total, Passed, Failed, Errors, Skipped, Rerun, Pass Rate, Avg Test Time, Total Duration, Stability Score (0–100), Flaky %, Failure Reproducibility — animated count-up on view
- **Risk badge** — STABLE / UNSTABLE / HIGH RISK
- Click any KPI card → modal listing the exact test cases behind it

### Test Details
- Expandable suite tree with per-test tabs: **Summary** (phases/fixtures/reason), **Stack Trace**, **Run History**, **Logs**, **Tags** (marks + steps), **Screenshots**, **Attachments**
- **Run history** — per-run status, duration, date/time, failure reason, screenshot — mapped correctly by file + test name
- **FLAKY badge** — auto-detected vs previous runs
- Live search + filter (All / Passed / Failed / Skipped / Flaky)

### Visual Analysis
- **Test Execution Timeline** — animated per-test bars
- **Mind Map** — Root → Suite → Describe → Test, clickable nodes open full detail
- **Failure Analysis** — auto-classified: Assertion / Timeout / Network / Script, with screenshot preview in modal
- **Result Heatmap**, **Individual Test History Cards**

### Charts
Pass/Fail donut · Duration histogram · Volume & Outcome Trends · Duration Trends · Duration by Spec File · Duration by Describe Block · **Test Distribution by Worker** (with total time) · Browser Distribution · Top 10 Slowest · Suite Health

### pytest auto-capture (new in 2.1)
- **Environment** — OS, Python, CI vars, git branch/commit, package versions
- **Marks & params** → tags panel (xdist-safe)
- **Phases** — setup / call / teardown timings + **fixture (before/after) costs**
- **Steps** — `velvet_report.step("...")`
- **Screenshots/videos** — explicit `attach()` or auto-discovered on failure
- **xdist** — per-worker distribution + total time
- Every field optional — absent data is hidden, report stays identical for XML-only users

### History & Export
- Auto-saved to `.history/` — up to 30 runs, full detail per test; commit to git for team trends
- Tags panel with multi-select filter
- Export HTML / CSV / JSON / **Email HTML** summary

---

## Configuration Reference (Python)

| Key | CLI flag | Default | Description |
|-----|----------|---------|-------------|
| `vReport_Title` | `--vReport-title` | XML filename | Report title |
| `vReport_output` | `--vReport-output` | `reports` | Output folder |
| `vReport_history` | `--vReport-history` | `reports/.history` | History folder |
| `vReport_xml` | `--vReport-xml` | auto | JUnit XML path |
| `vReport_open` | `--vReport-open` | `false` | Auto-open browser |
| `vReport_disable` | `--vReport-disable` | `false` | Skip generation |
| `vReport_capture` | — | `auto` | pytest auto-capture: `auto` \| `off` |
| `vReport_embed_max` | — | `2M` | Max attachment size to embed |
| `vReport_email` / `vReport_email_report_enable` | `--vReport-email` | `false` | Email-ready HTML summary |

### Node.js CLI
```
velvet-report generate <xml> [output] [--title text] [--history dir] [--open]
velvet-report clear-history [dir]
velvet-report info
```

---

## Architecture — One Change, All Platforms

```
core/src/template-parts/          ← Modular HTML / CSS / browser runtime
core/src/parser.js                ← JUnit XML parser
core/src/history.js               ← History + email
core/packages/python/get_pytest_data/  ← pytest auto-capture plugin
        ↓
node scripts/build.js             ← Compiles to all 3 platforms + 25 self-tests
        ↓
packages/pip → PyPI   packages/npm → npm   packages/maven → Maven Central
```

**Making changes:**
```bash
# Edit core/src/... (never hand-edit packages/*)
node scripts/build.js --verify    # rebuild all platforms + run 25 self-tests
```

Contributing? See [CONTRIBUTING.md](CONTRIBUTING.md) — small files, `FIX:` headers, easy to extend.

---

## Supported Frameworks

pytest · Playwright · Robot Framework · Jest · Cypress · Mocha · JUnit 5 · TestNG · Maven Surefire · Gradle · RSpec · PHPUnit · gotestsum · xUnit · NUnit · and any tool that outputs JUnit XML.

---

## Support the Project & Donate

If VelvetReport helps you or your team build and debug faster, please consider supporting the project. Your contributions directly help us maintain the library and reach our target of **10M+ downloads/users**!

[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-ffdd00?style=flat-square&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/YOUR_USERNAME)
[![Sponsor on GitHub](https://img.shields.io/badge/Sponsor%20on%20GitHub-Donate-ff69b4?style=flat-square&logo=github-sponsors&logoColor=white)](https://github.com/sponsors/YOUR_GITHUB_USERNAME)

- ☕ **[Buy Me a Coffee](https://buymeacoffee.com/YOUR_USERNAME)**: A fast, simple way to show support.
- 💖 **[Sponsor on GitHub](https://github.com/sponsors/YOUR_GITHUB_USERNAME)**: Fund ongoing maintenance and feature development.
- ⭐ **Star the Repository**: Help increase the project's visibility to reach a larger developer community.

---

## License

MIT © VelvetReport Contributors

---

*Keywords: junit xml report generator, html test report, pytest html report, pytest allure alternative, playwright test report, jest html reporter, cypress report, offline html test report, self-contained test report, CI test dashboard, test history tracking, flaky test detection, xdist report, python test report, junit 5 report, maven surefire report*
