overhave

Name	overhave JSON
Version	5.1.6 JSON
	download
home_page	None
Summary	Overhave - web-framework for BDD
upload_time	2024-03-22 12:33:38
maintainer	None
docs_url	None
author	Vladislav Mukhamatnurov
requires_python	<3.12,>=3.8.1
license	None
keywords
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

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

--------
Features
--------

* 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)

------------
Installation
------------

You can install **Overhave** via pip from PyPI:

.. code-block:: shell

pip install overhave

--------
Overview
--------

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`, `Test runs`, `Versions` and `Tags`:

* `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/test_runs_img.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
`Groups` subsections;
* `Emulation` - experimental section for alternative tools implementation
(in development).

**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
```PRJ-NUMBER``` and scenario text.

**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 ```OVERHAVE_```, for example ```OVERHAVE_DB_URL```.
If you want to configure settings in more explicit way through context injection,
please see next part of docs.

Context injection
-----------------

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

Service could be configured via application context injection with prepared
instance of `OverhaveContext` object. This context could be set using
```set_context``` function of initialized ```ProxyFactory``` instance.

For example, ```my_custom_context``` prepared. So, application start-up could
be realised with follow code:

.. code-block:: python

from overhave import overhave_app, overhave_admin_factory

factory = overhave_admin_factory()
factory.set_context(my_custom_context)
overhave_app(factory).run(host='localhost', port=8080, debug=True)

**Note**:

* ```overhave_app``` is the prepared `Flask` application with already enabled
Flask Admin and Login Manager plug-ins;
* ```overhave_factory``` is a function for LRU cached instance of the **Overhave**
factory ```ProxyFactory```; the instance has an access to application components,
directly used in ```overhave_app```.
* ```my_custom_context``` is an example of context configuration, see an
example code in `context_example.rst`_.

Redis
---------
* **RedisSentinel** - redis connection through sentinel. To enable sentinel connection use env OVERHAVE_REDIS_SENTINEL_ENABLED=True

* **Redis** - default redis connection without sentinel.

Consumers
---------

**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
```overhave_test_execution_factory```;

* **PUBLICATION** - consumer for features publication with it's own factory
```overhave_publication_factory```;

* **EMULATION** - consumer for specific emulation with it's own factory
```overhave_emulation_factory```.

**Note**: the ```overhave_test_execution_factory``` has ability for context injection
and could be enriched with the custom context as the ```overhave_admin_factory```.

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
current feature is located;
* any amount of arbitrary tags;
* severity tag - implements `Allure`_ severity to feature or just tagged
scenario (for example: ```@severity.blocker```);
* info about feature - who is creator, last editor and publisher;
* task tracker's tickets with format ```PRJ-1234```;

An example of filled feature content is located in
`feature_example.rst`_.

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.

Examples:

.. 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
```OVERHAVE_ADMIN_URL```:

.. code-block:: bash

export OVERHAVE_ADMIN_URL=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
```OVERHAVE_GIT_PROJECT_URL```:

.. code-block:: bash

export OVERHAVE_GIT_PROJECT_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 ```feature request``` or contribute
yourself).

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

language_settings = OverhaveLanguageSettings(step_prefixes=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',
default_target_branch_name='master',
)
client_settings=OverhaveGitlabClientSettings(
url="https://gitlab.mycompany.com",
auth_token=os.environ.get("MY_GITLAB_AUTH_TOKEN"),
)

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(
index_template_path="/path/to/index.html"
)

Authorization strategy
----------------------

**Overhave** provides several authorization strategies, declared by
```AuthorizationStrategy``` enum:

* `Simple` - strategy without real authorization.
Each user could use preferred name. This name will be used for user
authority. Each user is unique. Password not required.

* `Default` - strategy with real authorization.
Each user could use only registered credentials.

* `LDAP` - strategy with authorization using remote LDAP server.
Each user should use his LDAP credentials. LDAP
server returns user groups. If user in default 'admin' group or his groups
list contains admin group - user will be authorized. If user already placed
in database - user will be authorized too. No one password stores.

Appropriate strategy and additional data should be placed into
```OverhaveAuthorizationSettings```, for example LDAP strategy could be
configured like this:

.. code-block:: python

