Metadata-Version: 2.4
Name: robotframework-robotlog2db
Version: 1.6.0
Summary: Imports robot results to TestResultWebApp database
Author-email: Tran Duy Ngoan <Ngoan.TranDuy@vn.bosch.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://pypi.org/project/robotframework-robotlog2db/
Project-URL: Documentation, https://github.com/test-fullautomation/robotframework-robotlog2db/blob/develop/RobotLog2DB/RobotLog2DB.pdf
Project-URL: Readme, https://github.com/test-fullautomation/robotframework-robotlog2db/blob/develop/README.rst
Project-URL: Repository, https://github.com/test-fullautomation/robotframework-robotlog2db
Project-URL: Issues, https://github.com/test-fullautomation/robotframework-robotlog2db/issues
Keywords: robotframework,robot,results,TestResultWebApp,database
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/x-rst
Requires-Dist: robotframework>=6.1
Requires-Dist: colorama
Requires-Dist: lxml
Requires-Dist: mysqlclient
Requires-Dist: GenPackageDoc
Requires-Dist: PythonExtensionsCollection
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: docutils>=0.22.4; extra == "docs"

RobotLog2DB
===========

Table of Contents
-----------------

-  `Getting Started <#getting-started>`__

   -  `How to install <#how-to-install>`__
-  `Usage <#usage>`__
-  `Example <#example>`__
-  `Contribution <#contribution>`__
-  `Sourcecode Documentation <#sourcecode-documentation>`__
-  `Feedback <#feedback>`__
-  `About <#about>`__

   -  `Maintainers <#maintainers>`__
   -  `Contributors <#contributors>`__
   -  `License <#license>`__

Getting Started
---------------

**RobotLog2DB** is a command-line tool that enables you to import `Robot
Framework XML result`_ files into TestResultWebApp_'s database for
presenting an overview about the whole test execution and detail of each test
result.

**RobotLog2DB** tool is operating system independent and only works with
Python 3.

How to install
~~~~~~~~~~~~~~

**RobotLog2DB** can be installed in two different ways.

1. Installation via PyPi (recommended for users)

   .. code::

      pip install robotframework-robotlog2db

   `RobotLog2DB in PyPi <https://pypi.org/project/robotframework-robotlog2db/>`_

2. Installation via GitHub (recommended for developers)

   * Clone the **robotframework-robotlog2db** repository to your machine.

     .. code::

        git clone https://github.com/test-fullautomation/robotframework-robotlog2db.git

     `RobotLog2DB in GitHub <https://github.com/test-fullautomation/robotframework-robotlog2db>`_

   * Use the following command to install **RobotLog2DB** (executed in repository main folder):

     .. code::

        python -m pip install .

     Or:

     .. code::

        python -m pip install --proxy <proxy> .

     This command will also download and install all dependencies that are required to work with the source files in the current repository.
     After the initial installation of **RobotLog2DB** is done, you have the following two possibilities:

     1. *Clean the previous installation*:

        .. code::

           python "./cleanup_installation.py"

        ``cleanup_installation.py`` explicitly deletes all files and folders within the component installation folder under
        ``site-packages`` and also deletes local build artefacts.

     2. *Render the component documentation*:

        .. code::

           python "./genpackagedoc.py"

        This would e.g. be required in case of changes in the interface of **RobotLog2DB**.

        The documentation is rendered by a separate application called **GenPackageDoc**, that is part
        of the build dependencies and runtime dependencies of **RobotLog2DB**.

        **GenPackageDoc** needs to be configured. Details about how to do this, can be found in the
        `README.rst <https://github.com/test-fullautomation/python-genpackagedoc/blob/develop/README.rst>`_
        (sections *Install dependencies* and *Configure dependencies*).

   * Use the following command to build **RobotLog2DB** (executed in repository main folder):

     .. code::

        python -m build .

     Or:

     .. code::

        python -m pip config set global.proxy <proxy>
        python -m build .

