npm package: @fase-engineering/test360
Description: A simple project to generate a website from .xml test reports.
Author: Fabian Sernatinger
Latest version: 0.2.5

# Test360

Test360 is a simple, lightweight Node.js CLI tool written in TypeScript that generates beautiful, interactive static HTML websites from XML test and coverage reports. It supports JUnit-style and Jest XML reports as well as Cobertura coverage XML, producing professional, navigable pages for browsing test results and code coverage with comprehensive breadcrumb navigation and theme support.

> **Perfect for CI/CD pipelines, development teams, and anyone who wants to transform raw XML reports into professional, shareable HTML reports.**

**Note that the major part of this project was implemented by AI.**

## Features

- **Multiple Input Methods**: Scan directories or specify exact files
- **Flexible CLI Interface**: Support for both directory scanning and specific file targeting
- **Dark/Light Theme Support**: Toggle between dark, light, and system-default themes with persistent preferences
- Parse JUnit-compatible reports via [`src/parsers/junitParser.ts`](src/parsers/junitParser.ts)
- Parse Jest JUnit-style reports via [`src/parsers/jestParser.ts`](src/parsers/jestParser.ts)
- Parse Cobertura coverage XML via [`src/parsers/coberturaParser.ts`](src/parsers/coberturaParser.ts)
- **Interactive Navigation**: Full breadcrumb navigation across all report levels
- **Smart Test Sorting**: Failed tests automatically appear first for immediate attention
- Generate:
  - A landing page with overall test & coverage summaries
  - A hierarchical directory tree of unit tests (`unittests/`)
  - File-level and test-case pages with sortable tables
  - Coverage overview, package, and class pages (`coverage/`)
  - Professional breadcrumb navigation throughout the site

## Use Cases

Test360 is perfect for:

- **CI/CD Pipelines**: Generate HTML reports as build artifacts
- **Development Teams**: Share test results with team members who don't have access to CI/CD systems
- **Project Documentation**: Archive test results for compliance or historical analysis
- **Client Presentations**: Create professional reports to demonstrate code quality
- **Local Development**: Quickly visualize test results during development

## Requirements

- Node.js 14.x or higher
- npm or yarn package manager

## Installation

Install Test360 globally:

```sh
npm install -g @fase-engineering/test360
```

Or use it as a development dependency:

```sh
npm install --save-dev @fase-engineering/test360
```

For development or contribution:

```sh
git clone https://github.com/your-repo/test360.git
cd test360
npm install
npm run build
```

## Usage

### Basic Usage

Generate the site into `./www` (default):

```sh
# If installed globally
test360

# If using npm scripts (in project with Test360 as dependency)
npm run report

# Or directly with npx
npx test360
```

### Directory-based Usage

Specify an output directory:

```sh
test360 --output ./my-output
# or with npm script: npm run report -- --output ./my-output
```

Specify an input (reports) directory:

```sh
test360 --input ./my-reports
# or with npm script: npm run report -- --input ./my-reports
```

Specify both input and output:

```sh
test360 --input ./my-reports --output ./my-output
# or with npm script: npm run report -- --input ./my-reports --output ./my-output
```

### Specific File Usage

You can specify exact report files instead of scanning directories:

```sh
# Specify specific JUnit report
test360 --junit-report ./path/to/junit-results.xml

# Specify specific Jest report
test360 --jest-report ./path/to/jest-results.xml

# Specify specific coverage report
test360 --coverage-report ./path/to/coverage-results.xml

# Combine specific files
test360 --junit-report ./junit.xml --coverage-report ./coverage.xml

# Mix with output directory
test360 --junit-report ./junit.xml --output ./build
```

### Command Line Options

```sh
test360 [options]

Options:
  --output <dir>           Output directory for generated HTML (default: ./www)
  --input <dir>            Input directory to scan for reports (default: ./reports)
  --junit-report <file>    Specific JUnit XML report file
  --jest-report <file>     Specific Jest XML report file
  --coverage-report <file> Specific Cobertura coverage XML file
  --help, -h               Show help message
```

### Report Detection (Directory Mode)

When using directory scanning mode, report filenames must contain:

- the word `junit` for unit test XML reports (e.g., `junit-report.xml`)
- the word `coverage` for coverage XML reports (e.g., `coverage-report.xml`)