auth_settings = OverhaveAuthorizationSettings(auth_strategy=AuthorizationStrategy.LDAP)
ldap_manager_settings = OverhaveLdapManagerSettings(ldap_admin_group="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

OVERHAVE_S3_ENABLED=true
OVERHAVE_S3_URL=https://s3.example.com
OVERHAVE_S3_ACCESS_KEY=<MY_ACCESS_KEY>
OVERHAVE_S3_SECRET_KEY=<MY_SECRET_KEY>

Optionally, you could change default settings also:

.. code-block:: shell

OVERHAVE_S3_VERIFY=false
OVERHAVE_S3_AUTOCREATE_BUCKETS=true

The framework with enabled ```OVERHAVE_S3_AUTOCREATE_BUCKETS``` flag will create
application buckets in remote storage if buckets don't exist.

API
---
**Overhave** has it's own application programming interface, based on
`FastAPI`_.

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

**Overhave** openapi.json through `Swagger`_

Current possibilities could be displayed through built-in
`Swagger`_ - just run the API and open http://localhost:8000 in your
browser.

.. code-block:: bash

overhave api -p 8000

Interface has authorization through `oauth2`_ scheme, so you should setup
```OVERHAVE_API_AUTH_SECRET_KEY``` for usage.

Right now, API implements types of resources:

* `feature_tags`
get feature tag or get list of feature tags;
* `features`
get features info by tag ID or tag value;
* `test_users`
get test user info, specification, put new specification or delete
test user;
* `test_runs`
get test run info or create test run with given parameters;
* `emulations`
get emulation runs by test user id.

------------
Contributing
------------

Contributions are very welcome.

Preparation
-----------

Project installation is very easy
and takes just few prepared commands (`make pre-init` works only for Ubuntu;
so you can install same packages for your OS manually):

.. code-block:: shell

make pre-init
make init

Packages management is provided by `Poetry`_.

Check
-----

Tests can be run with `Tox`_. `Docker-compose`_ is used for other services
preparation and serving, such as database. Simple tests and linters execution:

.. code-block:: shell

make up
make test
make lint

Please, see `make` file and discover useful shortcuts. You could run tests
in docker container also:

.. code-block:: shell

make test-docker

Documentation build
-------------------

Project documentation could be built via `Sphinx`_ and simple `make` command:

.. code-block:: shell

make build-docs

By default, the documentation will be built using `html` builder into `_build`
directory.

-------
License
-------

Distributed under the terms of the `GNU GPLv2`_ license.

------
Issues
------

If you encounter any problems, please report them here in section `Issues`
with a detailed description.

.. _`Overhave`: https://github.com/TinkoffCreditSystems/overhave
.. _`Pydantic`: https://github.com/samuelcolvin/pydantic
.. _`Flask Admin`: https://github.com/flask-admin/flask-admin
.. _`Ace`: https://github.com/ajaxorg/ace
.. _`PyTest`: https://github.com/pytest-dev/pytest
.. _`pytest-bdd`: https://github.com/pytest-dev/pytest-bdd
.. _`Allure`: https://github.com/allure-framework/allure-python
.. _`Allure CLI`: https://docs.qameta.io/allure/#_get_started
.. _`Bitbucket`: https://www.atlassian.com/git
.. _`GitLab`: https://about.gitlab.com
.. _`python-gitlab`: https://python-gitlab.readthedocs.io
.. _`SQLAlchemy`: https://github.com/sqlalchemy/sqlalchemy
.. _`Walrus`: https://github.com/coleifer/walrus
.. _`GoTTY`: https://github.com/yudai/gotty
.. _`GNU GPLv2`: http://www.apache.org/licenses/LICENSE-2.0
.. _`Tox`: https://github.com/tox-dev/tox
.. _`Poetry`: https://github.com/python-poetry/poetry
.. _`Docker-compose`: https://docs.docker.com/compose
.. _`Typer`: https://github.com/tiangolo/typer
.. _`Sphinx`: https://github.com/sphinx-doc/sphinx
.. _`boto3`: https://github.com/boto/boto3
.. _`git`: https://git-scm.com/
.. _`FastAPI`: https://github.com/tiangolo/fastapi
.. _`Swagger`: https://swagger.io
.. _`oauth2`: https://oauth.net/2/
.. _`context_example.rst`: https://github.com/TinkoffCreditSystems/overhave/blob/master/docs/includes/context_example.rst
.. _`feature_example.rst`: https://github.com/TinkoffCreditSystems/overhave/blob/master/docs/includes/features_structure_example/feature_type_1/full_feature_example_en.feature

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "overhave",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<3.12,>=3.8.1",
    "maintainer_email": null,
    "keywords": null,
    "author": "Vladislav Mukhamatnurov",
    "author_email": "livestreamepidemz@yandex.ru",
    "download_url": "https://files.pythonhosted.org/packages/21/1e/04af9621d172bf2fcae24de084e1b5bcf63fe8777550ee97cf2056809dd3/overhave-5.1.6.tar.gz",
    "platform": null,
    "description": "========\nOverhave\n========\n\n.. figure:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/label_img.png\n  :width: 700\n  :align: center\n  :alt: Overhave framework\n\n  `Overhave`_ is the web-framework for BDD: scalable, configurable, easy to use, based on\n  `Flask Admin`_ and `Pydantic`_.\n\n  .. image:: https://github.com/TinkoffCreditSystems/overhave/workflows/CI/badge.svg\n    :target: https://github.com/TinkoffCreditSystems/overhave/actions?query=workflow%3ACI\n    :alt: CI\n\n  .. image:: https://img.shields.io/pypi/pyversions/overhave.svg\n    :target: https://pypi.org/project/overhave\n    :alt: Python versions\n\n  .. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n    :target: https://github.com/TinkoffCreditSystems/overhave\n    :alt: Code style\n\n  .. image:: https://img.shields.io/pypi/v/overhave?color=%2334D058&label=pypi%20package\n    :target: https://pypi.org/project/overhave\n    :alt: Package version\n\n  .. image:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/coverage.svg\n    :target: https://github.com/TinkoffCreditSystems/overhave\n    :alt: PyTest Coverage percent\n    \n  .. image:: https://img.shields.io/pypi/dm/overhave.svg\n    :target: https://pypi.org/project/overhave\n    :alt: Downloads per month\n\n--------\nFeatures\n--------\n\n* Ready web-interface for easy BDD features management with `Ace`_ editor\n* Traditional Gherkin format for scenarios provided by `pytest-bdd`_\n* Execution and reporting of BDD features based on `Allure`_\n* Auto-collection of `pytest-bdd`_ steps and display on web-interface\n* Simple scenarios structure, easy horizontal scaling\n* Built-in wrappers for `pytest-bdd`_ hooks to supplement `Allure`_ report\n* Ability to create and use several BDD keywords dictionary with different languages\n* Versioning and deployment of scenario drafts to `Bitbucket`_ or `GitLab`_\n* Synchronization between `git`_ repository and database with features\n* Built-in configurable access management of users and groups\n* Configurable strategy for user authorization (LDAP also provided)\n* Database schema based on `SQLAlchemy`_ models and works with PostgreSQL\n* Still configurable as `Flask Admin`_, supports plug-ins and extensions\n* Has built-in API application with Swagger docs, based on `FastAPI`_\n* Distributed `producer-consumer` architecture based on `Walrus`_ Redis streams\n* Command-line interface, provided with `Typer`_\n* Integrated interaction for files storage with s3-cloud based on `boto3`_\n* Web-browser emulation ability with custom toolkit (`GoTTY`_, for example)\n\n------------\nInstallation\n------------\n\nYou can install **Overhave** via pip from PyPI:\n\n.. code-block:: shell\n\n    pip install overhave\n\n--------\nOverview\n--------\n\nWeb-interface\n-------------\n\nThe web-interface is a basic tool for BDD features management. It consists of:\n\n* `Info` - index page with optional information about your tool or project;\n* `Scenarios` - section for features management, contains subsections\n    `Features`, `Test runs`, `Versions` and `Tags`:\n\n    * `Features`\n        gives an interface for features records management and provides info\n        about id, name author, time, editor and publishing status; it is possible\n        to search, edit or delete items through Script panel.\n\n        .. figure:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/label_img.png\n          :width: 500\n          :align: center\n          :alt: Features list\n\n    * `Test runs`\n        gives an interface for test runs management and provides info about.\n\n        .. figure:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/test_runs_img.png\n          :width: 500\n          :align: center\n          :alt: Test runs list\n\n    * Versions\n        contains feature versions in corresponding to test runs; versions contains PR-links to\n        the remote Git repository.\n\n        .. figure:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/versions_img.png\n          :width: 500\n          :align: center\n          :alt: Feature published versions list\n\n    * Tags\n        contains tags values, which are used for feature's tagging.\n\n        .. figure:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/tags_img.png\n          :width: 500\n          :align: center\n          :alt: Feature published versions list\n\n* `Test users` - section for viewing and configuring test users;\n* `Access` - section for access management, contains `Users` and\n    `Groups` subsections;\n* `Emulation` - experimental section for alternative tools implementation\n    (in development).\n\n**Overhave** features could be created and/or edited through special\n*script panel* in feature edit mode. Feature should have type registered by the\napplication, unique name, specified tasks list with the traditional format\n```PRJ-NUMBER``` and scenario text.\n\n**Script panel** has `pytest-bdd`_ steps table on the right side of interface.\nThese steps should be defined in appropriate fixture modules and registered\nat the application on start-up to be displayed.\n\n\n.. figure:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/panel_img.png\n  :width: 600\n  :align: center\n  :alt: Script panel\n\n  Example of **Overhave** script panel in feature edit mode\n\nAllure report\n-------------\n\n**Overhave** generates `Allure`_ report after tests execution in web-interface.\nIf you execute tests manually through `PyTest`_, these results are could be\nconverted into the `Allure`_ report also with the `Allure CLI`_ tool.\nThis report contains scenarios descriptions as they are described in features.\n\n.. figure:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/report_img.png\n  :width: 600\n  :align: center\n  :alt: Allure test-case report\n\n  Example of generated `Allure`_ report after execution of **Overhave**'s feature\n\nDemo-mode (Quickstart)\n----------------------\n\n**Overhave** has special demo-mode (in development), which could be possibly\nused for framework demonstration and manual debugging / testing. The framework\nprovides a CLI entrypoints for easy server run in debug mode:\n\n.. code-block:: shell\n\n    make up  # start PostgreSQL database and Redis\n    overhave db create-all  # create Overhave database schema\n    overhave-demo admin  # start Overhave admin on port 8076 in debug mode\n    overhave-demo consumer -s test  # start Overhave test execution consumer\n\n**Note**: you could run admin in special mode, which does not require\nconsumers. This mode uses *threadpool* for running testing and publication\ntasks asynchronously:\n\n.. code-block:: shell\n\n    overhave-demo admin --threadpool --language=ru\n\nBut this *threadpool* mode is unscalable in *kubernetes* paradigm. So,\nit's highly recommended to use corresponding consumers exactly.\n\nCommand-line interface\n----------------------\n\n**Overhave** has a CLI that provides a simple way to start service web-interface,\nrun consumer and execute basic database operations. Examples are below:\n\n.. code-block:: shell\n\n    overhave db create-all\n    overhave admin --port 8080\n    overhave consumer -s publication\n    overhave api -p 8000 -w 4\n\n**Note**: service start-up takes a set of settings, so you can set them through\nvirtual environment with prefix ```OVERHAVE_```, for example ```OVERHAVE_DB_URL```.\nIf you want to configure settings in more explicit way through context injection,\nplease see next part of docs.\n\nContext injection\n-----------------\n\nContext setting\n^^^^^^^^^^^^^^^\n\nService could be configured via application context injection with prepared\ninstance of `OverhaveContext` object. This context could be set using\n```set_context``` function of initialized ```ProxyFactory``` instance.\n\nFor example, ```my_custom_context``` prepared. So, application start-up could\nbe realised with follow code:\n\n.. code-block:: python\n\n    from overhave import overhave_app, overhave_admin_factory\n\n    factory = overhave_admin_factory()\n    factory.set_context(my_custom_context)\n    overhave_app(factory).run(host='localhost', port=8080, debug=True)\n\n**Note**:\n\n* ```overhave_app``` is the prepared `Flask` application with already enabled\n    Flask Admin and Login Manager plug-ins;\n* ```overhave_factory``` is a function for LRU cached instance of the **Overhave**\n    factory ```ProxyFactory```; the instance has an access to application components,\n    directly used in ```overhave_app```.\n* ```my_custom_context``` is an example of context configuration, see an\n    example code in `context_example.rst`_.\n\nRedis\n---------\n* **RedisSentinel** - redis connection through sentinel. To enable sentinel connection use env OVERHAVE_REDIS_SENTINEL_ENABLED=True\n\n* **Redis** - default redis connection without sentinel.\n\nConsumers\n---------\n\n**Overhave** has `producer-consumer` architecture, based on Redis streams,\nand supported 3 consumer's types:\n\n* **TEST** - consumer for test execution with it's own factory\n    ```overhave_test_execution_factory```;\n\n* **PUBLICATION** - consumer for features publication with it's own factory\n    ```overhave_publication_factory```;\n\n* **EMULATION** - consumer for specific emulation with it's own factory\n    ```overhave_emulation_factory```.\n\n**Note**: the ```overhave_test_execution_factory``` has ability for context injection\nand could be enriched with the custom context as the ```overhave_admin_factory```.\n\nProject structure\n-----------------\n\n**Overhave** supports it's own special project structure:\n\n.. image:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/project_structure.png\n  :width: 300\n  :alt: **Overhave** project structure\n\nThe right approach is to create a **root directory** (like \"demo\" inside the current\nrepository) that contains **features**, **fixtures** and **steps** directories.\n\nThe **Features** directory contains different feature types as\nseparate directories, each of them corresponds to predefined `pytest-bdd`_\nset of steps.\n\nThe **Fixtures** directory contains typical `PyTest`_ modules splitted by different\nfeature types. These modules are used for `pytest-bdd`_ isolated test runs. It is\nnecessary because of special mechanism of `pytest-bdd`_ steps collection.\n\nThe **Steps** directory contains `pytest-bdd`_ steps packages splitted by differrent\nfeature types also. Each steps subdirectory has it's own declared steps in according\nto supported feature type.\n\nSo, it is possible to create your own horizontal structure of\ndifferent product directions with unique steps and `PyTest`_ fixtures.\n\n**Note**: this structure is used in **Overhave** application. The formed data\ngives a possibility to specify registered feature type in the web-interface\n*script panel*. Also, this structure defines which steps will be displayed in\nthe right side of *script panel*.\n\nFeature format\n--------------\n\n**Overhave** has it's own special feature's text format, which inherits\nGherkin from `pytest-bdd`_ with unique updates:\n\n* required tag that is related to existing feature type directory, where\n    current feature is located;\n* any amount of arbitrary tags;\n* severity tag - implements `Allure`_ severity to feature or just tagged\n    scenario (for example: ```@severity.blocker```);\n* info about feature - who is creator, last editor and publisher;\n* task tracker's tickets with format ```PRJ-1234```;\n\nAn example of filled feature content is located in\n`feature_example.rst`_.\n\nPytest markers\n--------------\n\n**Overhave** implements solution for `PyTest`_ markers usage with custom\nadditional information:\n\n* \"`disabled`\": same as `skip` marker, but it's necessary to setup reason;\n* \"`xfail`\": traditional `xfail` with strict reason presence.\n\nExamples:\n\n.. code-block:: gherkin\n\n    @disabled(not ready)\n    Feature: My business feature\n\n.. code-block:: gherkin\n\n    @disabled(TODO: https://tracker.myorg.com/browse/PRJ-333; deadline 01.01.25)\n    Scenario: Yet another business feature\n\n\n.. code-block:: gherkin\n\n    @xfail(bug: https://tracker.myorg.com/browse/PRJ-555)\n    Scenario outline: Other business feature\n\nIf reason contains URL, so **Overhave** will attach `Allure` link to report:\nfor `disabled` - it will be `LinkType.LINK`, for `xfail` - `LinkType.ISSUE`.\n\nFeature links\n-------------\n\n**Overhave** has ability to set links to it's own admin service in `Allure`_\ntest-cases. Link will be set automatically when you generate `Allure`_ report.\nThis function can be enabled via setup of environment variable\n```OVERHAVE_ADMIN_URL```:\n\n.. code-block:: bash\n\n    export OVERHAVE_ADMIN_URL=https://overhave-admin.myorg.com\n\nAlso, **Overhave** has ability to set links to feature file in `Git`_ repository.\nLink will be set automatically when you generate `Allure`_ report. This function\ncan be enabled via setup of environment variable\n```OVERHAVE_GIT_PROJECT_URL```:\n\n.. code-block:: bash\n\n    export OVERHAVE_GIT_PROJECT_URL=https://git.myorg.com/bdd-features-repo\n\n\nLanguage\n--------\n\nThe web-interface language is ENG by default and could not be switched\n(if it's necessary - please, create a ```feature request``` or contribute\nyourself).\n\nThe feature text as well as `pytest-bdd`_ BDD keywords are configurable\nwith **Overhave** extra models, for example RUS keywords are already defined\nin framework and available for usage:\n\n.. code-block:: python\n\n    from overhave.extra import RUSSIAN_PREFIXES\n\n    language_settings = OverhaveLanguageSettings(step_prefixes=RUSSIAN_PREFIXES)\n\n**Note**: you could create your own prefix-value mapping for your language:\n\n.. code-block:: python\n\n    from overhave import StepPrefixesModel\n\n    GERMAN_PREFIXES = StepPrefixesModel(\n        FEATURE=\"Merkmal:\",\n        SCENARIO_OUTLINE=\"Szenario\u00fcbersicht:\",\n        SCENARIO=\"Szenario:\",\n        BACKGROUND=\"Hintergrund:\",\n        EXAMPLES=\"Beispiele:\",\n        EXAMPLES_VERTICAL=\"Beispiele: Vertikal\",\n        GIVEN=\"Gegeben \",\n        WHEN=\"Wann \",\n        THEN=\"Dann \",\n        AND=\"Und \",\n        BUT=\"Aber \",\n    )\n\nGit integration\n---------------\n\n**Overhave** gives an ability to sent your new features or changes to\nremote git repository, which is hosted by `Bitbucket`_ or `GitLab`_.\nIntegration with bitbucket is native, while integration with GitLab\nuses `python-gitlab`_ library.\n\nYou are able to set necessary settings for your project:\n\n.. code-block:: python\n\n    publisher_settings = OverhaveGitlabPublisherSettings(\n        repository_id='123',\n        default_target_branch_name='master',\n    )\n    client_settings=OverhaveGitlabClientSettings(\n        url=\"https://gitlab.mycompany.com\",\n        auth_token=os.environ.get(\"MY_GITLAB_AUTH_TOKEN\"),\n    )\n\nThe pull-request (for Bitbucket) or merge-request (for GitLab)\ncreated when you click the button `Create pull request` on\ntest run result's page. This button is available only for `success`\ntest run's result.\n\n**Note**: one of the most popular cases of GitLab API\nauthentication is the OAUTH2 schema with service account.\nIn according to this schema, you should have OAUTH2 token,\nwhich is might have a short life-time and could not be\nspecified through environment. For this situation, **Overhave**\nhas special `TokenizerClient` with it's own\n`TokenizerClientSettings` - this simple client could take\nthe token from a remote custom GitLab tokenizer service.\n\nGit-to-DataBase synchronization\n-------------------------------\n\n**Overhave** gives an ability to synchronize your current `git`_\nrepository's state with database. It means that your features,\nwhich are located on the database, could be updated - and the source\nof updates is your repository.\n\n**For example**: you had to do bulk data replacement in `git`_\nrepository, and now you want to deliver changes to remote database.\nThis not so easy matter could be solved with **Overhave** special\ntooling:\n\nYou are able to set necessary settings for your project:\n\n.. code-block:: bash\n\n    overhave sync run  # only update existing features\n    overhave sync run --create-db-features  # update + create new features\n    overhave sync run --pull-repository  # pull git repo and run sync\n\nYou are able to test this tool with **Overhave** demo mode.\nBy default, 3 features are created in demo database. Just try\nto change them or create new features and run synchronization\ncommand - you will get the result.\n\n.. code-block:: bash\n\n    overhave-demo sync-run  # or with '--create-db-features'\n\n**Overhave** supports validation of existing feature files.\nCommand try to parse features and fill defined feature info format.\nIf there is any problem, special error will be thrown.\n\n.. code-block:: bash\n\n    overhave sync validate-features\n    overhave sync validate-features --raise-if-nullable-id\n    overhave sync validate-features --pull-repository\n\nAnd yes, your are able to try it with demo mode:\n\n.. code-block:: bash\n\n    overhave-demo validate-features\n    overhave sync validate-features -r  # --raise-if-nullable-id\n\nCustom index\n------------\n\n**Overhave** gives an ability to set custom index.html file for rendering. Path\nto file could be set through environment as well as set with context:\n\n.. code-block:: python\n\n    admin_settings = OverhaveAdminSettings(\n        index_template_path=\"/path/to/index.html\"\n    )\n\nAuthorization strategy\n----------------------\n\n**Overhave** provides several authorization strategies, declared by\n```AuthorizationStrategy``` enum:\n\n* `Simple` - strategy without real authorization.\n    Each user could use preferred name. This name will be used for user\n    authority. Each user is unique. Password not required.\n\n* `Default` - strategy with real authorization.\n    Each user could use only registered credentials.\n\n* `LDAP` - strategy with authorization using remote LDAP server.\n    Each user should use his LDAP credentials. LDAP\n    server returns user groups. If user in default 'admin' group or his groups\n    list contains admin group - user will be authorized. If user already placed\n    in database - user will be authorized too. No one password stores.\n\nAppropriate strategy and additional data should be placed into\n```OverhaveAuthorizationSettings```, for example LDAP strategy could be\nconfigured like this:\n\n.. code-block:: python\n\n    auth_settings = OverhaveAuthorizationSettings(auth_strategy=AuthorizationStrategy.LDAP)\n    ldap_manager_settings = OverhaveLdapManagerSettings(ldap_admin_group=\"admin\")\n\nS3 cloud\n--------\n\n**Overhave** implements functionality for *s3* cloud interactions, such as\nbucket creation and deletion, files uploading, downloading and deletion.\nThe framework provides an ability to store reports and other files in\nthe remote s3 cloud storage. You could enrich your environment with following\nsettings:\n\n.. code-block:: shell\n\n    OVERHAVE_S3_ENABLED=true\n    OVERHAVE_S3_URL=https://s3.example.com\n    OVERHAVE_S3_ACCESS_KEY=<MY_ACCESS_KEY>\n    OVERHAVE_S3_SECRET_KEY=<MY_SECRET_KEY>\n\nOptionally, you could change default settings also:\n\n.. code-block:: shell\n\n    OVERHAVE_S3_VERIFY=false\n    OVERHAVE_S3_AUTOCREATE_BUCKETS=true\n\nThe framework with enabled ```OVERHAVE_S3_AUTOCREATE_BUCKETS``` flag will create\napplication buckets in remote storage if buckets don't exist.\n\nAPI\n---\n**Overhave** has it's own application programming interface, based on\n`FastAPI`_.\n\n.. figure:: https://raw.githubusercontent.com/TinkoffCreditSystems/overhave/master/docs/includes/images/api_img.png\n  :width: 600\n  :align: center\n  :alt: Allure test-case report\n\n  **Overhave** openapi.json through `Swagger`_\n\nCurrent possibilities could be displayed through built-in\n`Swagger`_ - just run the API and open http://localhost:8000 in your\nbrowser.\n\n.. code-block:: bash\n\n    overhave api -p 8000\n\nInterface has authorization through `oauth2`_ scheme, so you should setup\n```OVERHAVE_API_AUTH_SECRET_KEY``` for usage.\n\nRight now, API implements types of resources:\n\n* `feature_tags`\n    get feature tag or get list of feature tags;\n* `features`\n    get features info by tag ID or tag value;\n* `test_users`\n    get test user info, specification, put new specification or delete\n    test user;\n* `test_runs`\n    get test run info or create test run with given parameters;\n* `emulations`\n    get emulation runs by test user id.\n\n------------\nContributing\n------------\n\nContributions are very welcome.\n\nPreparation\n-----------\n\nProject installation is very easy\nand takes just few prepared commands (`make pre-init` works only for Ubuntu;\nso you can install same packages for your OS manually):\n\n.. code-block:: shell\n\n    make pre-init\n    make init\n\nPackages management is provided by `Poetry`_.\n\nCheck\n-----\n\nTests can be run with `Tox`_. `Docker-compose`_ is used for other services\npreparation and serving, such as database. Simple tests and linters execution:\n\n.. code-block:: shell\n\n    make up\n    make test\n    make lint\n\nPlease, see `make` file and discover useful shortcuts. You could run tests\nin docker container also:\n\n.. code-block:: shell\n\n    make test-docker\n\nDocumentation build\n-------------------\n\nProject documentation could be built via `Sphinx`_ and simple `make` command:\n\n.. code-block:: shell\n\n    make build-docs\n\nBy default, the documentation will be built using `html` builder into `_build`\ndirectory.\n\n-------\nLicense\n-------\n\nDistributed under the terms of the `GNU GPLv2`_ license.\n\n------\nIssues\n------\n\nIf you encounter any problems, please report them here in section `Issues`\nwith a detailed description.\n\n.. _`Overhave`: https://github.com/TinkoffCreditSystems/overhave\n.. _`Pydantic`: https://github.com/samuelcolvin/pydantic\n.. _`Flask Admin`: https://github.com/flask-admin/flask-admin\n.. _`Ace`: https://github.com/ajaxorg/ace\n.. _`PyTest`: https://github.com/pytest-dev/pytest\n.. _`pytest-bdd`: https://github.com/pytest-dev/pytest-bdd\n.. _`Allure`: https://github.com/allure-framework/allure-python\n.. _`Allure CLI`: https://docs.qameta.io/allure/#_get_started\n.. _`Bitbucket`: https://www.atlassian.com/git\n.. _`GitLab`: https://about.gitlab.com\n.. _`python-gitlab`: https://python-gitlab.readthedocs.io\n.. _`SQLAlchemy`: https://github.com/sqlalchemy/sqlalchemy\n.. _`Walrus`: https://github.com/coleifer/walrus\n.. _`GoTTY`: https://github.com/yudai/gotty\n.. _`GNU GPLv2`: http://www.apache.org/licenses/LICENSE-2.0\n.. _`Tox`: https://github.com/tox-dev/tox\n.. _`Poetry`: https://github.com/python-poetry/poetry\n.. _`Docker-compose`: https://docs.docker.com/compose\n.. _`Typer`: https://github.com/tiangolo/typer\n.. _`Sphinx`: https://github.com/sphinx-doc/sphinx\n.. _`boto3`: https://github.com/boto/boto3\n.. _`git`: https://git-scm.com/\n.. _`FastAPI`: https://github.com/tiangolo/fastapi\n.. _`Swagger`: https://swagger.io\n.. _`oauth2`: https://oauth.net/2/\n.. _`context_example.rst`: https://github.com/TinkoffCreditSystems/overhave/blob/master/docs/includes/context_example.rst\n.. _`feature_example.rst`: https://github.com/TinkoffCreditSystems/overhave/blob/master/docs/includes/features_structure_example/feature_type_1/full_feature_example_en.feature\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "Overhave - web-framework for BDD",
    "version": "5.1.6",
    "project_urls": null,
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "69ab3a2e0e8b805c841cf0991f356f8db468619764c0f6ac886fdb28ecf1120f",
                "md5": "3a313b21c9512104d09025930435709e",
                "sha256": "cdf2819a028075148e446858cdca3edcdeaa7ffb578b9279f416cc54fd2dec1e"
            },
            "downloads": -1,
            "filename": "overhave-5.1.6-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "3a313b21c9512104d09025930435709e",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<3.12,>=3.8.1",
            "size": 341768,
            "upload_time": "2024-03-22T12:33:35",
            "upload_time_iso_8601": "2024-03-22T12:33:35.155577Z",
            "url": "https://files.pythonhosted.org/packages/69/ab/3a2e0e8b805c841cf0991f356f8db468619764c0f6ac886fdb28ecf1120f/overhave-5.1.6-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "211e04af9621d172bf2fcae24de084e1b5bcf63fe8777550ee97cf2056809dd3",
                "md5": "19f2291fd2481d56d51d7e5a4a4cd980",
                "sha256": "8a2e1641a556d4cbc4d2ee1a2be4c2a107e88c416cb8683b4cf0352c437e0527"
            },
            "downloads": -1,
            "filename": "overhave-5.1.6.tar.gz",
            "has_sig": false,
            "md5_digest": "19f2291fd2481d56d51d7e5a4a4cd980",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<3.12,>=3.8.1",
            "size": 267391,
            "upload_time": "2024-03-22T12:33:38",
            "upload_time_iso_8601": "2024-03-22T12:33:38.290676Z",
            "url": "https://files.pythonhosted.org/packages/21/1e/04af9621d172bf2fcae24de084e1b5bcf63fe8777550ee97cf2056809dd3/overhave-5.1.6.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-03-22 12:33:38",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "overhave"
}

Vladislav Mukhamatnurov