behave-xray 0.2.2
Behave JIRA XRAY results uploader
Keywords: behave JIRA XRAY

# behave-xray

[![PyPi](https://img.shields.io/pypi/v/behave-xray.png)](https://pypi.python.org/pypi/behave-xray)
[![Build Status](https://github.com/fundakol/behave-xray/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/fundakol/behave-xray/actions?query=workflow?master)
[![codecov](https://codecov.io/gh/fundakol/behave-xray/branch/master/graph/badge.svg?token=VV1DMT3605)](https://codecov.io/gh/fundakol/behave-xray)

### Installation


```shell
$ pip install -U behave-xray
```

or from the source:

```shell
$ python setup.py install
```
### Usage

Add JIRA tags to Gherkin scenario:

```gherkin
# --FILE: tutorial.feature
@jira.test_plan('JIRA-3')
Feature: showing off behave
    Feature's description

  @jira.testcase('JIRA-1')
  Scenario: run a simple test
     Given we have behave installed
      When we implement a test
      Then behave will test it for us!

  @jira.testcase('JIRA-2')
  Scenario Outline: Add two numbers in Calc
    Given Calculator is open
    When I add <a> and <b>
    Then result is <result>

  Examples: Sum
      | a | b  | result |
      | 3 | 4  | 7      |
      | 6 | 10 | 18     |
```

This library also supports the feature files [exported from Xray Cucumber tests](https://docs.getxray.app/pages/viewpage.action?pageId=62267221):
```gherkin
Feature: showing off behave
    Feature's description

  @TEST_JIRA-1
  Scenario: run a simple test
     Given we have behave installed
      When we implement a test
      Then behave will test it for us!

  @TEST_JIRA-2
  Scenario Outline: Add two numbers in Calc
    Given Calculator is open
    When I add <a> and <b>
    Then result is <result>

  Examples: Sum
      | a | b  | result |
      | 3 | 4  | 7      |
      | 6 | 10 | 18     |
```

### Configure Jira URL and authentication

Set Jira server API base URL in system environments:

```shell
$ export XRAY_API_BASE_URL=<jira URL>
```

Set system environments for [basic authentication](https://developer.atlassian.com/server/jira/platform/basic-authentication/):

```shell
$ export XRAY_API_USER=<jria username>
$ export XRAY_API_PASSWORD=<user password>
```
Set system environments for [Personal Access Tokens](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html) authentication:
```shell
$ export XRAY_TOKEN=<Xray token>
```

Set system environments for Could server authentication with [Client ID and Client Secret](https://docs.getxray.app/display/XRAYCLOUD/Authentication+-+REST+v2):
```shell
$ export XRAY_CLIENT_ID=<Xray client id>
$ export XRAY_CLIENT_SECRET=<Xray client secret>
```

### Run tests

Run tests against [Jira Xray Server+DC](https://docs.getxray.app/display/XRAY/REST+API):
```shell
$ behave -f behave_xray:XrayFormatter
```

Run tests against [Jira Xray Cloud](https://docs.getxray.app/display/XRAYCLOUD/REST+API) server:
```shell
$ behave -f behave_xray:XrayCloudFormatter
```

You can register formatter in `behave.ini`:
```ini
# -- FILE: behave.ini
[behave.formatters]
xray = behave_xray:XrayCloudFormatter
```

and use with shorter name:
```shell
$ behave --f xray
```

### Attach an evidence to the scenario

One can implement `scenario_xray_result` hook to update results for a scenario.

```python
# - FILE: environment.py
from behave.model import Status
from behave_xray import hookimpl
from behave_xray.evidence import text

@hookimpl
def scenario_xray_result(result, scenario):
    if scenario.status == Status.failed:
        result.evidences.append(text(data='This is scenario evidence', filename=f'{scenario.name}.txt'))
```

### Customize report

Add summary to a report:

```shell
$ behave -f behave_xray:XrayCloudFormatter -D xray.summary='Report generated by behave'
```
or from `behave.ini` file:

```ini
# -- FILE: behave.ini
[behave.userdata]
xray.summary = Report generated by behave
```

Available options:

* `xray.summary`
* `xray.user`
* `xray.version`
* `xray.revision`