robotframework-testdoc 0.4.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.

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.

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.