Backslash Documentation Release 2.6.3 Rotem Yaari

Home , Backslash

Backslash Documentation Release 2.6.3

Rotem Yaari

Dec 17, 2018

Contents

1 Overview 1

2 Getting Started 3 2.1 Installation...... 3 2.2 Server Conﬁguration...... 5 2.3 Client Conﬁguration...... 7

3 Indices and tables 9

i ii CHAPTER 1

Overview

Backslash is a test reporting service, intended to help you make sense of automation efforts in your organization. Backslash exposes an API helping you report test runs, results, logs, metadata, failures and more. Backslash has a nice UI helping you sift through the results and ﬁnd what you’re looking for to grok the big picture of testing your products.

1 Backslash Documentation, Release 2.6.3

2 Chapter 1. Overview CHAPTER 2

Getting Started

For details about how to install and conﬁgure Backslash, please refer to the Installation chapter. Contents:

2.1 Installation

There are several ways to get Backslash up and running, but the simplest way is probably using Docker and docker- compose.

2.1.1 Step 1: Install Prerequisites

To run Backslash as a Docker container you’ll need to have Docker installed. This is well covered in the Docker installation guide. You will also need to install docker-compose, which is covered here.

2.1.2 Step 2: Obtain the Compose File

In order for Backslash to run, it needs its various supporting services to run in adjacent containers. docker-compose takes care of this by starting the various services in their respective containers and linking the various pieces together, but in order to do so it needs the configuration file that specifies the deployment. You can download the reference docker-compose file from the Backslash repository:

$ mkdir /opt/backslash $ mkdir /opt/backslash/docker $ curl https://raw.githubusercontent.com/getslash/backslash/master/docker/docker-

˓→compose.yml > /opt/backslash/docker/docker-compose.yml

Note: The docker-compose reference file might change as versions progress and more services are needed or modifi- cations to existing services are needed. You will need to keep track of this file before upgrading.

3 Backslash Documentation, Release 2.6.3

2.1.3 Step 3: Conﬁgure Backslash to Run as a Service

Once you have the compose file in place, you can configure your service to run on your host server. We recommend using systemd to achieve this (which is shown here), but you can use other mechanisms or approaches as you see fit. Create a unit description file – we’ll call it here backslash-docker – and place it in systemd’s configuration directory as /etc/systemd/system/backslash-docker.service:

# /etc/systemd/system/backslash-docker.service [Unit] Description=Backslash test reporting service Requires=docker.service After=docker.service

[Service] Type=oneshot RemainAfterExit=yes WorkingDirectory=/opt/backslash/docker ExecStartPre=-/usr/local/bin/docker-compose-f docker-compose.yml-p backslash down ExecStart=/usr/local/bin/docker-compose-f docker-compose.yml-p backslash up-d ExecStop=/usr/local/bin/docker-compose-f docker-compose.yml-p backslash down

[Install] WantedBy=multi-user.target

Once you have created the unit ﬁle you can enable it to start on boot:

$ systemctl daemon-reload $ systemctl enable backslash-docker

2.1.4 Step 4: Start Backslash

You can start Backslash by running:

$ systemctl start backslash-docker

Note: The initial execution will take longer than usual because the supporting images have to be fetched from the Internet. If you want to see the progress yourself, you can consider running docker-compose manually on the ﬁrst run

Now that the server is up and running, it’s time to conﬁgure your server. You can read about it in the Server Conﬁgu- ration section.

2.1.5 Upgrade

The way to upgrade an existing deployment to the latest version is: 1. update the docker image: $ docker pull getslash/backslash 2. restart the daemon: $ sudo systemctl restart backslash-docker

4 Chapter 2. Getting Started Backslash Documentation, Release 2.6.3

2.2 Server Conﬁguration

2.2.1 Initial Setup

When the server ﬁrst comes up, browsing to it will take you to an initial setup screen. The screen will prompt you for the following details: • Admin email/password: This will specify the local admin account used to manage Backslash • Default Email Domain: For users logging in with their user names, expecting the email domain to be automati- cally added upon authentication, you can set this optional ﬁeld to be your organization domain. • Enable Google OAuth2: Once checked, you will be able to enter the client ID and client secret as obtained from the Google Credentials console, enabling users to log in via the Google federated login mechanism • Enable LDAP: If checked, will ask for LDAP URI and base DN, enabling you to log in users via your organization’s LDAP service.

