junit-converter/README.md

Test report files to JUnit XML converter

## Test report files to JUnit converter

[![Actions Status][github-img]][github-url]
[![Git Issues][issues-img]][issues-url]
[![Closed Issues][closed-issues-img]][closed-issues-url]

[//]: # ([![Codacy Badge][codacy-img]][codacy-url])

### Overview

- Convert test report files to JUnit format.

### Supported report formats

- JUnit/xUnit XML Format  
- NUnit v3+ XML Format  
- xUnit.net v2+ XML Format  
- MSTest TRX Format (this is default `dotnet test` report output)  
- CTRF JSON  

### Conversion process

 - All test reports except CTRF are first converted to JUnit format using XSLT.
 - Any nested test suites are flattened.
 - TRX files undergo additional processing to enhance JUnit output.
 - CTRF reports are converted to custom JSON format and transformed to XML.

### JUnit

- Flattens any nested test suites.

### NUnit

- NUnit v3+ XML is supported.
- Converts <properties> to JUnit <properties>.
- Converts <output> to JUnit <system-out>.
- Converts skipped `test-case` <reason> to JUnit <skipped> with message.
- Converts `test-case` <failure> to JUnit <failure> with message and stack trace.

### xUnit.net  

- xUnit.net v2+ XML is supported.
- Converts <traits> to JUnit <properties>.
- Converts skipped `test` <reason> to JUnit <skipped> with message.
- Converts `test` <failure> to JUnit <failure> with message and stack trace.
- Supports single <assembly> per file, if multiple assemblies are present, only the first will be converted.

### MSTest (dotnet test) TRX

`dotnet test` generates TRX style files unless different logger is used.

- Converts `Output/ErrorInfo/ErrorInfo` to JUnit <failure> with message.
- Converts `Output/ErrorInfo/Message` to JUnit <failure> message.
- Converts `Output/ErrorInfo/StackTrace` to JUnit <failure> stack trace.
- Converts `Output/StdOut` to JUnit <system-out>.
- Converts `Output/StdErr` to JUnit <system-err>.
- Converts Inconclusive and NotExecuted tests to <skipped> with message.
- Tests are split into multiple <testsuite> elements by test classname.
- Tests are ordered by name.
- Test suit times are not 100% accurate - displayed as a sum() of all test times.  

### CTRF

- Converts `parameters` to JUnit <properties>
- Converts `stdout` to JUnit <system-out>.
- Converts `stderr` to JUnit <system-err>.
- Converts `message` and `trace` to JUnit <failure> message with stack trace.  

### Usage

```bash
npm i --save-dev junit-converter
```

```js
const converter = require('junit-converter');

let options = {
    testFile: 'mytesfiles/nunit.xml',
    testType: 'nunit'
}

// Convert test report to JUnit format and save to file
// Set minify:true to save minified XML
converter.toFile(options).then(() => console.log(`JUnit report created`));

// Convert test report to JUnit format and return as 'pretty' XML string
// Set minify:true to return minified XML string
converter.toString(options).then((result) =>{/*do something with result*/});

// Convert test report to JUnit format and return as JSON object for processing
converter.toJson(options).then((result) =>{/*do something with result*/});
```

### CLI via NPX

```bash
npx --yes junit-converter --testFile mytests/nunit.xml --testType nunit 
```

### CLI using global module

```bash
npm i -g junit-converter
junit-converter --testFile mytests/nunit.xml --testType nunit
```


### Options

| Option                    | Type    | Default                   | Description                                       |
|:--------------------------|:--------|:--------------------------|:--------------------------------------------------|
| `testFile` **(required)** | string  |                           | Path to test file for conversion                  |
| `testType` **(required)** | string  |                           | [Test report type](#supported-testtype-options)   |
| `reportDir`               | string  | ./report                  | Converted report output path when saving file     |
| `reportFile`              | string  | `testFile.name`-junit.xml | JUnit report file name                            |
| `splitByClassname`        | boolean | false                     | Split into multiple test suites by test classname |
| `minify`                  | boolean | false                     | Minify XML result                                 |

- `testFile` - relative or absolute path to input test file.  

- `testType` - type of test report, not case-sensitive.  

- `reportDir` - will be created if path does not exist. Only used when saving to file.  

- `reportFile` - JUnit file name. Only used when saving to file.  

- `splitByClassname` - If true splits test cases into multiple test suites by classname.  
  This is useful for test runners that generate tests under a single test suite such as `dotnet test` when using JUnit loggers.  
  Should only be set to true if test report file contains single test suite.
  TRX report files are always split by classname, so this option is ignored for TRX files.  

#### Supported `testType` options.

| `testType` | File Type                  |
|:-----------|:---------------------------|
| JUnit      | JUnit/xUnit XML            |
| NUnit      | NUnit v3+ XML              |
| xUnit      | xUnit.net v2+ XML          |
| TRX        | MSTest TRX (`dotnet test`) |
| CTRF       | CTRF JSON                  |


[issues-img]: https://img.shields.io/github/issues-raw/agracio/junit-converter.svg?style=flat-square
[issues-url]: https://github.com/agracio/junit-converter/issues
[closed-issues-img]: https://img.shields.io/github/issues-closed-raw/agracio/junit-converter.svg?style=flat-square&color=brightgreen
[closed-issues-url]: https://github.com/agracio/junit-converter/issues?q=is%3Aissue+is%3Aclosed

[codacy-img]: https://app.codacy.com/project/badge/Grade/1b8b8f9fdbce4267bf779197141657a2
[codacy-url]: https://app.codacy.com/gh/agracio/junit-converter/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade

[github-img]: https://github.com/agracio/junit-converter/workflows/Test/badge.svg
[github-url]: https://github.com/agracio/edge-js/junit-converter/workflows/main.yml