Command Line Interface
The Dashboard command line interface allows the user to interact with and control the Dashboard server.
This way the usage of the Dashboard is completely scriptable.
Installation
The Dashboard command line interface is shipped in the Docker image. If you wish to run it elsewhere, you have to install it first.
The Dashboard command line interface is installed with
pip install -i https://pypi.hilster.io dashboard-cli
To check the correct installation and see all possible commands, type:
dashboard -h
dashboard [-h] [-s SERVER] [-u SERVER_USERNAME] [-p SERVER_PASSWORD] [-t TIMEOUT] [-v]
{login,logout,add-user,delete-user,passwd,user-info,whoami,set-roles,list-users,create-project,delete-project,list-projects,list-reports,delete-report,list-requirements,delete-requirements,create-token,delete-token,list-tokens,delete-tokens,export-project,import-project,upload-requirements,upload-reports,rebuild-cache}
...
QABench Dashboard CLI - https://www.hilster.io
positional arguments:
{login,logout,add-user,delete-user,passwd,user-info,whoami,set-roles,list-users,create-project,delete-project,list-projects,list-reports,delete-report,list-requirements,delete-requirements,create-token,delete-token,list-tokens,delete-tokens,export-project,import-project,upload-requirements,upload-reports,rebuild-cache}
login Login
logout Logout
add-user Add a user
delete-user Add a user
passwd Change password
user-info Get user information
whoami Get current username
set-roles Set user's roles for a project
list-users List users
create-project Create a project
delete-project Delete a project
list-projects Show a list of projects
list-reports Show a list of reports
delete-report Delete a report
list-requirements Show a list of requirements
delete-requirements
Delete requirements
create-token Create a token
delete-token Delete a token
list-tokens List project tokens
delete-tokens Delete all project tokens
export-project Export a project to an archive
import-project Import a project from an archive
upload-requirements
Upload requirements
upload-reports Upload reports
rebuild-cache Rebuild cache
optional arguments:
-h, --help show this help message and exit
-s SERVER, --server SERVER
Server with HTTP URI scheme (default: http://localhost)
-u SERVER_USERNAME, --username SERVER_USERNAME
Username
-p SERVER_PASSWORD, --password SERVER_PASSWORD
Password
-t TIMEOUT, --timeout TIMEOUT
Timeout in seconds (default: 30 s)
-v, --verbose Verbose output
Run CLI in Docker Compose
To use the Dashboard command line interface in Docker Compose, run
docker compose exec dashboard-server dashboard -h
Authentication Options
The Dashboard and the command line interface support authentication.
You can either login and logout persistently with distinct commands, or add the username and/or password to all commands.
If only the username is supplied, the command line interface interactively asks for the password.
In both cases the login is persistently stored to ~/.dashboard_session.bin.
The stored login credentials are used automatically until you log out.
For example, to login to a server without running a specific command, use
dashboard login
This will save an authentication cookie alongside the session locally.
To remove the session data and logout, use
dashboard logout
To list all available projects with credentials, run
dashboard -u <username> -p <password> list-projects
Alternatively the environment variables $DASHBOARD_USERNAME and $DASHBOARD_PASSWORD can
be used to set the credentials.
DASHBOARD_USERNAME=root DASHBOARD_PASSWORD=root dashboard login
Server Options
To set the server via command line, use the -s or --server options.
dashboard --server https://dashboard.server list-projects
You can alternatively set an environment variable to set the server url.
DASHBOARD_SERVER=https://dashboard.server dashboard list-projects
Verbosity
To enable verbose output, use the -v or --verbose options.
dashboard --verbose whoami
You can alternatively set an environment variable to enable verbosity.
DASHBOARD_VERBOSE=true dashboard whoami
If $DASHBOARD_VERBOSE is set to any value, verbosity is enabled.
Session Storage
To set the filename to store session information, use the -S or --session-file options.
dashboard --session-file session.txt whoami
You can alternatively set an environment variable to set the session file.
DASHBOARD_SESSION_FILE=session.txt dashboard whoami
TLS/SSL Certificate Verification
To disable TLS/SSL certificate verification, use the --insecure option.
dashboard --server https://dashboard.server --insecure login
You can alternatively set an environment variable to disable TLS/SSL certificate verification
DASHBOARD_INSECURE=true dashboard --server https://dashboard.server login
This can be helpful in case of self signed certificates or SSL interception proxy servers.
User and Role Overview
user “root” |
role “admin” |
role “user” |
||
|---|---|---|---|---|
User Management |
||||
List users |
x |
|||
Add user |
x |
|||
Delete user |
x |
|||
Change own password |
x |
x |
x |
|
Change other user’s passwords |
x |
|||
Get own user info |
x |
x |
x |
|
Get other user’s info |
x |
|||
Get own username |
x |
x |
x |
|
Set other user’s roles |
x |
|||
Projects |
||||
Create project |
x |
|||
List projects the user has a role in |
x |
x |
x |
|
List all projects |
x |
|||
Delete project |
x |
|||
Export project |
x |
x |
x |
|
Import project |
x |
x |
||
Reports |
||||
Upload report |
x |
x |
x |
|
List reports |
x |
x |
x |
|
Delete report |
x |
x |
||
Tokens |
||||
Create token |
x |
x |
||
List tokens |
x |
x |
||
Delete token |
x |
x |
||
Delete all tokens |
x |
x |
||
Requirements |
||||
Upload requirements |
x |
x |
||
List requirements |
x |
x |
x |
|
Delete requirements |
x |
x |
||
Cache |
||||
Rebuild cache |
x |
x |
User Management
List Users
To list all users, run
dashboard list-users
You need to be root to list users.
Add User
To add a user, run
dashboard add-user <username> [--password <password>]
The password can optionally supplied via command line. If this is not the case, it is asked interactively twice.
Example:
dashboard add-user foo
You need to be root to add users.
Delete User
To delete a user, run
dashboard delete-user <username>
Example:
dashboard delete-user foo
You need to be root to delete users.
Change Password
To change your own password, run
dashboard passwd [--password <password>]
The password can optionally supplied via command line. If not, it is asked interactively twice.
Example:
dashboard passwd
To change another user’s password, run
dashboard passwd --username <username> [--password <password>]
You need to be root to change other user’s passwords.
Example:
dashboard passwd --username foo
User Information
To get user information for the current user, run
dashboard user-info
It will list the current username and project roles.
To get user information for other users, run
dashboard user-info --username <username>
as root.
Get Username
To get the currently logged in user name, run
dashboard whoami
Set User’s Project Roles
To set user’s roles for a project, run
dashboard set-roles <project> <username> [<list of roles>]
as root.
Available roles are admin and user.
Example:
dashboard set-roles project_1 user_name admin
To remove user’s roles just run the command without the optional roles.
Example:
dashboard set-roles project_1 user_name
Projects
Create Project
You can create a new project by running
dashboard create-project <project-name> <project-alias>
Example:
dashboard create-project project "My first project"
Only root users can create projects.
List Projects
To list all currently available projects in the Dashboard you can, run
dashboard list-projects
Project Alias Number of Reports
------------------ ----- -------------------
unit_tests Unit Tests 200
integration_tests Integration Tests 300
system_tests System Tests 400
Only projects available for the user are listed. A project is available if the user
has at least the user role for the specified project.
Running this command as root user lists all projects.
Project Status
To show the latest project status in the command line, run
dashboard status <project>
dashboard status unit-tests
Project: Unit Tests
Last modified: Sat, 11 Dec 2021 16:38:31 GMT
Successful tests: 92 % (23/25)
Requirements coverage: 98 % (98/100)
Warning
After uploading a new report it might take a few seconds until the cached contents are rebuilt.
Delete Project
To delete a project and the corresponding reports, requirements and tokens, run
dashboard delete-project <project-name>
Example:
dashboard delete-project project
Only root users can delete projects.
Export Project
To export a project to an archive, run
dashboard export-project <project> <archive-filename>
The exported archive is a zip file containing all supplied reports, requirements and tokens
to be stored as a backup or to be imported elsewhere.
Example:
dashboard export-project project archive.zip
Projects can be exported by users with at least the user role.
Import Project
To import an exported project from an archive, run
dashboard import-project <project> <archive-filename> [--wait <timeout>]
Note that a project needs to exist before you can import it.
Projects can be imported to existing projects by users with the admin role.
The root user can create a project on import by running
dashboard import-project -c <project> <archive-filename>
Example:
dashboard import-project -c <project> archive.zip
If --wait is supplied the command will wait until the cache was updated after importing all data or a timeout
occurs.
To import a project, update the cache and wait up to one minute run
dashboard import-project project archive.zip --wait 60
Reports
Upload Reports
Archived reports can be uploaded using the command line interface.
To upload multiple files in a directory, run
dashboard upload-reports <project> <list-of-filenames>
This interface supports the filetypes: YAML- and JSON-Reports generated
by the QABench htf (formerly known as HILSTER Testing Framework) and JunitXML-Reports
generated by any testing tool.
Example:
dashboard upload-reports <project> *.yaml *.yml *.json *.xml
Note
When using tokens for authentication, you have to supply a token to the
project url since the upload uses the same API endpoint as htf does.
HTTP 403 Forbidden is returned if a token is missing.
Reports can be uploaded by users with at least the user role.
List Reports
To print the list of reports uploaded for a project, run
dashboard list-reports <project>
Example:
dashboard list-reports <project>
ID Date Number of Tests Results
------------------------------------ ------------------- ----------------- ----------------------------------------
5173e06a-d705-4560-be2a-a6f9e96f3025 2020-01-01 00:00:00 2 Success 2 Failure 0 Error 0 Skipped 0
41bf9c00-216f-4afd-b838-12d495e41802 2020-01-02 00:00:00 2 Success 2 Failure 0 Error 0 Skipped 0
1036f49d-d460-406e-887c-e9919cca3a7f 2020-01-03 00:00:00 2 Success 2 Failure 0 Error 0 Skipped 0
Reports can be listed by users with at least the user role.
Delete Report
To delete a report, run
dashboard delete-report <project> <report-id>
Example:
dashboard delete-report <project> 5173e06a-d705-4560-be2a-a6f9e96f3025
Reports can be deleted by users with the admin role.
Tokens
By default all endpoints of the Dashboard need authentication, except the endpoint used by QABench htf (formerly known as HILSTER Testing Framework) to upload reports.
Instead of authenticating QABench htf (formerly known as HILSTER Testing Framework), you can add tokens to your project that are used in the server url. Thus tokens can be used to restrict the upload of test reports.
If no tokens exist for a project, the endpoint for QABench htf (formerly known as HILSTER Testing Framework) does not need a token to be supplied in the server url. If a token is supplied in this case, an exception is raised.
If one or many tokens exist for a project, one of these tokens must be supplied in the server url. If no token is supplied in this case, an exception is raised.
Create Token
To create a token, run
dashboard create-token <project> <token-name>
Example:
dashboard create-token <project> my_token
The newly created token is printed on the command line and can be used after that. The token is simply added to the project url.
To use QABench htf (formerly known as HILSTER Testing Framework) with a token, run
htf -r https://dashboard.server/project/<project>/token/<token> .
Example:
htf -r https://dashboard.server/project/my_project/token/5f214bca1ddb227668c086a9 .
Tokens can be created by users with the admin role.
List Tokens
To print the list of tokens for a project, run
dashboard list-tokens <project>
Example:
dashboard list-tokens <project>
Name Token
----- --------------------------------------------------------
token 4479723524bcb8a562e861cd8ef1998b431114ef4213e38b16dba026
Tokens can be created by users with the admin role.
Delete Token
To delete a token, run
dashboard delete-token <project> <token>
Example:
dashboard delete-token <project> 4479723524bcb8a562e861cd8ef1998b431114ef4213e38b16dba026
Tokens can be deleted by users with the admin role.
Delete all Tokens
To delete all tokens, run
dashboard delete-tokens <project>
Tokens can be deleted by users with the admin role.
Requirements
Upload Requirements
To upload requirements to a project, run
dashboard upload-requirements <project> <list-of-filenames>
Requirement files need to be csv-files.
More information regarding the requirement format can be found here
Example:
dashboard upload-requirements <project> requirements.csv
By default the current date will be used when uploading the requirements. To force a specific date, use
dashboard upload-requirements <project> <list-of-filenames> --date "%Y-%m-%d %H:%M:%S"
Example:
dashboard upload-requirements <project> requirements.csv --date "2020-01-01 00:00:00"
Requirements can be uploaded by users with the admin role.
List Requirements
To print a list of requirements uploaded to a project, run
dashboard list-requirements <project>
Example:
dashboard list-requirements <project>
ID Date Number of Requirements Requirements
------------------------ ------------------- ------------------------ ----------------------------
5f214bca1ddb227668c086a9 2020-01-01 00:00:00 0 ['REQ_0']
5f214bca1ddb227668c086ad 2020-01-02 00:00:00 4 ['REQ_0', 'REQ_1']
5f214bca1ddb227668c086b1 2020-01-03 00:00:00 6 ['REQ_0', 'REQ_1', 'REQ_2']
Requirements can be listed by users with at least the user role.
Delete Requirements
To delete a set of requirements, run
dashboard delete-requirements <project> <requirements-id>
Example:
dashboard delete-requirements <project> 5f214bca1ddb227668c086a9
Requirements can be deleted by users with the admin role.
Cache
To rebuild the project cache, run
dashboard rebuild-cache <project> [--wait <timeout>]
The cache can be rebuilt by users with the admin role.
If --wait is supplied the command will wait until the cache was updated or a timeout occurs.
To update the cache and to wait up to one minute run
dashboard rebuild-cache <project> --wait 60
Bash-Completion
dashboard supports Bash-Completion which provides
automatic command completion for the bash shell.
To easly run dashboard create-project type
dashboard cr<TAB>
create-project create-token
dashboard create-project
Enable Bash-Completion
To enable Bash-Completion
eval $(dashboard complete)
eval $(dashboard.admin complete)
To persistently enable bash completion, add the command to your ~.bashrc.
alternatively put it into a new file called /etc/bash_completion.d/dashboard, eg.
echo "eval $(dashboard complete)" >> ~/.bashrc
echo "eval $(dashboard.admin complete)" >> ~/.bashrc
. ~/.bashrc
or
echo "eval $(dashboard complete)" > /etc/bash_completion.d/dashboard
. /etc/bash_completion.d/dashboard
echo "eval $(dashboard.admin complete)" > /etc/bash_completion.d/dashboard.admin
. /etc/bash_completion.d/dashboard.admin
To check if Bash-Completion is enabled type
complete -p | grep dashboard
complete -p | grep dashboard.admin