======== Overhave ========

.. figure:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/label_img.png :width: 700 :align: center :alt: Overhave framework

Overhave_ is the web-framework for BDD: scalable, configurable, easy to use, based on Flask Admin and Pydantic.

.. image:: https://github.com/TinkoffCreditSystems/overhave/workflows/CI/badge.svg :target: https://github.com/TinkoffCreditSystems/overhave/actions?query=workflow%3ACI :alt: CI

.. image:: https://img.shields.io/pypi/pyversions/overhave.svg :target: https://pypi.org/project/overhave :alt: Python versions

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/TinkoffCreditSystems/overhave :alt: Code style

.. image:: https://img.shields.io/pypi/v/overhave?color=%2334D058&label=pypi%20package :target: https://pypi.org/project/overhave :alt: Package version

.. image:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/coverage.svg :target: https://github.com/TinkoffCreditSystems/overhave :alt: PyTest Coverage percent .. image:: https://img.shields.io/pypi/dm/overhave.svg :target: https://pypi.org/project/overhave :alt: Downloads per month

• Ready web-interface for easy BDD features management with Ace_ editor
• Traditional Gherkin format for scenarios provided by pytest-bdd_
• Execution and reporting of BDD features based on Allure_
• Auto-collection of pytest-bdd_ steps and display on web-interface
• Simple scenarios structure, easy horizontal scaling
• Built-in wrappers for pytest-bdd hooks to supplement Allure report
• Ability to create and use several BDD keywords dictionary with different languages
• Versioning and deployment of scenario drafts to Bitbucket or GitLab
• Synchronization between git_ repository and database with features
• Built-in configurable access management of users and groups
• Configurable strategy for user authorization (LDAP also provided)
• Database schema based on SQLAlchemy_ models and works with PostgreSQL
• Still configurable as Flask Admin_, supports plug-ins and extensions
• Has built-in API application with Swagger docs, based on FastAPI_
• Distributed producer-consumer architecture based on Walrus_ Redis streams
• Command-line interface, provided with Typer_
• Integrated interaction for files storage with s3-cloud based on boto3_
• Web-browser emulation ability with custom toolkit (GoTTY_, for example)

You can install Overhave via pip from PyPI:

.. code-block:: shell

pip install overhave

Web-interface

The web-interface is a basic tool for BDD features management. It consists of:

• Info - index page with optional information about your tool or project;
• Scenarios - section for features management, contains subsections

* Features gives an interface for features records management and provides info about id, name author, time, editor and publishing status; it is possible to search, edit or delete items through Script panel.

.. figure:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/label_img.png :width: 500 :align: center :alt: Features list

* Test runs gives an interface for test runs management and provides info about.

.. figure:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/testrunsimg.png :width: 500 :align: center :alt: Test runs list

* Versions contains feature versions in corresponding to test runs; versions contains PR-links to the remote Git repository.

.. figure:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/versions_img.png :width: 500 :align: center :alt: Feature published versions list

* Tags contains tags values, which are used for feature's tagging.

.. figure:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/tags_img.png :width: 500 :align: center :alt: Feature published versions list

• Test users - section for viewing and configuring test users;
• Access - section for access management, contains Users and

• Emulation - experimental section for alternative tools implementation

Overhave features could be created and/or edited through special script panel in feature edit mode. Feature should have type registered by the application, unique name, specified tasks list with the traditional format

-NUMBER

Script panel has pytest-bdd_ steps table on the right side of interface. These steps should be defined in appropriate fixture modules and registered at the application on start-up to be displayed.

.. figure:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/panel_img.png :width: 600 :align: center :alt: Script panel

Example of Overhave script panel in feature edit mode

Allure report

Overhave generates Allure_ report after tests execution in web-interface. If you execute tests manually through PyTest_, these results are could be converted into the Allure report also with the Allure CLI tool. This report contains scenarios descriptions as they are described in features.

.. figure:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/report_img.png :width: 600 :align: center :alt: Allure test-case report

Example of generated Allure_ report after execution of Overhave's feature

Demo-mode (Quickstart)

Overhave has special demo-mode (in development), which could be possibly used for framework demonstration and manual debugging / testing. The framework provides a CLI entrypoints for easy server run in debug mode:

.. code-block:: shell