2.2.2 Optional Conﬁguration

Backslash uses an internal Docker volume for storing configuration files, some of which enable specific behaviors at runtime. In order to customize these files, you’ll have to do the following on a new instance of Backslash: 1. In the Docker compose file, change the locations referring to the conf volume, and set them to point at where you want to store the config files. For example, change conf:/conf to /my/backslash/config/ files:/conf. This needs to be done in several places in the configuration file 2. Start Backslash. You’ll see files created in that directory, especially a file named 000-private.yml. You can now add YAML files to this directory, and they will be read and loaded when the server starts.

Note: The conﬁguration directory is secret and should not be shared or opened for access by anyone except for administrators.

Create a file which will be used for your specific settings, e.g. 001-deployment.yml – we will use this file to specify more options.

HTTPS

Backslash supports serving via HTTPS, in which case it prefers secure connections over insecure ones. To activate SSL, set the BACKSLASH_HOSTNAME environment variable in your compose file, set BACKSLASH_USE_SSL to yes, and place your certificate and key file in your config directory, under the names certificate.crt and server.key respectively.

Display Names

By default, Backslash calls test subjects “Subjects” and related entities “Related”. If you want to change these names when displayed, you can do this via the display_names conﬁg in your 001-deployment.yml mentioned above:

2.2. Server Conﬁguration 5 Backslash Documentation, Release 2.6.3

... display_names: subject: microwave related: plate

This will make subjects be called “microwaves” in all relevant contexts, and related entities be called “plates”.

Metadata Links

In some cases you may have test metadata items which are actually links/URIs pointing at external resources. This could be Jenkins builds, logs collected, or any other external resource related to the test. If you want to allow quick access to those items from the test page, you can specify it via the test_metadata_links variable:

... test_metadata_links: - name: Jenkins build key: jenkins_url icon: http://url/for/jenkins/icon.png

The above will add a link to the test page pointing at the Jenkins build whenever a “jenkins_url” metadata key is found for a test

Metadata Details

Similar to metadata links, you can choose speciﬁc metadata keys to be displayed as informational values for tests and/or sessionsL:

... test_metadata_display_items: - key: my_metadata_key name: My Metadata Key

Or:

... session_metadata_display_items: - key: my_metadata_key name: My Metadata Key

2.2.3 Deployment Customization

Auxiliary Services

In some extreme cases you might want specific APIs or routes served by external containers running customized code. This can be done through customizing the docker-compose configuration. First, create an empty docker-compose file acting as your override (we will be using it as an additional -f argument to docker-compose):

# compose-override.yml version:'3'

Now, create your custom container running your own extension, e.g. a customized Flask app serving /api/ your_custom_api:

6 Chapter 2. Getting Started Backslash Documentation, Release 2.6.3

# compose-override.yml version:'3' services: my_custom_service: image: your-server/image-name command:"your-command-here"

Now we can use the BACKSLASH_ADDITIONAL_ROUTES environment variable to the nginx container to make it forward your new API to your custom container:

# compose-override.yml version:'3' services: ... nginx: environment: -"BACKSLASH_ADDITIONAL_ROUTES=/api/your_custom_api:http://my_custom_service:8000

˓→"

2.2.4 Data Replication

ElasticSearch

Backslash supports replicating data to ElasticSearch. To conﬁgure it, click “Replication” under the “Admin menu”. This functionality is only accessible to admin users.

2.3 Client Conﬁguration

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 speciﬁc 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 ofﬁcial client library for Backslash, which also includes a supplemental plugin for Slash.

2.3.1 Quick Conﬁguration

The simplest conﬁguration is to add the following to your .slashrc in your project’s root directory: 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 ﬁrst 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.

2.3. Client Conﬁguration 7 Backslash Documentation, Release 2.6.3

2.3.2 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: plugin= BackslashPlugin(..., runtoken='xxxxx...')

2.3.3 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: 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)

2.3.4 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:

... 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 ...

8 Chapter 2. Getting Started CHAPTER 3

Indices and tables

• genindex • modindex • search