.. 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
Ace_ editorpytest-bdd_Allure_pytest-bdd_ steps and display on web-interfacepytest-bdd_ hooks to supplement Allure_ reportBitbucket_ or GitLab_git_ repository and database with featuresSQLAlchemy_ models and works with PostgreSQLFlask Admin_, supports plug-ins and extensionsFastAPI_producer-consumer architecture based on Walrus_ Redis streamsTyper_boto3_GoTTY_, for example)You can install Overhave via pip from PyPI:
.. code-block:: shell
pip install overhave
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
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
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.
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 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_.RedisSentinel - redis connection through sentinel. To enable sentinel connection use env OVERHAVE_REDIS_SENTINEL_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
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.
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.
Overhave has it's own special feature's text format, which inherits
Gherkin from pytest-bdd_ with unique updates:
Allure_ severity to feature or just tagged
scenario (for example: @severity.blocker);PRJ-1234;An example of filled feature content is located in
feature_example.rst_.
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.
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
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 ",
)
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.
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
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"
)
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")
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.
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.Contributions are very welcome.
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_.
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
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.
Distributed under the terms of the GNU GPLv2_ license.
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
FAQs
Overhave - web-framework for BDD
We found that overhave demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.
Security News
Michigan TypeScript founder Dimitri Mitropoulos implements WebAssembly runtime in TypeScript types, enabling Doom to run after processing 177 terabytes of type definitions.
Security News
vlt's new "reproduce" tool verifies npm packages against their source code, outperforming traditional provenance adoption in the JavaScript ecosystem.