Package: overhave
Overhaveis the web-framework for BDD: scalable, configurable, easy to use, based onFlask AdminandPydantic.FeaturesReady web-interface for easy BDD features management withAceeditorTraditional Gherkin format for scenarios provided bypytest-bddExecution and reporting of BDD features based onAllureAuto-collection ofpytest-bddsteps and display on web-interfaceSimple scenarios structure, easy horizontal scalingBuilt-in wrappers forpytest-bddhooks to supplementAllurereportAbility to create and use several BDD keywords dictionary with different languagesVersioning and deployment of scenario drafts toBitbucketorGitLabSynchronization betweengitrepository and database with featuresBuilt-in configurable access management of users and groupsConfigurable strategy for user authorization (LDAP also provided)Database schema based onSQLAlchemymodels and works with PostgreSQLStill configurable asFlask Admin, supports plug-ins and extensionsHas built-in API application with Swagger docs, based onFastAPIDistributedproducer-consumerarchitecture based onWalrusRedis streamsCommand-line interface, provided withTyperIntegrated interaction for files storage with s3-cloud based onboto3Web-browser emulation ability with custom toolkit (GoTTY, for example)InstallationYou can installOverhavevia pip from PyPI:pipinstalloverhaveOverviewWeb-interfaceThe 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 subsectionsFeatures,Test runs,VersionsandTags:Featuresgives 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.Test runsgives an interface for test runs management and provides info about.Versionscontains feature versions in corresponding to test runs; versions contains PR-links to
the remote Git repository.Tagscontains tags values, which are used for feature’s tagging.Test users- section for viewing and configuring test users;Access- section for access management, containsUsersandGroupssubsections;Emulation- experimental section for alternative tools implementation(in development).Overhavefeatures could be created and/or edited through specialscript panelin 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 panelhaspytest-bddsteps 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.Example ofOverhavescript panel in feature edit modeAllure reportOverhavegeneratesAllurereport after tests execution in web-interface.
If you execute tests manually throughPyTest, these results are could be
converted into theAllurereport also with theAllure CLItool.
This report contains scenarios descriptions as they are described in features.Example of generatedAllurereport after execution ofOverhave’s featureDemo-mode (Quickstart)Overhavehas 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:makeup# start PostgreSQL database and Redisoverhavedbcreate-all# create Overhave database schemaoverhave-demoadmin# start Overhave admin on port 8076 in debug modeoverhave-democonsumer-stest# start Overhave test execution consumerNote: you could run admin in special mode, which does not require
consumers. This mode usesthreadpoolfor running testing and publication
tasks asynchronously:overhave-demoadmin--threadpool--language=ruBut thisthreadpoolmode is unscalable inkubernetesparadigm. So,
it’s highly recommended to use corresponding consumers exactly.Command-line interfaceOverhavehas a CLI that provides a simple way to start service web-interface,
run consumer and execute basic database operations. Examples are below:overhavedbcreate-alloverhaveadmin--port8080overhaveconsumer-spublicationoverhaveapi-p8000-w4Note: 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 injectionContext settingService could be configured via application context injection with prepared
instance ofOverhaveContextobject. 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:fromoverhaveimportoverhave_app,overhave_admin_factoryfactory=overhave_admin_factory()factory.set_context(my_custom_context)overhave_app(factory).run(host='localhost',port=8080,debug=True)Note:`overhave_app`is the preparedFlaskapplication with already enabledFlask Admin and Login Manager plug-ins;`overhave_factory`is a function for LRU cached instance of theOverhavefactory`ProxyFactory`; the instance has an access to application components,
directly used in`overhave_app`.`my_custom_context`is an example of context configuration, see anexample code incontext_example.rst.RedisRedisSentinel- redis connection through sentinel. To enable sentinel connection use env OVERHAVE_REDIS_SENTINEL_ENABLED=TrueRedis- default redis connection without sentinel.ConsumersOverhavehasproducer-consumerarchitecture, 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 structureOverhavesupports it’s own special project structure:The right approach is to create aroot directory(like “demo” inside the current
repository) that containsfeatures,fixturesandstepsdirectories.TheFeaturesdirectory contains different feature types as
separate directories, each of them corresponds to predefinedpytest-bddset of steps.TheFixturesdirectory contains typicalPyTestmodules splitted by different
feature types. These modules are used forpytest-bddisolated test runs. It is
necessary because of special mechanism ofpytest-bddsteps collection.TheStepsdirectory containspytest-bddsteps 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 andPyTestfixtures.Note: this structure is used inOverhaveapplication. The formed data
gives a possibility to specify registered feature type in the web-interfacescript panel. Also, this structure defines which steps will be displayed in
the right side ofscript panel.Feature formatOverhavehas it’s own special feature’s text format, which inherits
Gherkin frompytest-bddwith unique updates:required tag that is related to existing feature type directory, wherecurrent feature is located;any amount of arbitrary tags;severity tag - implementsAllureseverity to feature or just taggedscenario (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 infeature_example.rst.Pytest markersOverhaveimplements solution forPyTestmarkers usage with custom
additional information:“disabled”: same asskipmarker, but it’s necessary to setup reason;“xfail”: traditionalxfailwith strict reason presence.Examples:@disabled(notready)Feature:My business feature@disabled(TODO:https://tracker.myorg.com/browse/PRJ-333; deadline01.01.25)Scenario:Yet another business feature@xfail(bug:https://tracker.myorg.com/browse/PRJ-555)
Scenario outline: Other business featureIf reason contains URL, soOverhavewill attachAllurelink to report:
fordisabled- it will beLinkType.LINK, forxfail-LinkType.ISSUE.Feature linksOverhavehas ability to set links to it’s own admin service inAlluretest-cases. Link will be set automatically when you generateAllurereport.
This function can be enabled via setup of environment variable`OVERHAVE_ADMIN_URL`:exportOVERHAVE_ADMIN_URL=https://overhave-admin.myorg.comAlso,Overhavehas ability to set links to feature file inGitrepository.
Link will be set automatically when you generateAllurereport. This function
can be enabled via setup of environment variable`OVERHAVE_GIT_PROJECT_URL`:exportOVERHAVE_GIT_PROJECT_URL=https://git.myorg.com/bdd-features-repoLanguageThe 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 aspytest-bddBDD keywords are configurable
withOverhaveextra models, for example RUS keywords are already defined
in framework and available for usage:fromoverhave.extraimportRUSSIAN_PREFIXESlanguage_settings=OverhaveLanguageSettings(step_prefixes=RUSSIAN_PREFIXES)Note: you could create your own prefix-value mapping for your language:fromoverhaveimportStepPrefixesModelGERMAN_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 integrationOverhavegives an ability to sent your new features or changes to
remote git repository, which is hosted byBitbucketorGitLab.
Integration with bitbucket is native, while integration with GitLab
usespython-gitlablibrary.You are able to set necessary settings for your project: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 buttonCreate pull requeston
test run result’s page. This button is available only forsuccesstest 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,Overhavehas specialTokenizerClientwith it’s ownTokenizerClientSettings- this simple client could take
the token from a remote custom GitLab tokenizer service.Git-to-DataBase synchronizationOverhavegives an ability to synchronize your currentgitrepository’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 ingitrepository, and now you want to deliver changes to remote database.
This not so easy matter could be solved withOverhavespecial
tooling:You are able to set necessary settings for your project:overhavesyncrun# only update existing featuresoverhavesyncrun--create-db-features# update + create new featuresoverhavesyncrun--pull-repository# pull git repo and run syncYou are able to test this tool withOverhavedemo 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.overhave-demosync-run# or with '--create-db-features'Overhavesupports 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.overhavesyncvalidate-featuresoverhavesyncvalidate-features--raise-if-nullable-idoverhavesyncvalidate-features--pull-repositoryAnd yes, your are able to try it with demo mode:overhave-demovalidate-featuresoverhavesyncvalidate-features-r# --raise-if-nullable-idCustom indexOverhavegives an ability to set custom index.html file for rendering. Path
to file could be set through environment as well as set with context:admin_settings=OverhaveAdminSettings(index_template_path="/path/to/index.html")Authorization strategyOverhaveprovides 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:auth_settings=OverhaveAuthorizationSettings(auth_strategy=AuthorizationStrategy.LDAP)ldap_manager_settings=OverhaveLdapManagerSettings(ldap_admin_group="admin")S3 cloudOverhaveimplements functionality fors3cloud 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:OVERHAVE_S3_ENABLED=trueOVERHAVE_S3_URL=https://s3.example.comOVERHAVE_S3_ACCESS_KEY=<MY_ACCESS_KEY>OVERHAVE_S3_SECRET_KEY=<MY_SECRET_KEY>Optionally, you could change default settings also:OVERHAVE_S3_VERIFY=falseOVERHAVE_S3_AUTOCREATE_BUCKETS=trueThe framework with enabled`OVERHAVE_S3_AUTOCREATE_BUCKETS`flag will create
application buckets in remote storage if buckets don’t exist.APIOverhavehas it’s own application programming interface, based onFastAPI.Overhaveopenapi.json throughSwaggerCurrent possibilities could be displayed through built-inSwagger- just run the API and openhttp://localhost:8000in your
browser.overhaveapi-p8000Interface has authorization throughoauth2scheme, so you should setup`OVERHAVE_API_AUTH_SECRET_KEY`for usage.Right now, API implements types of resources:feature_tagsget feature tag or get list of feature tags;featuresget features info by tag ID or tag value;test_usersget test user info, specification, put new specification or delete
test user;test_runsget test run info or create test run with given parameters;emulationsget emulation runs by test user id.ContributingContributions are very welcome.PreparationProject installation is very easy
and takes just few prepared commands (make pre-initworks only for Ubuntu;
so you can install same packages for your OS manually):makepre-initmakeinitPackages management is provided byPoetry.CheckTests can be run withTox.Docker-composeis used for other services
preparation and serving, such as database. Simple tests and linters execution:makeupmaketestmakelintPlease, seemakefile and discover useful shortcuts. You could run tests
in docker container also:maketest-dockerDocumentation buildProject documentation could be built viaSphinxand simplemakecommand:makebuild-docsBy default, the documentation will be built usinghtmlbuilder into_builddirectory.LicenseDistributed under the terms of theGNU GPLv2license.IssuesIf you encounter any problems, please report them here in sectionIssueswith a detailed description.