Built-in Plugins
================

Slash comes with pre-installed, built-in plugins that can be activated when needed.

Coverage
--------

This plugins tracks and reports runtime code coverage during runs, and reports the results in various formats. It uses the Net Batchelder's `coverage package <https://coverage.readthedocs.io/en/>`_.

To use it, run Slash with ``--with-coverage``, and optionally specify modules to cover::

  $ slash run --with-coverage --cov mypackage --cov-report html

Notifications
-------------

The notifications plugin allows users to be notified when sessions end in various methods, or notification mediums.

To use it, run Slash with ``--with-notifications``. Please notice that each notification type requires additional configuration values. You will also have to enable your desired backend with ``--notify-<backend name>`` (e.g. ``--notify-email``)

For e-mail notification, you'll need to configure your SMTP server, and pass the recipients using ``--email-to``::

  $ slash run --notify-email --with-notifications -o plugin_config.notifications.email.smtp_server='my-smtp-server.com --email-to youremail@company.com'

For using Slack notification, you should firstly configure `slack webhook integration <https://api.slack.com/incoming-webhooks>`_. And run slash::

  $ slash run --with-notifications -o plugin_config.notifications.slack.url='your-webhook-ingetration-url' -o plugin_config.notifications.slack.channel='@myslackuser'

Including Details in Notifications
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. index::
   pair: notification; details

You can include additional information in your notifications, which is then sent as a part of email messages you receive. This can be done with the ``prepare_notification`` hook:

.. code-block:: python

       @slash.hooks.prepare_notification.register
       def prepare_notification(message):
           message.details_dict['additional_information'] = 'some information included'

XUnit
-----

The xUnit plugin outputs an XML file when sessions finish running. The XML conforms to the xunit format, and thus can be read and processed by third party tools (like CI services, for example)

Use it by running with ``--with-xunit`` and by specifying the output filename with ``--xunit-filename``::

  $ slash run --with-xunit --xunit-filename xunit.xml


Signal handling
---------------

The signal handling plugin allows users to register handlers for OS signals. By default, the plugin registers the following handlers (if supported by the OS):
1. SIGUSR1 drops into debugger
2. SIGUSR2 skips current test

The plugin also supports registering additional signal handlers, as well as overriding the default ones, by using the ``register_handler`` function

Linking to logs archived by a CI system
---------------------------------------

The CI links plugin adds a web link to the test log file artifact archived by a CI system to the test's additional details store. This creates a link to the test log file for each failing test in the test summary view, and also adds the link to each test's additional details table in the Backslash web interface.

Use it by running with ``--with-ci-links`` and ensuring that the URL for the build is defined.

.. note:: The plugin will not add any links to the additional details store if the build URL is not defined.

By default the plugin retrieves the build URL from the ``BUILD_URL`` environment variable populated by the Jenkins CI system, but this can be changed by specifying a different environment variable in the ``slash.config.root.plugin_config.ci_links.build_url_environment_variable`` configuration item.

The default template used to generate the link is ``%(build_url)s/artifact/%(log_path)s``, (where ``log_path`` is the log path generated by Slash for the test case), but this can be changed by specifying a different template in the ``slash.config.root.plugin_config.ci_links.link_template`` configuration item.