Metadata-Version: 2.4
Name: robotframework-testdoc
Version: 0.3.2a3
Summary: A CLI Tool to generate a Test Documentation for your RobotFramework Test Scripts.
Project-URL: Repository, https://github.com/MarvKler/robotframework-testdoc
Project-URL: Issues, https://github.com/MarvKler/robotframework-testdoc/issues
Author-email: Marvin Klerx <marvinklerx20@gmail.com>
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: click
Requires-Dist: jinja2
Requires-Dist: mkdocs
Requires-Dist: mkdocs-include-markdown-plugin
Requires-Dist: mkdocs-macros-plugin
Requires-Dist: mkdocs-material
Requires-Dist: pydantic
Requires-Dist: robotframework
Requires-Dist: tomli
Provides-Extra: dev
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: robotframework-robocop; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# Robot Framework TestDoc

## GitHub Project

Link to GitHub Project: [robotframework-testdoc](https://github.com/MarvKler/robotframework-testdoc)

## Statistics

[![Release Pipeline](https://github.com/MarvKler/robotframework-testdoc/actions/workflows/release.yml/badge.svg)](https://github.com/MarvKler/robotframework-testdoc/actions/workflows/release.yml)  
[![PyPI - Version](https://img.shields.io/pypi/v/robotframework-testdoc.svg)](https://pypi.org/project/robotframework-testdoc)   
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/robotframework-testdoc.svg)](https://pypi.org/project/robotframework-testdoc)    
[![PyPI Downloads - Total](https://static.pepy.tech/badge/robotframework-testdoc)](https://pepy.tech/projects/robotframework-testdoc)   
[![PyPI Downloads - Monthly](https://static.pepy.tech/badge/robotframework-testdoc/month)](https://pepy.tech/projects/robotframework-testdoc)   

## Installation

Install the tool using the following command:
```shell
pip install robotframework-testdoc
```

> [!IMPORTANT]
> Preconditions: Python & Pip Installation.

## Usage

### Basic Usage
```shell
testdoc suite_directory output.html
# or
testdoc suite_file output.html
```

### Extended Usage
```shell
testdoc [OPTIONS] suite_directory output.html
```

> [!TIP]
> **Included Help:** Please execute ``testdoc --help`` for further details about the commandline arguments or see the examples below.

### Plugin Usage

You can use the testdoc tool also as plugin integration.  
You have two option to use it this way:
1. You can write your own HTML page as ``jinja2`` template, add this HTML template as CLI argument while generating the docs and you will get your own HTML style as documentation page.
2. You can use the ``mkdocs`` integration to define your own mkdcs template as CLI argument and the testdoc tool will internally take care of the mkdocs page generation.

For further details about the usage, please read the [plugin usage documentation](./PLUGIN_USAGE.md).

## Examples

Below you can find some example of using the testdoc library.  

> [!TIP]
> Of course, you can combine all of them!

```shell
# Generating docu without option
testdoc tests/ TestDocumentation.html

# Generating docu with new title, new root suite name, new root suite documentation text & new metadata
testdoc -t "Robot Framework Test Automation" -n "System Tests" -d "Root Suite Documentation" -m "Root Suite Metadata" tests/ TestDocumentation.html

# Generating docu with source prefix to navigate directly to its gitlab file path
testdoc -s "https://gitlab.com/myrepository" tests/ TestDocumentation.html

# Generating docu only with specific mentioned tags to include & exclude 
testdoc -i ManagementUI -e LongTime tests/ TestDocumentation.html

# Generating docu only with multiple specific mentioned tags to include
testdoc -i ManagementUI -i MQTT tests/ TestDocumentation.html

# Generating docu only with new metadata for root suite object
testdoc -m Version=0.1.1-dev -m Tester=RobotExpert tests/ TestDocumentation.html

# Generating docu - hide tags information
testdoc --hide-tags tests/ TestDocumentation.html

# Generating docu - hide test case documentation texts
testdoc --hide-test-doc tests/ TestDocumentation.html

# Generating docu - hide test suite documentation texts
testdoc --hide-suite-doc tests/ TestDocumentation.html

# Generating docu - hide source information
testdoc --hide-source tests/ TestDocumentation.html

# Generating docu - hide keyword information (keyword calls in tests)
testdoc --hide-keywords tests/ TestDocumentation.html
```

## Visualization of Keywords

Keywords are visualized in a specific design and to replicate the robot framework test case structure (model) as best as possible.

### User / Library Keywords called in a Test Case Body

This view does actually replicate the robot framework suite file with the ``*** Test Cases ***`` section, the ``Test Case Name`` and the ``Test Case Body``.

![alt text](docs/test_keywords_visualization.png)

### User Keyword defined in a Test Suite

![alt text](docs/suite_keywords_visualization.png)

## Robot Framework Tags
The commandline arguments ``include`` & ``exclude`` have more or less the same functionality like in the known ``robot ...`` command.     
You can decide to weither include and / or exclude specific test cases into the test documentation.

## External Configuration File
The idea of the external configuration file is, having a central place for passing the known CMD arguments via file instead of CMD parameters.   
This will keep your CMD line call simple & clean.

For using this config file, just call the following command:
```shell
# Generate docu with options defined in TOML file
testdoc -c path/to/config.toml tests/ TestDocumentation.html
```

### pyproject.toml vs. custom toml file

Using the ``pyproject`` requires to define the ``testdoc`` sections with the prefix ``tool.``   
Example section start: ``[tool.testdoc]``

Using your own custom toml-file, does not require you to use the prefix. Here, you can just use ``[testdoc]`` as section header.


### Example Configuration File
```toml
[tool.testdoc]
title = "New title of HTML document"
name = "New name of root suite element"
doc = "New doc text of root suite element"
sourceprefix = "gitlab::https://gitlab.com/myrepo/repo_path"
include = ["TagA", "TagB"]
exclude = ["TagC"]
hide_tags = true
hide_test_doc = true
hide_suite_doc = true
hide_source = true
hide_keywords = true
style = "blue"
verbose_mode = false

[tool.testdoc.metadata]
Author = "Your-Name"
Version = "1.0.0"
Source = "AnySourceAsMetaData"

[tool.testdoc.colors]
# Use predefined theme:
default = "blue"
# OR
# Use custom colors:
background = "#000028"
inner_color = "#000028"
button_active_color = "#193966"
button_hover_color = "#193966"
border_color = "#CCCCCC"
text_color = "#CCCCCC"
title_color = "#00ffb9"
robot_icon = "#00ffb9"
code_area_background = "#303030"
code_area_foreground = "#f1f1f1"
```

## HTML Template Selection

You can choose between multiple HTML template for the design of your test documentation.    
These template can be configured via ``cli arguments`` or within a ``.toml configuration file`` with the parameter ``html_template (-ht / --html-template)``.

### Default Design

- v2

### Available HTML Templates - NOT RECOMMENDED

You can choose one of the following designs:
- v1
- v2

### Version 1

#### Visit Tests

![alt text](docs/html_v1_common.png)

### Version 2

#### Visit Tests on Root Suite Level

![alt text](docs/html_v2_root.png)

#### Visit Tests on Suite File Level

![alt text](docs/html_v2_suitefile.png)

## Theme Selection / Color Configuration

You can select between several themes (color configurations) for your HTML document to create!

> [!CAUTION]
> This is only possible via toml-configuration file, but not via cmd args directly!

### Default Themes

There are a few predefined default themes available that you can choose via the toml-configuration file OR cli.   
Therefore, please use the following syntax: for the toml file
```toml
[colors]
# Use the default theme
default = "default"
default = 0
# Use the dark theme
default = "dark"
default = 1
# Use the blue theme
default = "blue"
default = 2
# Use the robot theme
default = "robot"
default = 3
# Use the dark robot theme
default = "robot_dark"
default = 4
# Use the green theme
default = "green"
default = 5
```

For setting it via CLI, please use the following:
```shell
# Applying dark theme
testdoc ... -S dark PATH OUTPUT_FILE

# Applying blue theme
testdoc ... --style blue PATH OUTPUT_FILE
```

> [!TIP]
> You can select the default theme using either a string value or an integer value.

### Custom Themes

You can apply your own custom theme to modify the colors of the created HTML document.   
Use the following syntax & parameters in your toml-configuration file, to overwrite the predefined themes:
```toml
[colors]
background = "#000028"
inner_color = "#000028"
button_active_color = "#193966"
button_hover_color = "#193966"
border_color = "#CCCCCC"
text_color = "#CCCCCC"
title_color = "#00ffb9"
robot_icon = "#00ffb9"
code_area_background = "#303030"
code_area_foreground = "#f1f1f1"
```

> [!TIP]
> Please make sure to configure all available color values from this example — missing values may cause layout or rendering issues in the generated HTML document!

### Default Themes - Screenshot

#### Dark

![alt text](docs/style_dark.png)

#### Blue

![alt text](docs/style_blue.png)

#### Robot / Default

![alt text](docs/style_robot.png)

## Contribution & Development

See [Development.md](./DEVELOPMENT.md) for more information about contributing & developing this library.