.. _cli: 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 .. code-block:: bash pip install -i https://pypi.hilster.io dashboard-cli To check the correct installation and see all possible commands, type: .. code-block:: none dashboard -h .. code-block:: none 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 .. code-block:: bash 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 .. code-block:: bash dashboard login This will save an authentication cookie alongside the session locally. To remove the session data and logout, use .. code-block:: bash dashboard logout To list all available projects with credentials, run .. code-block:: bash dashboard -u -p list-projects Alternatively the environment variables ``$DASHBOARD_USERNAME`` and ``$DASHBOARD_PASSWORD`` can be used to set the credentials. .. code-block:: bash DASHBOARD_USERNAME=root DASHBOARD_PASSWORD=root dashboard login Server Options -------------- To set the server via command line, use the ``-s`` or ``--server`` options. .. code-block:: bash dashboard --server https://dashboard.server list-projects You can alternatively set an environment variable to set the server url. .. code-block:: bash DASHBOARD_SERVER=https://dashboard.server dashboard list-projects Verbosity --------- To enable verbose output, use the ``-v`` or ``--verbose`` options. .. code-block:: bash dashboard --verbose whoami You can alternatively set an environment variable to enable verbosity. .. code-block:: bash 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. .. code-block:: bash dashboard --session-file session.txt whoami You can alternatively set an environment variable to set the session file. .. code-block:: bash DASHBOARD_SESSION_FILE=session.txt dashboard whoami TLS/SSL Certificate Verification -------------------------------- To disable TLS/SSL certificate verification, use the ``--insecure`` option. .. code-block:: bash dashboard --server https://dashboard.server --insecure login You can alternatively set an environment variable to disable TLS/SSL certificate verification .. code-block:: bash 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 | x | | | | | passwords | | | | +---------------------+------------------------+-------------+--------------+-------------+ | | Get own user info | x | x | x | +---------------------+------------------------+-------------+--------------+-------------+ | | Get other user's | x | | | | | info | | | | +---------------------+------------------------+-------------+--------------+-------------+ | | Get own username | x | x | x | +---------------------+------------------------+-------------+--------------+-------------+ | | Set other user's roles | x | | | +---------------------+------------------------+-------------+--------------+-------------+ | **Projects** | | | | | +---------------------+------------------------+-------------+--------------+-------------+ | | Create project | x | | | +---------------------+------------------------+-------------+--------------+-------------+ | | List projects the user | x | x | x | | | has a role in | | | | +---------------------+------------------------+-------------+--------------+-------------+ | | 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 .. code-block:: bash dashboard list-users You need to be ``root`` to list users. .. _add-user: Add User ~~~~~~~~ To add a user, run .. code-block:: bash dashboard add-user [--password ] The password can optionally supplied via command line. If this is not the case, it is asked interactively twice. Example: .. code-block:: bash dashboard add-user foo You need to be ``root`` to add users. Delete User ~~~~~~~~~~~ To delete a user, run .. code-block:: bash dashboard delete-user Example: .. code-block:: bash dashboard delete-user foo You need to be ``root`` to delete users. .. _passwd: Change Password ~~~~~~~~~~~~~~~ To change your own password, run .. code-block:: bash dashboard passwd [--password ] The password can optionally supplied via command line. If not, it is asked interactively twice. Example: .. code-block:: bash dashboard passwd To change another user's password, run .. code-block:: bash dashboard passwd --username [--password ] You need to be ``root`` to change other user's passwords. Example: .. code-block:: bash dashboard passwd --username foo User Information ~~~~~~~~~~~~~~~~ To get user information for the current user, run .. code-block:: bash dashboard user-info It will list the current username and project roles. To get user information for other users, run .. code-block:: bash dashboard user-info --username as ``root``. Get Username ~~~~~~~~~~~~ To get the currently logged in user name, run .. code-block:: bash dashboard whoami .. _set-roles: Set User's Project Roles ~~~~~~~~~~~~~~~~~~~~~~~~ To set user's roles for a project, run .. code-block:: bash dashboard set-roles [] as ``root``. Available roles are ``admin`` and ``user``. Example: .. code-block:: bash dashboard set-roles project_1 user_name admin To remove user's roles just run the command without the optional roles. Example: .. code-block:: bash dashboard set-roles project_1 user_name Projects -------- .. _create-project: Create Project ~~~~~~~~~~~~~~ You can create a new project by running .. code-block:: bash dashboard create-project Example: .. code-block:: bash 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 .. code-block:: bash dashboard list-projects .. code-block:: bash 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 .. code-block:: bash dashboard status .. code-block:: bash 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 .. code-block:: bash dashboard delete-project Example: .. code-block:: bash dashboard delete-project project Only ``root`` users can delete projects. Export Project ~~~~~~~~~~~~~~ To export a project to an archive, run .. code-block:: bash dashboard export-project 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: .. code-block:: bash 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 .. code-block:: bash dashboard import-project [--wait ] 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 .. code-block:: bash dashboard import-project -c Example: .. code-block:: bash dashboard import-project -c 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 .. code-block:: bash 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 .. code-block:: bash dashboard upload-reports 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: .. code-block:: bash dashboard upload-reports *.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 .. code-block:: bash dashboard list-reports Example: .. code-block:: bash dashboard list-reports .. code-block:: bash 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 .. code-block:: bash dashboard delete-report Example: .. code-block:: bash dashboard delete-report 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 .. code-block:: bash dashboard create-token Example: .. code-block:: bash dashboard create-token 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 .. code-block:: bash htf -r https://dashboard.server/project//token/ . Example: .. code-block:: bash 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 .. code-block:: bash dashboard list-tokens Example: .. code-block:: bash dashboard list-tokens .. code-block:: bash Name Token ----- -------------------------------------------------------- token 4479723524bcb8a562e861cd8ef1998b431114ef4213e38b16dba026 Tokens can be created by users with the ``admin`` role. Delete Token ~~~~~~~~~~~~ To delete a token, run .. code-block:: bash dashboard delete-token Example: .. code-block:: bash dashboard delete-token 4479723524bcb8a562e861cd8ef1998b431114ef4213e38b16dba026 Tokens can be deleted by users with the ``admin`` role. Delete all Tokens ~~~~~~~~~~~~~~~~~ To delete all tokens, run .. code-block:: bash dashboard delete-tokens Tokens can be deleted by users with the ``admin`` role. Requirements ------------ .. _upload-requirements: Upload Requirements ~~~~~~~~~~~~~~~~~~~ To upload requirements to a project, run .. code-block:: bash dashboard upload-requirements Requirement files need to be ``csv``-files. More information regarding the requirement format can be found :ref:`here` Example: .. code-block:: bash dashboard upload-requirements requirements.csv By default the current date will be used when uploading the requirements. To force a specific date, use .. code-block:: bash dashboard upload-requirements --date "%Y-%m-%d %H:%M:%S" Example: .. code-block:: bash dashboard upload-requirements 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 .. code-block:: bash dashboard list-requirements Example: .. code-block:: bash dashboard list-requirements .. code-block:: bash 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 .. code-block:: bash dashboard delete-requirements Example: .. code-block:: bash dashboard delete-requirements 5f214bca1ddb227668c086a9 Requirements can be deleted by users with the ``admin`` role. Cache ----- To rebuild the project cache, run .. code-block:: bash dashboard rebuild-cache [--wait ] 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 .. code-block:: bash dashboard rebuild-cache --wait 60 Bash-Completion --------------- ``dashboard`` supports Bash-Completion which provides automatic command completion for the ``bash`` shell. To easly run ``dashboard create-project`` type .. code-block:: bash dashboard cr create-project create-token dashboard create-project Enable Bash-Completion ---------------------- To enable Bash-Completion .. code-block:: bash 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. .. code-block:: bash echo "eval $(dashboard complete)" >> ~/.bashrc echo "eval $(dashboard.admin complete)" >> ~/.bashrc . ~/.bashrc or .. code-block:: bash 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 .. code-block:: bash complete -p | grep dashboard complete -p | grep dashboard.admin