dump2polarion
=============

.. image:: https://travis-ci.org/mkoura/dump2polarion.svg?branch=master
    :target: https://travis-ci.org/mkoura/dump2polarion
    :alt: Build status

.. image:: https://coveralls.io/repos/github/mkoura/dump2polarion/badge.svg?branch=master
    :target: https://coveralls.io/github/mkoura/dump2polarion?branch=master
    :alt: Coverage report

.. image:: https://img.shields.io/pypi/v/dump2polarion.svg
    :target: https://pypi.python.org/pypi/dump2polarion
    :alt: Version

.. image:: https://img.shields.io/pypi/pyversions/dump2polarion.svg
    :target: https://pypi.python.org/pypi/dump2polarion
    :alt: Supported Python versions

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/ambv/black
    :alt: Code style: black


Capabilities of the dump2polarion library
-----------------------------------------

* generating XML files for XUnit, Testcase and Requirements Importers
* submitting XML files to Importers
* verifying that the import was successfull
* saving the import log files
* reading Test Cases data from SVN repository with checked out Polarion project

The library supports all features of the Importers (even iterations). The export to XML files can be customized per project - lookup method, what results will be included in the XUnit (e.g. only PASSed tests), etc.

Both Python 2 and 3 are supported.

The library doesn't use the legacy webservices API, all the operations are performed using Polarion Importers.

polarion_dumper.py script
-------------------------

Script for importing tests results recorded in the CSV, SQLite, junit-report.xml (generated by pytest) or Ostriz JSON input file to Polarion using the XUnit Importer.

Can be also used for submit of pre-generated XUnit, Test Case or Requirement XML files to corresponding Polarion Importer.

By default the script waits until the Importer finishes the import job and then checks the success of the operation.

Usage
~~~~~

.. code-block::

    polarion_dumper.py -i {input_file}

By default the input data are submitted to Polarion. You can disable this bahavior with ``-n`` option. In this case the XML file used for submission will be saved to disk. Default file location is the current directory (can be overriden with ``-o`` option).

When output file is specified with ``-o PATH``, the XML file used for results submission will be saved to disk. If `PATH` is a directory, resulting file name will be generated - `PATH/FILE_TYPE-TESTRUN_ID-TIMESTAMP.xml`.

When the input file is a XML file in a format supported by one of the Polarion Importers (e.g. saved earlier with ``-o FILE -n``), it is submitted to Polarion.

Configuration
-------------
You can specify credentials on command line with ``--user kerberos_username --password kerberos_password``. Or you can set them in a config file.

The config file is specified on command line with ``-c config_file.yaml``.

Another possibility for specifying credentials are environment variables (the same are used for pylarion):

.. code-block::

    export POLARION_USERNAME=kerberos_username
    export POLARION_PASSWORD=kerberos_password

You can mix all these approaches, e.g. user name on command line and password in the environment variable.

.. IMPORTANT::

    You need to specify URLs of the importer services and queues in the config file. See <https://mojo.redhat.com/docs/DOC-1098563#config>


Install
-------
To install the package to your virtualenv, run

.. code-block::

    pip install dump2polarion

or install it from cloned directory

.. code-block::

    pip install -e .

Package on PyPI <https://pypi.python.org/pypi/dump2polarion>

Requirements
------------
Requirements are listed in ``requirements.txt``.

CSV format for XUnit
--------------------
There needs to be a row with field names - it is present by default when exported from Polarion.

Fields are ID; Title; Test Case ID (optional but recommended); Verdict; Comment (optional); Time (optional); stdout (optional); stderr (optional) + any other field you want. Order of the fields and case doesn't matter.

The "Verdict" field and any optional fields must be added manually. Valid values for "verdict" are "passed", "failed", "skipped", "waiting" or empty. It's case insensitive.

There can be any content before the row with field names and the test results.

SQLite format for XUnit
-----------------------
You can convert the CSV file exported out of Polarion using the ``csv2sqlite.py`` script:

.. code-block::

    csv2sqlite.py -i {input_file.csv} -o {output_file.sqlite3}

How to submit the XML file manually
-----------------------------------

.. code-block::

    polarion_dumper.py -i input.xml --user {user} --password {password}

or

.. code-block::

    curl -k -u {user}:{password} -X POST -F file=@./output.xml {importer_url}

More info
---------
For CFME QE specific instructions see <https://mojo.redhat.com/docs/DOC-1098563>

For info about XUnit Importer see <https://mojo.redhat.com/docs/DOC-1073077>

For info about Test Case Importer see <https://mojo.redhat.com/docs/DOC-1075945>

For info about Requirements Importer see <https://mojo.redhat.com/docs/DOC-1163149>
