Client Configuration
====================

Once your server is all set up, you can start reporting test executions to it.

Backslash is a generic test reporting service that is not tightly
coupled to a specific use case, but the best out-of-the-box client
support is for the Slash testing framework, as the two were developed
in parallel.

This chapter will focus on how to get started reporting to Backslash
from Slash, but it should be fairly easy to add integrations to other
frameworks. We will be using the `official client library for
Backslash <https://pypi.python.org/pypi/backslash/>`_, which also
includes a supplemental plugin for Slash.


Quick Configuration
-------------------

The simplest configuration is to add the following to your
``.slashrc`` in your project's root directory:

.. code-block:: python

       import slash.plugins
       from backslash.contrib.slash_plugin import BackslashPlugin

       slash.plugins.manager.install(
           BackslashPlugin(
               'http://your.backslash.server',
           ), activate=True)

That's it!

When you first run your tests, the plugin will initialize itself and
open a browser window asking you to log in, so that it can fetch a run
token for your sessions.

Run Tokens
----------

In order for Backslash to identify you when running tests, a *run
token* is used. This token is generated by the server and stored by the
client in ``~/.config/backslash`` for future runs.

By default, as stated above, the Backslash plugin fetches this token
using a multi-step authentication via a web browser. However, you can
specify the run token explicitly when constructing the plugin:

.. code-block:: python

       plugin = BackslashPlugin(..., runtoken='xxxxx...')

Adding Session Metadata
-----------------------

One of the most frequent tasks when reporting test runs is reporting metadata about the session in question. Backslash supports arbitrary JSON metadata, and it can be easily added by overriding the ``_get_initial_session_metadata`` method:


.. code-block:: python


       import slash.plugins
       from backslash.contrib.slash_plugin import BackslashPlugin as BackslashPluginBase


       class BackslashPlugin(BackslashPluginBase):

            def _get_initial_session_metadata(self):
                returned = super()._get_initial_session_metadata()
                returned.update({
                   'environment_type': my_environment_type
                })
                return returned


       slash.plugins.manager.install(
           BackslashPlugin(
               'http://your.backslash.server',
           ), activate=True)



Adding Test Subjects
--------------------

Backslash test sessions run on *test subjects*. You can control how your session records its subjects by overriding the ``_get_extra_session_start_kwargs`` method:

.. code-block:: python

    ...
        def _get_extra_session_start_kwargs(self):
            returned = super()._get_extra_session_start_kwargs()
            returned['subjects'] = [
                {
                    'name': 'microwave1',
                    'product': 'Microwave',
                    'version': 'v1',
                    'revision': '123456',
                }
            ]
            return returned
    ...