Skip to content

docs: unify documentation structure across all reporters #452

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gibiw merged 1 commit into from
Feb 9, 2026
Merged

docs: unify documentation structure across all reporters #452

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,4 +59,7 @@ target/
qaseio.lock

#Ipython Notebook
.ipynb_checkpoints
.ipynb_checkpoints

.planning/
CLAUDE.md
230 changes: 168 additions & 62 deletions qase-behave/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,79 +1,76 @@
# [Qase TestOps](https://qase.io) Behave Reporter

[![License](https://lxgaming.github.io/badges/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
[![PyPI version](https://img.shields.io/pypi/v/qase-behave?style=flat-square)](https://pypi.org/project/qase-behave/)
[![PyPI downloads](https://img.shields.io/pypi/dm/qase-behave?style=flat-square)](https://pypi.org/project/qase-behave/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](https://www.apache.org/licenses/LICENSE-2.0)

## Installation
Qase Behave Reporter enables seamless integration between your Behave BDD tests and [Qase TestOps](https://qase.io), providing automatic test result reporting, test case management, and comprehensive test analytics.

## Features

To install the latest version, run:
- Link automated tests to Qase test cases by ID
- Auto-create test cases from your feature files
- Report test results with rich metadata (fields, attachments)
- Automatic step reporting from Gherkin scenarios
- Multi-project reporting support
- Flexible configuration (file, environment variables)

## Installation

```sh
pip install qase-behave
```

## Getting started

The Behave reporter can auto-generate test cases
and suites from your test data.
Test results of subsequent test runs will match the same test cases
as long as their names and file paths don't change.

You can also annotate the tests with the IDs of existing test cases
from Qase.io before executing tests. It's a more reliable way to bind
autotests to test cases, that persists when you rename, move, or
parameterize your tests.

### Metadata

- `qase.id` - set the ID of the test case
- `qase.fields` - set the fields of the test case
- `qase.suite` - set the suite of the test case
- `qase.ignore` - ignore the test case in Qase. The test will be executed, but the results will not be sent to Qase.

For detailed instructions on using annotations and methods, refer to [Usage](docs/usage.md).
## Quick Start

For information about attaching files and content or adding comments to test results, see [Attachments](docs/ATTACHMENTS.md).
**1. Create `qase.config.json` in your project root:**

### Multi-Project Support

Qase Behave Reporter supports sending test results to multiple Qase projects simultaneously.
You can specify different test case IDs for each project using the `@qase.project_id.PROJECT_CODE:IDS` tag format.

For detailed information, configuration, and examples, see the [Multi-Project Support Guide](docs/MULTI_PROJECT.md).
```json
{
"mode": "testops",
"testops": {
"project": "YOUR_PROJECT_CODE",
"api": {
"token": "YOUR_API_TOKEN"
}
}
}
```

For example:
**2. Add Qase ID to your scenario:**

```gherkin
Feature: Example tests
Feature: Authentication

@qase.id:1 @qase.fields:{"description":"It_is_simple_test"} @qase.suite:MySuite
Scenario: Example test
Given I have a simple test
When I run it
Then it should pass
@qase.id:1
Scenario: User can log in with valid credentials
Given I am on the login page
When I enter valid credentials
Then I should see the dashboard
```

To execute Behave tests and report them to Qase.io, run the command:
**3. Run your tests:**

```bash
```sh
behave --format=qase.behave.formatter:QaseFormatter
```

You can try it with the example project at [`examples/behave`](../examples/behave/).

## Configuration

Qase Behave Reporter is configured in multiple ways:
The reporter is configured via (in order of priority):

- using a config file `qase.config.json`
- using environment variables
- using command line options
1. **Environment variables** (`QASE_*`, highest priority)
2. **Config file** (`qase.config.json`)

Environment variables override the values given in the config file,
and command line options override both other values.
### Minimal Configuration

For complete configuration reference, see the [qase-python-commons README](../qase-python-commons/README.md) which contains all available configuration options.
| Option | Environment Variable | Description |
|--------|---------------------|-------------|
| `mode` | `QASE_MODE` | Set to `testops` to enable reporting |
| `testops.project` | `QASE_TESTOPS_PROJECT` | Your Qase project code |
| `testops.api.token` | `QASE_TESTOPS_API_TOKEN` | Your Qase API token |

### Example: qase.config.json
### Example `qase.config.json`

```json
{
Expand All @@ -82,11 +79,10 @@ For complete configuration reference, see the [qase-python-commons README](../qa
"testops": {
"project": "YOUR_PROJECT_CODE",
"api": {
"token": "YOUR_API_TOKEN",
"host": "qase.io"
"token": "YOUR_API_TOKEN"
},
"run": {
"title": "Test run title"
"title": "Behave Automated Run"
},
"batch": {
"size": 100
Expand All @@ -100,21 +96,131 @@ For complete configuration reference, see the [qase-python-commons README](../qa
"format": "json"
}
}
},
"logging": {
"console": true,
"file": false
},
"environment": "local"
}
}
```

> **Full configuration reference:** See [qase-python-commons](../qase-python-commons/README.md) for all available options including logging, status mapping, execution plans, and more.

## Usage

### Link Tests with Test Cases

Associate your scenarios with Qase test cases using the `@qase.id` tag:

```gherkin
Feature: Shopping Cart

@qase.id:1
Scenario: Add item to cart
Given I am on the product page
When I click add to cart
Then the item should be in my cart

@qase.id:2
Scenario: Remove item from cart
Given I have an item in my cart
When I click remove
Then my cart should be empty
```

### Add Metadata

Enhance your scenarios with additional information using the `@qase.fields` tag:

```gherkin
Feature: Checkout

@qase.id:1
@qase.fields:{"severity":"critical","priority":"high","layer":"e2e"}
@qase.suite:Checkout
Scenario: Complete purchase
Given I have items in my cart
When I complete checkout
Then I should see order confirmation
```

**Note:** In field values, use underscores (`_`) instead of spaces. They will be automatically converted.

### Ignore Tests

Exclude specific scenarios from Qase reporting:

```gherkin
Feature: Authentication

@qase.ignore
Scenario: Work in progress test
Given this test is not ready
Then it should not be reported
```

### Test Result Statuses

| Behave Result | Qase Status |
|---------------|-------------|
| Passed | `passed` |
| Failed (AssertionError) | `failed` |
| Failed (other exception) | `invalid` |
| Skipped | `skipped` |

### Attachments

Attach files and content to test results in step definitions:

```python
from behave import given, when, then
from qase.behave import qase

@when('I take a screenshot')
def step_impl(context):
screenshot = context.browser.get_screenshot_as_png()
qase.attach(content=screenshot, file_name="screenshot.png", mime_type="image/png")
```

> For detailed usage examples, see the [Usage Guide](docs/usage.md).

## Running Tests

### Basic Execution

```sh
behave --format=qase.behave.formatter:QaseFormatter
```

### With Environment Variables

```sh
export QASE_MODE=testops
export QASE_TESTOPS_PROJECT=PROJ
export QASE_TESTOPS_API_TOKEN=your_token
behave --format=qase.behave.formatter:QaseFormatter
```

### With Custom Run Title

```sh
export QASE_TESTOPS_RUN_TITLE="Regression Run"
behave --format=qase.behave.formatter:QaseFormatter
```

## Requirements

We maintain the reporter on [LTS versions of Python](https://devguide.python.org/versions/).
- Python >= 3.9
- behave >= 1.2.6

## Documentation

| Guide | Description |
|-------|-------------|
| [Usage Guide](docs/usage.md) | Complete usage reference with all tags and options |
| [Attachments](docs/ATTACHMENTS.md) | Adding screenshots, logs, and files to test results |
| [Multi-Project Support](docs/MULTI_PROJECT.md) | Reporting to multiple Qase projects |

## Examples

`python >= 3.9`
`behave >= 1.2.6`
See the [examples directory](../examples/single/behave/) for complete working examples.

<!-- references -->
## License

Apache License 2.0. See [LICENSE](../LICENSE) for details.
Loading