After succesful installation, the executable file **RobotLog2DB**
will be available (under *Scripts* folder of Python on Windows
and *~/.local/bin/* folder on Linux).

In case above location is added to **PATH** environment variable
then you can run it directly as operation system's command.

Usage
-----

**RobotLog2DB** requires the Robot Framework result file(s) which contains the
output result in XML format (default name is ``output.xml``) and
TestResultWebApp_'s database information for importing.

Use below command to get tools's usage

::

   RobotLog2DB -h


The usage should be showed as below:

::

   usage: RobotLog2DB (RobotXMLResult to TestResultWebApp importer) [-h] [-v] [--recursive] [--dryrun] [--append] [--UUID UUID] [--variant VARIANT] [--versions VERSIONS] [--config CONFIG]
                                                                    resultxmlfile server user password database

   RobotLog2DB imports XML result files (default: output.xml) generated by the Robot Framework into a WebApp database.

   positional arguments:
   resultxmlfile        absolute or relative path to the result file or directory of result files to be imported.
   server               server which hosts the database (IP or URL).
   user                 user for database login.
   password             password for database login.
   database             database schema for database login.

   optional arguments:
   -h, --help           show this help message and exit
   -v, --version        version of the RobotLog2DB importer.
   --recursive          if set, then the path is searched recursively for output files to be imported.
   --dryrun             if set, then verify all input arguments (includes DB connection) and show what would be done.
   --append             is used in combination with --UUID <UUID>.If set, allow to append new result(s) to existing execution result UUID in --UUID argument.
   --UUID UUID          UUID used to identify the import and version ID on webapp. If not provided RobotLog2DB will generate an UUID for the whole import.
   --variant VARIANT    variant name to be set for this import.
   --versions VERSIONS  metadata: Versions (Software;Hardware;Test) to be set for this import (semicolon separated).
   --config CONFIG      configuration json file for component mapping information.
   --interface {db,rest}
                        database access interface.
   --testrunurl TESTRUNURL
                        link to test execution job: Jenkins job, Gitlab CI/CD pipeline, ...

The below command is simple usage with all required arguments to import
Robot Framework results into TestResultWebApp's database:

::

   RobotLog2DB <resultxmlfile> <server> <user> <password> <database>

Besides the executable file, you can also run tool as a Python module

::

   python -m RobotLog2DB <resultxmlfile> <server> <user> <password> <database>


Example
-------

In order the import the Robot Framework result(s) to TestResultWebApp's database,
we need the Robot Framework result file (``output.xml``).

So, firstly execute the Robot Framework testcase(s) to get the Robot Framework result file.

Sample Robot Framework testcase which contains neccessary information for importing into
TestResultWebApp's database:

::

   *** Settings ***
   # Test execution level
   Metadata   project        ROBFW              # Project/Variant
   Metadata   version_sw     SW_VERSION_0.1     # Software version
   Metadata   version_hw     HW_VERSION_0.1     # Hardware version
   Metadata   version_test   TEST_VERSION_0.1   # Test version

   # File/Suite level
   Documentation             This is description for Robot Framework test file
   Metadata    author        Tran Duy Ngoan (RBVH/ECM1)
   Metadata    component     Import_Tools
   Metadata    testtool      Robot Framework 3.2rc2 (Python 3.9.0 on win32)
   Metadata    machine       %{COMPUTERNAME}
   Metadata    tester        %{USER}

   *** Test Cases ***
   Testcase 01
      [Tags]   ISSUE-001   TCID-1001   FID-112   FID-111
      Log   	This is Testcase 01

   Testcase 02
      [Tags]   ISSUE-RTC-003   TCID-1002   FID-113
      Log   	This is Testcase 01


Notes:
~~~~~~

   In case you are using RobotFramework AIO, these below ``Metadata``
   definitions will be handled implicitly by `RobotFramework Testsuites
   Management`_ library within Suite Setup.

   * project
   * version_sw
   * version_hw
   * version_test
   * machine
   * tester
   * testtool

   So that you do not need to define them in your Robot Framework testcase(s).

   However, if these ``Metadata`` definitions are already missing in the
   Robot Framework output result file, you can specific them when executing the
   **RobotLog2DB** tool with the optional arguments:

   * ``--variant VARIANT``: Project definitions
   * ``--versions VERSIONS``: Versions (Software;Hardware;Test) definitions.
   * ``--config CONFIG``: Project, versions or component mapping definitions.

   Please refer to `RobotLog2DB tool’s Documentation`_ for more detail about
   these optional arguments.

After getting Robot Framework result file (``output.xml``), use below sample
command to  import that result into TestResultWebApp's database which is hosted
at *localhost* as below sample command

::

   RobotLog2DB output.xml localhost test_user test_pw test_db

Then, open TestResultWebApp with your favourite browser and you will see how
wonderful the execution result is displayed as below figures:

Dashboard view:

.. image:: https://github.com/test-fullautomation/robotframework-robotlog2db/blob/develop/packagedoc/additional_docs/pictures/Dashboard.png?raw=true
   :alt: Dashboard view

Datatable view:

.. image:: https://github.com/test-fullautomation/robotframework-robotlog2db/blob/develop/packagedoc/additional_docs/pictures/Datatable.png?raw=true
   :alt: Datatable view

Contribution
------------
We are always searching support and you are cordially invited to help to improve
**RobotLog2DB** tool.

Sourcecode Documentation
------------------------
To understand more detail about the tool's features, parameters and how Robot Framework
testcase information will be displayed on TestResultWebApp, please refer to
`RobotLog2DB tool’s Documentation`_.

Feedback
--------
Please feel free to give any feedback to us via

Email to: `Thomas Pollerspöck`_

Issue tracking: `RobotLog2DB Issues`_

About
-----

Maintainers
~~~~~~~~~~~
`Thomas Pollerspöck`_

`Tran Duy Ngoan`_

Contributors
~~~~~~~~~~~~

`Nguyen Huynh Tri Cuong`_

`Mai Dinh Nam Son`_

`Tran Hoang Nguyen`_

`Holger Queckenstedt`_

License
~~~~~~~

Copyright 2020-2023 Robert Bosch GmbH

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    |License: Apache v2|

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.


.. |License: Apache v2| image:: https://img.shields.io/pypi/l/robotframework.svg
   :target: http://www.apache.org/licenses/LICENSE-2.0.html
.. _RobotLog2DB: https://github.com/test-fullautomation/robotframework-robotlog2db
.. _TestResultWebApp: https://github.com/test-fullautomation/TestResultWebApp
.. _Thomas Pollerspöck: mailto:Thomas.Pollerspoeck@de.bosch.com
.. _Tran Duy Ngoan: mailto:Ngoan.TranDuy@vn.bosch.com
.. _Nguyen Huynh Tri Cuong: mailto:Cuong.NguyenHuynhTri@vn.bosch.com
.. _Mai Dinh Nam Son: mailto:Son.MaiDinhNam@vn.bosch.com
.. _Tran Hoang Nguyen: mailto:Nguyen.TranHoang@vn.bosch.com
.. _Holger Queckenstedt: mailto:Holger.Queckenstedt@de.bosch.com
.. _RobotLog2DB tool’s Documentation: https://github.com/test-fullautomation/robotframework-robotlog2db/blob/develop/RobotLog2DB/RobotLog2DB.pdf
.. _RobotLog2DB Issues: https://github.com/test-fullautomation/robotframework-robotlog2db/issues
.. _RobotFramework Testsuites Management: https://github.com/test-fullautomation/robotframework-testsuitesmanagement
.. _Robot Framework XML result: https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#output-file
