robotframework-testdoc 0.3.1

A CLI Tool to generate a Test Documentation for your RobotFramework Test Scripts.

Robot Framework TestDoc

GitHub Project

Link to GitHub Project: robotframework-testdoc

Statistics

Installation

Install the tool using the following command:

pip install robotframework-testdoc

[!IMPORTANT] Preconditions: Python & Pip Installation.

Usage

Basic Usage

testdoc suite_directory output.html
# or
testdoc suite_file output.html

Extended Usage

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.

Examples

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

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

# 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.

User Keyword defined in a Test Suite

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:

# 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

[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

Version 2

Visit Tests on Root Suite Level

Visit Tests on Suite File Level

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

[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:

# 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:

[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

Blue

Robot / Default

Contribution & Development

See Development.md for more information about contributing & developing this library.