allure-docx 0.4.0
Docx report generator based on allure-generated json files.
License: MIT

# allure-docx
DOCX and PDF report generation based on allure-generated result files.

## About
This package is developed in collaboration by [Typhoon Hil](https://www.typhoon-hil.com/) and the [Fraunhofer Institute for Solar Energy Systems ISE](https://www.ise.fraunhofer.de/). Users are welcome to test and report problems and suggestions by creating an issue. Note that the package is not officially supported by Typhoon HIL and is still on the alpha phase.


### Limitations

The generator was only tested so far using allure results from python with `allure-pytest` and java with `allure-junit5`. Therefore it expects a folder with `.json` files generated by the allure plugins.

Check the issues on the repository to see other current limitations.

### Questions

Feel free to open an issue ticket with any problems or questions. Please if possible provide your test result files so we can debug it more efficiently.

## Installation

The library uses matplotlib which depends on Visual C++ Redistributables. If not already installed, you can get them here: https://www.microsoft.com/en-in/download/details.aspx?id=48145 .

### Windows

We publish windows standalone executable files. With them you can use it without having to install anything else, meaning no installing python, etc.

You can download them at: https://github.com/typhoon-hil/allure-docx/releases

Then you can use the executable directly (possibly adding it a folder added to PATH).

### Linux and Windows

You can install from source using:

`pip install git+https://github.com/typhoon-hil/allure-docx.git`

Then you should be able to use `allure-docx` executable like you use `pip`.

## Usage

Check usage by running `allure-docx --help`

You can generate the docx file by running `allure-docx ALLUREDIR filename.docx`

### Configuration

Use the `--config_tag` / `--config_file` option to control which information should be added. Use the preset names or give a path to your custom .ini file. 
When using a custom configuration the standard configuration is used as base and is overwritten for each attribute inside the custom file. 
The standard file looks like this:
```
[info]
description = fbpsu
details = fbpsu
trace = fbpsu
parameters = fbpsu
links = fbpsu
setup = fbpsu
body = fbpsu
teardown = fbpsu
duration = fbpsu
attachments = fbpsu
[labels]
severity = fbpsu
[cover]
title = Allure
[details]
```

The report will display tests with the specified field (info and labels section) if the corresponding character is included. For mapping see following table:

| failed | broken | passed | skipped | unknown |
|--------|--------|--------|---------|---------|
| f      | b      | p      | s       | u       |

There are some additional information you can add to your report. This includes following:

<details>
    <summary style="font-weight: bold">Add custom labels</summary>

The allure engine allows for custom labels inside the test code. These are not printed on standard.
You can add a custom label under `[labels]` section to include it in the report. It will appear inside the label table directly below the test heading. 

Example:

```
[labels]
some_label = fbpsu
```
</details>
<details>
    <summary style="font-weight: bold">Add a company name to the cover</summary>

You can include a company name on the cover of the report by setting the `company_name` variable under the `[cover]` section. 

Example:
```
[cover]
company = Some company
```

</details>
<details>
    <summary style="font-weight: bold">Add custom details to the Test Details section</summary>

You can add custom variables inside the `[details]` section. These will be printed on the Test Details section of the document. 

Example:
```
[details]
Test name = Example Test
Device under test = Example device under test
Relevant documents = 
    Document abc v1.5
    Document xyz v5.4
Description = This is a test description.
```
This will be printed as following table under Test Details:

|                        |                                         |
|------------------------|-----------------------------------------|
| **Test name**          | Example Test                            |
| **Device under test**  | Example device under test               |
| **Relevant documents** | Document abc v1.5<br/>Document xyz v5.4 |
| **Description**        | This is a test description.             |

Putting "Device under test" into the details section also adds the value to the header."

</details>


### Custom Title and Logo

You can use the `--title` option to customize the docx report title (or specify inside custom configuration file, as described above).
 
If you want to remove the title altogether (e.g. your logo already has the company title), you can set `--title=""`.

You can also use the `--logo` option with a path to a custom image to add the test title and the `--logo-width` option to adjust the width size of the logo image (in centimeters).

Example invocation:

`allure-docx --pdf --config_file=C:\myconfig.ini --logo=C:\mycompanylogo.png --logo-width=2 allure allure.docx`

### PDF

The `--pdf` option will search for either Word (Windows only) or `soffice` (LibreOffice) to generate the PDF.

If both Word and `soffice` are present, Word will be used.

## Previous versions

The previous version of the package can be found in the releases page of the plugin [here](https://github.com/typhoon-hil/allure-docx/releases).

## Miscelaneous
### Building the standalone executable

We use PyInstaller to create standalone executables. If you want to build an executable yourself, follow these steps:
- Create a new virtual environment with the proper python version (tested using python 3, 32 or 64 bit so far)
- Install using pip `pyinstaller` and ONLY needed packages defined in `setup.py`. This prevents your executable to become too large with unnecessary dependencies
- Delete any previous `dist` folder from a previous PyInstaller run
- Run the `build_exe.cmd` command to run PyInstaller and create a single file executable.

If having the following error:

`ImportError: This package should not be accessible on Python 3. Either you are trying to run from the python-future src folder or your installation of python-future is corrupted.`

Run `pip install --force-reinstall -U future` (https://github.com/nipy/nipype/issues/2646)