make up # start PostgreSQL database and Redis overhave db create-all # create Overhave database schema overhave-demo admin # start Overhave admin on port 8076 in debug mode overhave-demo consumer -s test # start Overhave test execution consumer

Note: you could run admin in special mode, which does not require consumers. This mode uses threadpool for running testing and publication tasks asynchronously:

.. code-block:: shell

overhave-demo admin --threadpool --language=ru

But this threadpool mode is unscalable in kubernetes paradigm. So, it's highly recommended to use corresponding consumers exactly.

Command-line interface

Overhave has a CLI that provides a simple way to start service web-interface, run consumer and execute basic database operations. Examples are below:

.. code-block:: shell

overhave db create-all overhave admin --port 8080 overhave consumer -s publication overhave api -p 8000 -w 4

Note: service start-up takes a set of settings, so you can set them through virtual environment with prefix

Context injection

Context setting ^^^^^^^^^^^^^^^

Service could be configured via application context injection with prepared instance of OverhaveContext object. This context could be set using

For example,

.. code-block:: python

from overhave import overhaveapp, overhaveadmin_factory

factory = overhaveadminfactory() factory.setcontext(mycustom_context) overhave_app(factory).run(host='localhost', port=8080, debug=True)

Note:

• is the prepared Flask application with already enabled

• is a function for LRU cached instance of the Overhave

• is an example of context configuration, see an

Redis

• RedisSentinel - redis connection through sentinel. To enable sentinel connection use env OVERHAVEREDISSENTINEL_ENABLED=True

• Redis - default redis connection without sentinel.

Overhave has producer-consumer architecture, based on Redis streams, and supported 3 consumer's types:

• TEST - consumer for test execution with it's own factory

• PUBLICATION - consumer for features publication with it's own factory

• EMULATION - consumer for specific emulation with it's own factory

Note: the

Project structure

Overhave supports it's own special project structure:

.. image:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/project_structure.png :width: 300 :alt: Overhave project structure

The right approach is to create a root directory (like "demo" inside the current repository) that contains features, fixtures and steps directories.

The Features directory contains different feature types as separate directories, each of them corresponds to predefined pytest-bdd_ set of steps.

The Fixtures directory contains typical PyTest_ modules splitted by different feature types. These modules are used for pytest-bdd_ isolated test runs. It is necessary because of special mechanism of pytest-bdd_ steps collection.

The Steps directory contains pytest-bdd_ steps packages splitted by differrent feature types also. Each steps subdirectory has it's own declared steps in according to supported feature type.

So, it is possible to create your own horizontal structure of different product directions with unique steps and PyTest_ fixtures.

Note: this structure is used in Overhave application. The formed data gives a possibility to specify registered feature type in the web-interface script panel. Also, this structure defines which steps will be displayed in the right side of script panel.

Feature format

Overhave has it's own special feature's text format, which inherits Gherkin from pytest-bdd_ with unique updates:

• required tag that is related to existing feature type directory, where

• any amount of arbitrary tags;
• severity tag - implements Allure_ severity to feature or just tagged

@severity.blocker

• info about feature - who is creator, last editor and publisher;
• task tracker's tickets with format

  -1234

  ;

Pytest markers

Overhave implements solution for PyTest_ markers usage with custom additional information:

• "disabled": same as skip marker, but it's necessary to setup reason;
• "xfail": traditional xfail with strict reason presence.

.. code-block:: gherkin

@disabled(not ready) Feature: My business feature

.. code-block:: gherkin

