Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jest-community/jest-junit

A Jest reporter that creates compatible junit xml files
https://github.com/jest-community/jest-junit

javascript jest jest-junit jest-testresultsprocessor junit nodejs

Last synced: about 2 months ago
JSON representation

A Jest reporter that creates compatible junit xml files

Host: GitHub
URL: https://github.com/jest-community/jest-junit
Owner: jest-community
License: apache-2.0
Created: 2016-11-18T23:33:59.000Z (almost 8 years ago)
Default Branch: master
Last Pushed: 2024-04-11T00:19:56.000Z (5 months ago)
Last Synced: 2024-04-14T05:09:43.891Z (5 months ago)
Topics: javascript, jest, jest-junit, jest-testresultsprocessor, junit, nodejs
Language: JavaScript
Homepage:
Size: 676 KB
Stars: 474
Watchers: 6
Forks: 106
Open Issues: 16
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-jest - jest-junit

README

        [![Actions Status](https://github.com/jest-community/jest-junit/actions/workflows/nodejs.yml/badge.svg?branch=master)](https://github.com/jest-community/jest-junit/actions)

# jest-junit

A Jest reporter that creates compatible junit xml files

Note: as of jest-junit 11.0.0 NodeJS >= 10.12.0 is required.

## Installation

```shell

yarn add --dev jest-junit

```

## Usage

In your jest config add the following entry:

```JSON

{

  "reporters": [ "default", "jest-junit" ]

}

```

Then simply run:

```shell

jest

```

For your Continuous Integration you can simply do:

```shell

jest --ci --reporters=default --reporters=jest-junit

```

## Usage as testResultsProcessor (deprecated)

The support for `testResultsProcessor` is only kept for [legacy reasons][test-results-processor] and might be removed in the future.

You should therefore prefer to configure `jest-junit` as a _reporter_.

Should you still want to, add the following entry to your jest config:

```JSON

{

  "testResultsProcessor": "jest-junit"

}

```

Then simply run:

```shell

jest

```

For your Continuous Integration you can simply do:

```shell

jest --ci --testResultsProcessor="jest-junit"

```

## Configuration

`jest-junit` offers several configurations based on environment variables or a `jest-junit` key defined in `package.json` or a reporter option.

Environment variable and package.json configuration should be **strings**.

Reporter options should also be strings exception for suiteNameTemplate, classNameTemplate, titleNameTemplate that can also accept a function returning a string.

| Environment Variable Name | Reporter Config Name| Description | Default | Possible Injection Values

|---|---|---|---|---|

| `JEST_SUITE_NAME` | `suiteName` | `name` attribute of `` | `"jest tests"` | N/A

| `JEST_JUNIT_OUTPUT_DIR` | `outputDirectory` | Directory to save the output. Relative path outside of project root (e.g. in monorepos) has to be prefixed with `` literal, e.g. `/../coverage` | `process.cwd()` | N/A

| `JEST_JUNIT_OUTPUT_NAME` | `outputName` | File name for the output. | `"junit.xml"` | N/A

| `JEST_JUNIT_OUTPUT_FILE` | `outputFile` | Fullpath for the output. If defined, `outputDirectory` and `outputName` will be overridden | `undefined` | N/A

| `JEST_JUNIT_UNIQUE_OUTPUT_NAME` | `uniqueOutputName` | Create unique file name for the output leveraging the `outputName` as a prefix if given `${outputName}-${uuid}.xml` or a default of `junit.xml-${uuid}.xml` if `outputName` is not specified, overrides `outputName` | `false` | N/A

| `JEST_JUNIT_SUITE_NAME` | `suiteNameTemplate` | Template string for `name` attribute of the ``. | `"{title}"` | `{title}`, `{filepath}`, `{filename}`, `{displayName}`

| `JEST_JUNIT_CLASSNAME` | `classNameTemplate` | Template string for the `classname` attribute of ``. | `"{classname} {title}"` | `{classname}`, `{title}`, `{suitename}`, `{filepath}`, `{filename}`, `{displayName}`

| `JEST_JUNIT_TITLE` | `titleTemplate` | Template string for the `name` attribute of ``. | `"{classname} {title}"` | `{classname}`, `{title}`, `{filepath}`, `{filename}`, `{displayName}`

| `JEST_JUNIT_ANCESTOR_SEPARATOR` | `ancestorSeparator` | Character(s) used to join the `describe` blocks. | `" "` | N/A

| `JEST_JUNIT_ADD_FILE_ATTRIBUTE` | `addFileAttribute` | Add file attribute to the output (validated on CIRCLE CI and GitLab CI). Must be a string. | `"false"` | N/A

| `JEST_JUNIT_FILE_PATH_PREFIX` | `filePathPrefix` | Prefix to add to the test suite file path. The value will be prefixed using `path.join`. Useful in case of monorepo | `""` | N/A

| `JEST_JUNIT_INCLUDE_CONSOLE_OUTPUT` | `includeConsoleOutput` | Adds console output to any testSuite that generates stdout during a test run. | `false` | N/A

| `JEST_JUNIT_INCLUDE_SHORT_CONSOLE_OUTPUT` | `includeShortConsoleOutput` | Adds short console output (only message value) to any testSuite that generates stdout during a test run. | `false` | N/A

| `JEST_JUNIT_REPORT_TEST_SUITE_ERRORS` | `reportTestSuiteErrors` | Reports test suites that failed to execute altogether as `error`. _Note:_ since the suite name cannot be determined from files that fail to load, it will default to file path.| `false` | N/A

| `JEST_JUNIT_NO_STACK_TRACE` | `noStackTrace` | Omit stack traces from test failure reports, similar to `jest --noStackTrace` | `false` | N/A

| `JEST_USE_PATH_FOR_SUITE_NAME` | `usePathForSuiteName` | **DEPRECATED. Use `suiteNameTemplate` instead.** Use file path as the `name` attribute of `` | `"false"` | N/A

| `JEST_JUNIT_TEST_CASE_PROPERTIES_JSON_FILE` | `testCasePropertiesFile` | Name of the custom testcase properties file | `"junitProperties.js"` | N/A

| `JEST_JUNIT_TEST_CASE_PROPERTIES_DIR` | `testCasePropertiesDirectory` | Location of the custom testcase properties file | `process.cwd()` | N/A

| `JEST_JUNIT_TEST_SUITE_PROPERTIES_JSON_FILE` | `testSuitePropertiesFile` | Name of the custom testsuite properties file | `"junitTestCaseProperties.js"` | N/A

| `JEST_JUNIT_TEST_SUITE_PROPERTIES_DIR` | `testSuitePropertiesDirectory` | Location of the custom testsuite properties file | `process.cwd()` | N/A

You can configure these options via the command line as seen below:

```shell

JEST_SUITE_NAME="Jest JUnit Unit Tests" JEST_JUNIT_OUTPUT_DIR="./artifacts" jest

```

Or you can also define a `jest-junit` key in your `package.json`.  All are **string** values.

```

{

  ...

  "jest-junit": {

    "suiteName": "jest tests",

    "outputDirectory": ".",

    "outputName": "junit.xml",

    "uniqueOutputName": "false",

    "classNameTemplate": "{classname}-{title}",

    "titleTemplate": "{classname}-{title}",

    "ancestorSeparator": " › ",

    "usePathForSuiteName": "true"

  }

}

```

Or you can define your options in your reporter configuration.

```js

// jest.config.js

{

  reporters: [

    "default",

    [ "jest-junit", { suiteName: "jest tests" } ]

  ]

}

```

### Configuration Precedence

If using the `usePathForSuiteName` and `suiteNameTemplate`, the `usePathForSuiteName` value will take precedence. ie: if `usePathForSuiteName=true` and `suiteNameTemplate="{filename}"`, the filepath will be used as the `name` attribute of the `` in the rendered `jest-junit.xml`).

### Examples

Below are some example configuration values and the rendered `.xml` to created by `jest-junit`.

The following test defined in the file `/__tests__/addition.test.js` will be used for all examples:

```js

describe('addition', () => {

  describe('positive numbers', () => {

    it('should add up', () => {

      expect(1 + 2).toBe(3);

    });

  });

});

```

#### Example 1

The default output:

```xml

  

    

    

  

```

#### Example 2

Using the `classNameTemplate` and `titleTemplate`:

```shell

JEST_JUNIT_CLASSNAME="{classname}" JEST_JUNIT_TITLE="{title}" jest

```

renders

```xml

  

    

    

  

```

#### Example 3

Using the `ancestorSeparator`:

```shell

JEST_JUNIT_ANCESTOR_SEPARATOR=" › " jest

```

renders

```xml

  

    

    

  

```

#### Example 4

Using the `suiteNameTemplate`:

```shell

JEST_JUNIT_SUITE_NAME ="{filename}" jest

```

```xml

  

    

    

  

```

#### Example 5

Using `classNameTemplate` as a function in reporter options

```js

// jest.config.js

{

  reporters: [

    "default",

      [

        "jest-junit",

        {

          classNameTemplate: (vars) => {

            return vars.classname.toUpperCase();

          }

        }

      ]

  ]

}

```

renders

```xml

  

    

    

  

```

#### Adding custom testsuite properties

New feature as of jest-junit 11.0.0!

Create a file in your project root directory named junitProperties.js:

```js

module.exports = () => {

  return {

    key: "value",

  };

};

```

Will render

```xml

  

    

      

    

    

    

  

```

#### Adding custom testcase properties

Create a file in your project root directory named junitTestCaseProperties.js:

```js

module.exports = (testResult) => {

  return {

    "dd_tags[test.invocations]": testResult.invocations,

  };

};

```

Will render

```xml

  

    

      

        

      

    

  

```

WARNING: Properties for testcases is not following standard JUnit XML schema.

However, other consumers may support properties for testcases like [DataDog metadata through `` elements](https://docs.datadoghq.com/continuous_integration/tests/junit_upload/?tab=jenkins#providing-metadata-through-property-elements)

[test-results-processor]: https://github.com/jest-community/jest-junit/discussions/158#discussioncomment-392985