junit2report 1.0.0

CLI tool and library to convert JUnit XML test results into human-readable HTML dashboards

JUnit To Report Generator

junit2report is a lightweight, zero-dependency Python tool that converts JUnit XML test reports into human-readable, static HTML dashboards.

Perfect for CI/CD pipelines, local debugging, or sharing test results with stakeholders.

🚀 Key Features

• Simple Conversion: Turn complex XML into a clean, responsive HTML file in seconds.
• 🎨 Multiple Templates: Choose from built-in themes (Dark mode, Minimal, etc.) to suit your preferences.
• CI/CD Ready: Seamlessly integrates with Jenkins, GitHub Actions, GitLab CI, and CircleCI.
• Detailed Insights: View pass/fail rates, execution times, and capture stdout/stderr logs.
• Dual Mode: Use it as a CLI tool or import it as a Python library.

📦 Installation

Install the package via pip:

pip install junit2report

🛠 Usage

Command Line Interface (CLI) Basic conversion (uses default template):

junit2report report.xml -o output.html

Using a specific template:

junit2report report.xml -o output.html --template dark

Setting a custom title:

junit2report report.xml -o output.html --template legacy --title "Nightly Run"

List available templates:

junit2report --list-templates

Generating analytics reports (in addition to the main report):

junit2report report.xml -o output.html --allow-analytics

This generates both output.html (main report) and output-analytics.html (analytics dashboard with charts and filters).

Python Library You can integrate the generator directly into your Python scripts.

from junit_report_generator import create_report

# Convert with a specific template
create_report(
    source="results.xml", 
    output="dashboard.html", 
    template="dark",
    title="Nightly Run"
)

# or using a string of XML data
with open("results.xml", "r") as f:
    xml_data = f.read()
    html_content = create_report(xml_string=xml_data, template="minimal")

🎨 Available Templates

The package comes with several pre-built templates to customize your report style.

Template Name	Description	Best For
modern	(Default) A clean, colorful dashboard with charts and collapsible sections.	General use, stakeholder reports.
dark	A high-contrast dark theme version of the modern dashboard.	Late-night debugging, dark-mode lovers.
minimal	A text-heavy, high-density layout with no charts and only minimal inline JavaScript for basic filtering/collapsing.	Large test suites (10k+ tests), slow connections that still allow basic interactivity.
legacy	A simple table view similar to older Jenkins reports.	Backward compatibility.
analytics	Advanced analytics dashboard with multi-axis charts, performance insights, and interactive filters.	In-depth performance analysis, identifying bottlenecks.

📸 Template Previews

Modern (Default)	Dark
Minimal	Legacy
Analytics

📊 Example Output

The generated HTML report includes:

• Summary Cards: Total tests, passed, failed, skipped, and total duration.
• Test Cases Table: Sortable list of all test cases with status indicators.
• Failure Details: Expandable sections showing stack traces and error messages.

Analytics Dashboard (--allow-analytics)

The analytics report provides advanced insights:

• Interactive Charts: Status distribution, test count by class, execution time by class, failure distribution, and pass rate visualization.
• Performance Metrics: Detailed breakdown of test execution by class with averages and statistics.
• Error Analysis: Deduplicated error messages with frequency counts and affected tests.
• Top Tests: Slowest and fastest tests ranked by execution time.
• Filterable Sections: Use "Show top N" filters in Performance by Class and Error Analysis sections to focus on the most relevant data.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

1. Clone the repository

   </code></pre>
   </li>
   </ol>
   <p>git clone <a href="https://github.com/gorkalertxundi/junit2report.git">https://github.com/gorkalertxundi/junit2report.git</a>
   cd junit2report</p>
   <pre><code>
   2. **Install in editable mode**
   ```bash
   pip install -e .
   

   This installs the package in development mode, allowing you to make changes to the source code and test them immediately without reinstalling.

   3. Verify the installation

      </code></pre>
      </li>
      </ol>
      <h1>Check that the CLI is available</h1>
      <p>junit2report --list-templates</p>
      <h1>Verify templates are bundled correctly</h1>
      <p>python -c "from junit2report import get_available_templates; print(get_available_templates())"</p>
      <pre><code>
      ### Running Tests
      
      Run the test suite to ensure everything works correctly:
      
      ```bash
      # Run all tests
      python -m unittest discover tests
      
      # Run tests with verbose output
      python -m unittest discover tests -v
      
      # Run a specific test
      python -m unittest tests.test_parser.TestJUnitParser.test_parse_single_testsuite
      

      All tests should pass before submitting a pull request.

      Testing Locally

      1. Generate a test report

         </code></pre>
         </li>
         </ol>
         <h1>Use the provided sample file</h1>
         <p>junit2report sample-test-results.xml -o test-report.html</p>
         <h1>Try different templates</h1>
         <p>junit2report sample-test-results.xml -o dark-report.html --template dark
         junit2report sample-test-results.xml -o minimal-report.html --template minimal</p>
         <pre><code>
         2. **Test the Python API**
         ```python
         from junit2report import create_report
         
         # Test with file
         create_report(source="sample-test-results.xml", output="api-test.html")
         
         # Test with XML string
         with open("sample-test-results.xml") as f:
             html = create_report(xml_string=f.read(), template="dark")
             print(f"Generated {len(html)} bytes of HTML")
         

         3. Test template bundling

            # Build the package
            python -m build
            

         Check that templates are included

         tar -tzf dist/junit2report-*.tar.gz | grep templates

         
         ### Adding a New Template
         
         1. Create your template file in `junit2report/templates/yourtemplate.html`
         2. Use Jinja2 syntax with these variables:
         - `{{ summary.total }}`, `{{ summary.passed }}`, `{{ summary.failed }}`, etc.
         - `{{ summary.pass_rate }}` for the percentage
         - `{% for test in test_cases %}` to iterate through tests
         - `{{ test.name }}`, `{{ test.status }}`, `{{ test.message }}`, `{{ test.output }}`
         3. Test your template: `junit2report sample-test-results.xml --template yourtemplate`
         4. The template will automatically appear in `--list-templates`
         
         ### Contribution Workflow
         
         1. Fork the repository
         2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
         3. Make your changes and test thoroughly
         4. Run the test suite to ensure nothing broke
         5. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
         6. Push to the branch (`git push origin feature/AmazingFeature`)
         7. Open a Pull Request with a clear description of your changes
         
         ## 📄 License
         Distributed under the MIT License. See LICENSE for more information.