From 04fa42168f87147738cc1a0be314baaf789779d5 Mon Sep 17 00:00:00 2001 From: Maxim <17935127+delatrie@users.noreply.github.com> Date: Mon, 11 Mar 2024 22:48:02 +0700 Subject: [PATCH] Fix project's metadata. Add common READMEs (#799) --- allure-behave/setup.py | 2 +- allure-nose2/setup.py | 2 +- allure-pytest-bdd/setup.py | 2 +- allure-pytest/setup.py | 2 +- allure-python-commons-test/README.md | 62 +++++++++++++++ allure-python-commons-test/setup.py | 37 ++++++++- allure-python-commons/README.md | 112 +++++++++++++++++++++++++++ allure-python-commons/setup.py | 14 +++- 8 files changed, 224 insertions(+), 9 deletions(-) create mode 100644 allure-python-commons-test/README.md create mode 100644 allure-python-commons/README.md diff --git a/allure-behave/setup.py b/allure-behave/setup.py index 7376de66..62cb593e 100644 --- a/allure-behave/setup.py +++ b/allure-behave/setup.py @@ -51,7 +51,7 @@ def main(): "Documentation": "https://allurereport.org/docs/behave/", "Source": "https://github.com/allure-framework/allure-python", }, - author="QAMetaSoftware, Stanislav Seliverstov", + author="Qameta Software Inc., Stanislav Seliverstov", author_email="sseliverstov@qameta.io", license="Apache-2.0", classifiers=classifiers, diff --git a/allure-nose2/setup.py b/allure-nose2/setup.py index 8523d912..2c64e8ff 100644 --- a/allure-nose2/setup.py +++ b/allure-nose2/setup.py @@ -49,7 +49,7 @@ def main(): project_urls={ "Source": "https://github.com/allure-framework/allure-python", }, - author="QAMetaSoftware, Stanislav Seliverstov", + author="Qameta Software Inc., Stanislav Seliverstov", author_email="sseliverstov@qameta.io", license="Apache-2.0", classifiers=classifiers, diff --git a/allure-pytest-bdd/setup.py b/allure-pytest-bdd/setup.py index e092374b..5f8cf7af 100644 --- a/allure-pytest-bdd/setup.py +++ b/allure-pytest-bdd/setup.py @@ -51,7 +51,7 @@ def main(): project_urls={ "Source": "https://github.com/allure-framework/allure-python", }, - author="QAMetaSoftware, Stanislav Seliverstov", + author="Qameta Software Inc., Stanislav Seliverstov", author_email="sseliverstov@qameta.io", license="Apache-2.0", classifiers=classifiers, diff --git a/allure-pytest/setup.py b/allure-pytest/setup.py index 1a8494c1..f88df22b 100644 --- a/allure-pytest/setup.py +++ b/allure-pytest/setup.py @@ -64,7 +64,7 @@ def main(): "Documentation": "https://allurereport.org/docs/pytest/", "Source": "https://github.com/allure-framework/allure-python", }, - author="QAMetaSoftware, Stanislav Seliverstov", + author="Qameta Software Inc., Stanislav Seliverstov", author_email="sseliverstov@qameta.io", license="Apache-2.0", classifiers=classifiers, diff --git a/allure-python-commons-test/README.md b/allure-python-commons-test/README.md new file mode 100644 index 00000000..c0e68c3f --- /dev/null +++ b/allure-python-commons-test/README.md @@ -0,0 +1,62 @@ +## Allure Python Testing Utilities + +[![Release Status](https://img.shields.io/pypi/v/allure-python-commons-test)](https://pypi.python.org/pypi/allure-python-commons-test) +[![Downloads](https://img.shields.io/pypi/dm/allure-python-commons-test)](https://pypi.python.org/pypi/allure-python-commons-test) + +> The package contains pyhamcrest matchers to assert the Allure results. They +> come in handy when you need to test an Allure adapter. + +[Allure Report logo](https://allurereport.org "Allure Report") + +- Learn more about Allure Report at [https://allurereport.org](https://allurereport.org) +- 📚 [Documentation](https://allurereport.org/docs/) – discover official documentation for Allure Report +- ❓ [Questions and Support](https://github.com/orgs/allure-framework/discussions/categories/questions-support) – get help from the team and community +- 📢 [Official announcements](https://github.com/orgs/allure-framework/discussions/categories/announcements) – stay updated with our latest news and updates +- 💬 [General Discussion](https://github.com/orgs/allure-framework/discussions/categories/general-discussion) – engage in casual conversations, share insights and ideas with the community +- 🖥️ [Live Demo](https://demo.allurereport.org/) — explore a live example of Allure Report in action + +--- + +## The matchers library + +Here is the list of available matchers. Refer to [https://github.com/allure-framework/allure-python/tree/master/tests](https://github.com/allure-framework/allure-python/tree/master/tests) for usage examples. + +|Module|Matcher|Check| +|------|-------|-----| +|container|`has_container`|The report contains a container that matches all the provided matchers.| +|container|`has_same_container`|The report contains a container that has all the specified tests as its children| +|container|`has_before`|The container has a before fixture with the specified name that matches all the provided matchers| +|container|`has_after`|The container has an after fixture with the specified name that matches all the provided matchers| +|content|`csv_equivalent`|The string (typically, an attachment's content) contains a CSV document that is equvalent to the provided one| +|label|`has_label`|The test contains a label with the specified name and (optionaly) the value| +|label|`has_severity`|The test has the specified severity label| +|label|`has_epic`|The test has the specified epic label| +|label|`has_feature`|The test has the specified feature label| +|label|`has_story`|The test has the specified story label| +|label|`has_tag`|The test has the specified tag label| +|label|`has_package`|The test has the specified package label| +|label|`has_suite`|The test has the specified suite label| +|label|`has_parent_suite`|The test has the specified parentSuite label| +|label|`has_sub_suite`|The test has the specified subSuite label| +|report|`has_test_case`|The report contains a test whose fullName ends, or name starts with the specified name. Additionally, the test must match all the provided matchers| +|report|`has_only_testcases`|Each test of the report matches at least one of the provided matchers| +|report|`has_only_n_test_cases`|Same as `has_test_case` but also checks if the number of matched tests is equal to the expected one| +|result|`has_title`|The test has an expected name| +|result|`has_description`|The test has a description that matches all the provided matchers| +|result|`has_description_html`|The test has a descriptionHtml that matches all the provided matchers| +|result|`has_step`|The test or step has a step with the specified name that matches all the provided matchers| +|result|`has_parameter`|The test or step has a parameter with the specified name whose value matches the provided matchers| +|result|`doesnt_have_parameter`|The test or step doesn't have a parameter with the specified name| +|result|`has_link`|The test has a link with the expected url, type (if provided) and name (if provided)| +|result|`has_issue_link`|The test has an issue link with the expected url and name (if provided)| +|result|`has_test_case_link`|The test has an issue link with the expected url and name (if provided)| +|result|`has_attachment`|The test or step has an attachment with the expected name and type.| +|result|`has_attachment_with_content`|The test or step has an attachment with the expected name and type. In addition, the content must match the provided matcher.| +|result|`with_id`|The test or container has the expected uuid| +|result|`with_status`|The test or step has the expected status| +|result|`has_status_details`|The status details of the test or step matches all the provided matchers| +|result|`with_message_contains`|The status details' message contains the provided text| +|result|`with_trace_contains`|The status details' trace contains the provided text| +|result|`with_excluded`|The parameter is excluded from the historyId calculation| +|result|`with_mode`|The parameter has the specified mode| +|result|`has_history_id`|The test has historyId| diff --git a/allure-python-commons-test/setup.py b/allure-python-commons-test/setup.py index 7650824c..1f8d1aa1 100644 --- a/allure-python-commons-test/setup.py +++ b/allure-python-commons-test/setup.py @@ -1,22 +1,53 @@ +import os from setuptools import setup PACKAGE = "allure-python-commons-test" +classifiers = [ + 'Development Status :: 5 - Production/Stable', + 'Intended Audience :: Developers', + 'License :: OSI Approved :: Apache Software License', + 'Topic :: Software Development :: Quality Assurance', + 'Topic :: Software Development :: Testing', + 'Programming Language :: Python :: 3', + 'Programming Language :: Python :: 3 :: Only', + 'Programming Language :: Python :: 3.7', + 'Programming Language :: Python :: 3.8', + 'Programming Language :: Python :: 3.9', + 'Programming Language :: Python :: 3.10', + 'Programming Language :: Python :: 3.11', + 'Programming Language :: Python :: 3.12', +] + install_requires = [ "pyhamcrest>=1.9.0" ] +def get_readme(fname): + return open(os.path.join(os.path.dirname(__file__), fname)).read() + + def main(): setup( name=PACKAGE, use_scm_version={"root": "..", "relative_to": __file__}, setup_requires=['setuptools_scm'], - description="Common module for self-testing allure integrations with python-based frameworks", - url="https://github.com/allure-framework/allure-python", - author="QAMetaSoftware, Stanislav Seliverstov", + description=( + "A collection of PyHamcrest matchers to test Allure adapters for " + "Python test frameworks" + ), + url="https://allurereport.org/", + project_urls={ + "Source": "https://github.com/allure-framework/allure-python", + }, + author="Qameta Software Inc., Stanislav Seliverstov", author_email="sseliverstov@qameta.io", license="Apache-2.0", + classifiers=classifiers, + keywords="allure reporting testing matchers", + long_description=get_readme("README.md"), + long_description_content_type="text/markdown", packages=["allure_commons_test"], package_dir={"allure_commons_test": "src"}, install_requires=install_requires diff --git a/allure-python-commons/README.md b/allure-python-commons/README.md new file mode 100644 index 00000000..bde7b47d --- /dev/null +++ b/allure-python-commons/README.md @@ -0,0 +1,112 @@ +## Allure Common API + +[![Release Status](https://img.shields.io/pypi/v/allure-python-commons)](https://pypi.python.org/pypi/allure-python-commons) +[![Downloads](https://img.shields.io/pypi/dm/allure-python-commons)](https://pypi.python.org/pypi/allure-python-commons) + +> The package contains classes and functions for users of Allure Report. It can +> be used to enhance reports using an existing Allure adapter or to create new +> adapters. + +[Allure Report logo](https://allurereport.org "Allure Report") + +- Learn more about Allure Report at [https://allurereport.org](https://allurereport.org) +- 📚 [Documentation](https://allurereport.org/docs/) – discover official documentation for Allure Report +- ❓ [Questions and Support](https://github.com/orgs/allure-framework/discussions/categories/questions-support) – get help from the team and community +- 📢 [Official announcements](https://github.com/orgs/allure-framework/discussions/categories/announcements) – stay updated with our latest news and updates +- 💬 [General Discussion](https://github.com/orgs/allure-framework/discussions/categories/general-discussion) – engage in casual conversations, share insights and ideas with the community +- 🖥️ [Live Demo](https://demo.allurereport.org/) — explore a live example of Allure Report in action + +--- + +## User's API + +Install an adapter that suits your test framework. You can then add more +information to the report by using functions from the `allure` module. + +### Decorators API + +Use these functions as decorators of your own functions, e.g.: + +```python +import allure + +@allure.title("My test") +def test_fn(): + pass +``` + +The full list of decorators: + + - `allure.title` + - `allure.description` + - `allure.description_html` + - `allure.label` + - `allure.severity` + - `allure.epic` + - `allure.feature` + - `allure.story` + - `allure.suite` + - `allure.parent_suite` + - `allure.sub_suite` + - `allure.tag` + - `allure.id` + - `allure.manual` + - `allure.link` + - `allure.issue` + - `allure.testcase` + - `allure.step` + +Refer to the adapter's documentation for the information about what decorators +are supported and what functions they can be applied to. + +### Runtime API + +Most of the functions of Runtime API can be accessed via `allure.dynamic.*`. +Call them at runtime from your code. + +The full list includes: + + - `allure.dynamic.title` + - `allure.dynamic.description` + - `allure.dynamic.description_html` + - `allure.dynamic.label` + - `allure.dynamic.severity` + - `allure.dynamic.epic` + - `allure.dynamic.feature` + - `allure.dynamic.story` + - `allure.dynamic.suite` + - `allure.dynamic.parent_suite` + - `allure.dynamic.sub_suite` + - `allure.dynamic.tag` + - `allure.dynamic.id` + - `allure.dynamic.manual` + - `allure.dynamic.link` + - `allure.dynamic.issue` + - `allure.dynamic.testcase` + - `allure.dynamic.parameter` + - `allure.attach` + - `allure.attach.file` + - `allure.step` + +Refer to the adapter's documentation for the information about what functions +are supported and where you can use them. + +## Adapter API + +You may use `allure-pytest-commons` to build your own Allure adapter. The key +elements of the corresponding API are: + + - `allure_python_commons.model2`: the object model of Allure Report. + - `allure_python_commons.logger`: classes that are used to emit Allure Report objects (tests, containers, attachments): + - `AllureFileLogger`: emits to the file system. + - `AllureMemoryLogger`: collects the objects in memory. Useful for + testing. + - `allure_python_commons.lifecycle.AllureLifecycle`: an implementation of + Allure lifecycle that doesn't isolate the state between threads. + - `allure_python_commons.reporter.AllureReporter`: an implementation of + Allure lifecycle that supports some multithreaded scenarios. + +A new version of the API is likely to be released in the future as we need +a decent support for multithreaded and async-based concurrency (see +[here](https://github.com/allure-framework/allure-python/issues/697) and +[here](https://github.com/allure-framework/allure-python/issues/720)). diff --git a/allure-python-commons/setup.py b/allure-python-commons/setup.py index fa9335a3..91a1e1f0 100644 --- a/allure-python-commons/setup.py +++ b/allure-python-commons/setup.py @@ -1,3 +1,4 @@ +import os from setuptools import setup PACKAGE = "allure-python-commons" @@ -24,21 +25,30 @@ ] +def get_readme(fname): + return open(os.path.join(os.path.dirname(__file__), fname)).read() + + def main(): setup( name=PACKAGE, use_scm_version={"root": "..", "relative_to": __file__}, setup_requires=['setuptools_scm'], - description="Common module for integrate allure with python-based frameworks", + description=( + "Contains the API for end users as well as helper functions and " + "classes to build Allure adapters for Python test frameworks", + ), url="https://allurereport.org/", project_urls={ "Source": "https://github.com/allure-framework/allure-python", }, - author="QAMetaSoftware, Stanislav Seliverstov", + author="Qameta Software Inc., Stanislav Seliverstov", author_email="sseliverstov@qameta.io", license="Apache-2.0", classifiers=classifiers, keywords="allure reporting report-engine", + long_description=get_readme("README.md"), + long_description_content_type="text/markdown", packages=["allure_commons"], package_dir={"allure_commons": 'src'}, install_requires=install_requires,