@disabled(TODO: https://tracker.myorg.com/browse/PRJ-333; deadline 01.01.25) Scenario: Yet another business feature

.. code-block:: gherkin

@xfail(bug: https://tracker.myorg.com/browse/PRJ-555) Scenario outline: Other business feature

If reason contains URL, so Overhave will attach Allure link to report: for disabled - it will be LinkType.LINK, for xfail - LinkType.ISSUE.

Feature links

Overhave has ability to set links to it's own admin service in Allure_ test-cases. Link will be set automatically when you generate Allure_ report. This function can be enabled via setup of environment variable

.. code-block:: bash

export OVERHAVEADMINURL=https://overhave-admin.myorg.com

Also, Overhave has ability to set links to feature file in Git_ repository. Link will be set automatically when you generate Allure_ report. This function can be enabled via setup of environment variable

.. code-block:: bash

export OVERHAVEGITPROJECT_URL=https://git.myorg.com/bdd-features-repo

Language

The web-interface language is ENG by default and could not be switched (if it's necessary - please, create a

request

The feature text as well as pytest-bdd_ BDD keywords are configurable with Overhave extra models, for example RUS keywords are already defined in framework and available for usage:

.. code-block:: python

from overhave.extra import RUSSIAN_PREFIXES

languagesettings = OverhaveLanguageSettings(stepprefixes=RUSSIAN_PREFIXES)

Note: you could create your own prefix-value mapping for your language:

.. code-block:: python

from overhave import StepPrefixesModel

GERMAN_PREFIXES = StepPrefixesModel( FEATURE="Merkmal:", SCENARIO_OUTLINE="Szenarioübersicht:", SCENARIO="Szenario:", BACKGROUND="Hintergrund:", EXAMPLES="Beispiele:", EXAMPLES_VERTICAL="Beispiele: Vertikal", GIVEN="Gegeben ", WHEN="Wann ", THEN="Dann ", AND="Und ", BUT="Aber ", )

Git integration

Overhave gives an ability to sent your new features or changes to remote git repository, which is hosted by Bitbucket or GitLab. Integration with bitbucket is native, while integration with GitLab uses python-gitlab_ library.

You are able to set necessary settings for your project:

.. code-block:: python

publisher_settings = OverhaveGitlabPublisherSettings( repository_id='123', defaulttargetbranch_name='master', ) client_settings=OverhaveGitlabClientSettings( url="https://gitlab.mycompany.com", authtoken=os.environ.get("MYGITLABAUTHTOKEN"), )

The pull-request (for Bitbucket) or merge-request (for GitLab) created when you click the button Create pull request on test run result's page. This button is available only for success test run's result.

Note: one of the most popular cases of GitLab API authentication is the OAUTH2 schema with service account. In according to this schema, you should have OAUTH2 token, which is might have a short life-time and could not be specified through environment. For this situation, Overhave has special TokenizerClient with it's own TokenizerClientSettings - this simple client could take the token from a remote custom GitLab tokenizer service.

Git-to-DataBase synchronization

Overhave gives an ability to synchronize your current git_ repository's state with database. It means that your features, which are located on the database, could be updated - and the source of updates is your repository.

For example: you had to do bulk data replacement in git_ repository, and now you want to deliver changes to remote database. This not so easy matter could be solved with Overhave special tooling:

You are able to set necessary settings for your project:

.. code-block:: bash

overhave sync run # only update existing features overhave sync run --create-db-features # update + create new features overhave sync run --pull-repository # pull git repo and run sync

You are able to test this tool with Overhave demo mode. By default, 3 features are created in demo database. Just try to change them or create new features and run synchronization command - you will get the result.

.. code-block:: bash

overhave-demo sync-run # or with '--create-db-features'

Overhave supports validation of existing feature files. Command try to parse features and fill defined feature info format. If there is any problem, special error will be thrown.

.. code-block:: bash

overhave sync validate-features overhave sync validate-features --raise-if-nullable-id overhave sync validate-features --pull-repository

And yes, your are able to try it with demo mode:

.. code-block:: bash

overhave-demo validate-features overhave sync validate-features -r # --raise-if-nullable-id

Custom index

Overhave gives an ability to set custom index.html file for rendering. Path to file could be set through environment as well as set with context:

.. code-block:: python

admin_settings = OverhaveAdminSettings( indextemplatepath="/path/to/index.html" )

Authorization strategy

Overhave provides several authorization strategies, declared by

• Simple - strategy without real authorization.

• Default - strategy with real authorization.

• LDAP - strategy with authorization using remote LDAP server.

Appropriate strategy and additional data should be placed into

.. code-block:: python

authsettings = OverhaveAuthorizationSettings(authstrategy=AuthorizationStrategy.LDAP) ldapmanagersettings = OverhaveLdapManagerSettings(ldapadmingroup="admin")

S3 cloud

Overhave implements functionality for s3 cloud interactions, such as bucket creation and deletion, files uploading, downloading and deletion. The framework provides an ability to store reports and other files in the remote s3 cloud storage. You could enrich your environment with following settings:

.. code-block:: shell

OVERHAVES3ENABLED=true OVERHAVES3URL=https://s3.example.com OVERHAVES3ACCESSKEY=ACCESS_KEY> OVERHAVES3SECRETKEY=SECRET_KEY>