**Note**: When specific report files are provided via CLI arguments, they take precedence over directory scanning. File paths can be absolute or relative to the current working directory.

## Configuration

- **Base path to ignore in file paths**: Configure in [`src/config.ts`](src/config.ts) (default: `"tests"`)
- **Coverage thresholds**: Define low/high coverage thresholds in [`src/config.ts`](src/config.ts)
  - `low: 0.5` (50% - red indicator)
  - `high: 1.0` (100% - green indicator)

## Theme Support

Test360 includes built-in theme support for better readability in different environments:

- **🖥️ System Default**: Automatically follows your OS theme preference
- **☀️ Light Mode**: Clean, bright interface ideal for well-lit environments
- **🌙 Dark Mode**: Easy on the eyes for low-light conditions

The theme toggle appears in the top-right corner of every page. Your preference is saved in the browser's localStorage and persists across sessions. The theme system includes:

- Optimized color schemes for both themes
- Smooth transitions between themes
- Separate logo variants for light and dark modes
- Consistent styling across all report pages

## Navigation Features

Test360 provides comprehensive navigation throughout the generated site:

- **Theme Switching**: Toggle between dark, light, and system-default themes with one click
- **Breadcrumb Navigation**: Always know where you are and navigate back easily
- **Hierarchical Structure**: Browse from overview → directories → files → individual tests
- **Visual Indicators**: Color-coded status indicators for failed tests and coverage levels
- **Smart Sorting**: Failed tests automatically appear first; additional sorting by name, status, duration, etc.
- **Sortable Tables**: Click column headers to sort test results with secondary alphabetical ordering
- **Professional Styling**: Clean, modern interface with consistent navigation patterns
- **Persistent Preferences**: Theme selection is saved in browser localStorage

## Output Structure

After running, your output directory will contain:

```sh
./www/                             # Default output directory
├── index.html                     # Landing page with overall summaries
├── styles.css                     # Shared stylesheet with CSS variables
├── theme.js                       # Theme switching JavaScript
├── favicon.png                    # Site favicon
├── logo_white.png                 # Logo for dark theme
├── logo_black.png                 # Logo for light theme
├── unittests/                     # Unit test results section
│   ├── index.html                # Unit tests root (with breadcrumbs: Home → Unit Tests)
│   ├── theme.js                  # Theme switching JavaScript (copy)
│   ├── dir-*.html                # Directory-level pages
│   ├── file-*.html               # File-level test pages
│   └── test-*.html               # Individual test case pages
└── coverage/                      # Coverage reports section
    ├── coverage-overview.html     # Coverage summary (with breadcrumbs: Home → Coverage)
    ├── theme.js                   # Theme switching JavaScript (copy)
    ├── cov-package-*.html         # Package-level coverage
    └── cov-class-*.html          # Class-level coverage details
```

## Version History

### v0.2.5 (Latest)

- **NEW**: Dark/Light theme support with system-default option
- **NEW**: Smart test sorting - failed tests automatically appear first
- **NEW**: Theme persistence using browser localStorage
- **IMPROVED**: CSS variables for consistent theming
- **IMPROVED**: Secondary alphabetical sorting in test tables
- **IMPROVED**: Responsive theme toggle UI with visual indicators

### v0.2.0

- _NEW_: CLI support for specifying exact report files
- _NEW_: Comprehensive breadcrumb navigation throughout the site
- _NEW_: Professional help system (`--help`)
- _IMPROVED_: Better error handling and file validation
- _IMPROVED_: Enhanced logging and user feedback
- _FIXED_: Unit test parsing and display issues

### v0.1.0

- Initial release with directory-based report scanning
- Support for JUnit, Jest, and Cobertura reports
- Basic HTML report generation

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

### Development Setup

1. Fork the repository
2. Clone your fork: `git clone https://github.com/your-username/test360.git`
3. Install dependencies: `npm install`
4. Make your changes
5. Run tests: `npm test` (if available)
6. Build the project: `npm run build`
7. Generate sample reports: `npm run report`
8. Submit a pull request

## License

MIT License - see the [LICENSE](LICENSE) file for details.

## Author

Fabian Sernatinger

## Support

For issues, questions, or suggestions, please open an issue on the GitHub repository.