From ce3df3904fa9126aac1ada7295790ef04a3a9ae3 Mon Sep 17 00:00:00 2001 From: fundakol <22340156+fundakol@users.noreply.github.com> Date: Fri, 10 Dec 2021 21:58:46 +0100 Subject: [PATCH] Improve long description in PyPi --- README.md | 125 ------------------------------------- README.rst | 179 +++++++++++++++++++++++++++++++++++++++++++++++++++++ setup.cfg | 4 +- 3 files changed, 181 insertions(+), 127 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/README.md b/README.md deleted file mode 100644 index 26c930e..0000000 --- a/README.md +++ /dev/null @@ -1,125 +0,0 @@ -# pytest-jira-xray - -[![PyPi](https://img.shields.io/pypi/v/pytest-jira-xray.png)](https://pypi.python.org/pypi/pytest-jira-xray) -[![Build Status](https://travis-ci.com/fundakol/pytest-jira-xray.svg?branch=master)](https://travis-ci.com/github/fundakol/pytest-jira-xray) -[![codecov](https://codecov.io/gh/fundakol/pytest-jira-xray/branch/master/graph/badge.svg)](https://codecov.io/gh/fundakol/pytest-jira-xray) - -pytest-jira-xray is a plugin for pytest that uploads test results to JIRA XRAY. - -### Installation - -```commandline -pip install pytest-jira-xray -``` - -or - -```commandline -python setup.py install -``` - -### Usage - -Mark a test with JIRA XRAY test ID - -```python -# -- FILE: test_example.py -import pytest - -@pytest.mark.xray('JIRA-1') -def test_one(): - assert True -``` - -### Jira Xray configuration can be provided via Environment Variables: - -* Jira base URL: -```commandline -$ export XRAY_API_BASE_URL= -``` -- Basic authentication: -```commandline -$ export XRAY_API_USER= -$ export XRAY_API_PASSWORD= -``` - -- SSL Client Certificate - -To disable SSL certificate verification, at the client side (no case-sensitive), default is True: -```commandline -$ export XRAY_API_VERIFY_SSL=False -``` - -Or you can provide path to certificate file -```commandline -$ export XRAY_API_VERIFY_SSL= -``` - -* Cloud authentication: -```commandline -$ export XRAY_CLIENT_ID= -$ export XRAY_CLIENT_SECRET= -``` - -* Test Execution parameters: -```commandline -$ export XRAY_EXECUTION_TEST_ENVIRONMENTS="Env1 Env2 Env3" -$ export XRAY_EXECUTION_FIX_VERSION="1.0" -$ export XRAY_EXECUTION_REVISION=`git rev-parse HEAD` - -$ export XRAY_EXECUTION_SUMMARY="Smoke tests" # New execution only -$ export XRAY_EXECUTION_DESC="This is an automated test execution of the smoke tests" # New execution only -``` - -### Upload results - -* Upload results to new test execution: -```commandline -$ pytest --jira-xray -``` - -* Upload results to existing test execution: -```commandline -$ pytest --jira-xray --execution TestExecutionId -``` - -* Upload results to existing test plan (new test execution will be created): -```commandline -$ pytest --jira-xray --testplan TestPlanId -``` - -* Use with Jira cloud: -```commandline -$ pytest --jira-xray --cloud -``` - -* Store results in a file instead of exporting directly to a XRAY server -```commandline -$ pytest --jira-xray --xraypath=xray.json -``` - -### IntelliJ integration - -When you want to synchronize your test results via. Pytest integration in IntelliJ, you need to configure the following: - -1. Use the *pytest* test configuration template and add `--jira-xray -o log_cli=true` to *Additional Arguments* \ - ![](doc/intellij-pytest-template.png) -2. Disable `--no-summary` in *Settings*\ - ![](doc/intellij-pytest-advanced-settings.png) - -### Troubleshooting - -This section holds information about common issues. - -#### `The Test XXX is in a non-executable status` - * Problem: The test is not executable by the user. - * Solution: Make sure, that your test is not deactivated, approved and ready to use in Jira. - -#### `Error message from server: fixVersions: fixVersions` - * Problem: The version is malformed or doesn't exist. - * Solution: Make sure the version exists and the name matches the existing version and that only one version is used. - - -## References - -- XRay import execution endpoint: https://docs.getxray.app/display/XRAY/Import+Execution+Results diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..a63890b --- /dev/null +++ b/README.rst @@ -0,0 +1,179 @@ +================ +pytest-jira-xray +================ + +.. image:: https://img.shields.io/pypi/v/pytest-jira-xray.png + :target: https://pypi.python.org/pypi/pytest-jira-xray + :alt: PyPi +.. image:: https://travis-ci.com/fundakol/pytest-jira-xray.svg?branch=master + :target: https://travis-ci.com/github/fundakol/pytest-jira-xray + :alt: Build status +.. image:: https://codecov.io/gh/fundakol/pytest-jira-xray/branch/master/graph/badge.svg + :target: https://codecov.io/gh/fundakol/pytest-jira-xray + :alt: Code coverage + + +pytest-jira-xray is a plugin for pytest that uploads test results to JIRA XRAY. + + +Installation +------------ + +.. code-block:: + + pip install pytest-jira-xray + +or + +.. code-block:: + + python setup.py install + + +Usage +----- + +Mark a test with JIRA XRAY test ID + +.. code-block:: python + + # -- FILE: test_example.py + import pytest + + @pytest.mark.xray('JIRA-1') + def test_one(): + assert True + + +Jira Xray configuration can be provided via Environment Variables: +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +* Jira base URL: + +.. code-block:: bash + + $ export XRAY_API_BASE_URL= + + +- Basic authentication: + +.. code-block:: bash + + $ export XRAY_API_USER= + $ export XRAY_API_PASSWORD= + + +- SSL Client Certificate + +To disable SSL certificate verification, at the client side (no case-sensitive), default is True: + +.. code-block:: bash + + $ export XRAY_API_VERIFY_SSL=False + + +Or you can provide path to certificate file + +.. code-block:: bash + + $ export XRAY_API_VERIFY_SSL= + + +* Cloud authentication: + +.. code-block:: bash + + $ export XRAY_CLIENT_ID= + $ export XRAY_CLIENT_SECRET= + + +* Test Execution parameters: + +.. code-block:: bash + + $ export XRAY_EXECUTION_TEST_ENVIRONMENTS="Env1 Env2 Env3" + $ export XRAY_EXECUTION_FIX_VERSION="1.0" + $ export XRAY_EXECUTION_REVISION=`git rev-parse HEAD` + + $ export XRAY_EXECUTION_SUMMARY="Smoke tests" # New execution only + $ export XRAY_EXECUTION_DESC="This is an automated test execution of the smoke tests" # New execution only + + +Upload results +++++++++++++++ + +* Upload results to new test execution: + +.. code-block:: bash + + $ pytest --jira-xray + + +* Upload results to existing test execution: + +.. code-block:: bash + + $ pytest --jira-xray --execution TestExecutionId + + +* Upload results to existing test plan (new test execution will be created): + +.. code-block:: bash + + $ pytest --jira-xray --testplan TestPlanId + + +* Use with Jira cloud: + +.. code-block:: bash + + $ pytest --jira-xray --cloud + + +* Store results in a file instead of exporting directly to a XRAY server + +.. code-block:: bash + + $ pytest --jira-xray --xraypath=xray.json + + +IntelliJ integration +++++++++++++++++++++ + +When you want to synchronize your test results via. Pytest integration in IntelliJ, you need to configure the following: + +1. Use the *pytest* test configuration template and add `--jira-xray -o log_cli=true` to *Additional Arguments* + +.. image:: https://user-images.githubusercontent.com/22340156/145638520-c6bf56d2-089e-430c-94ae-ac8122a3adea.png + :target: https://user-images.githubusercontent.com/22340156/145638520-c6bf56d2-089e-430c-94ae-ac8122a3adea.png + +2. Disable `--no-summary` in *Settings* + +.. image:: https://user-images.githubusercontent.com/22340156/145638538-71590ec8-86c6-4b93-9a99-460b4e38e153.png + :target: https://user-images.githubusercontent.com/22340156/145638538-71590ec8-86c6-4b93-9a99-460b4e38e153.png + + +Troubleshooting ++++++++++++++++ + +This section holds information about common issues. + +`The Test XXX is in a non-executable status` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Problem: The test is not executable by the user. + +* Solution: Make sure, that your test is not deactivated, approved and ready to use in Jira. + +`Error message from server: fixVersions: fixVersions` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Problem: The version is malformed or doesn't exist. + +* Solution: Make sure the version exists and the name matches the existing version and that only one version is used. + + +References +---------- + +- XRay import execution endpoint: ``_ diff --git a/setup.cfg b/setup.cfg index cdb72f4..5245048 100644 --- a/setup.cfg +++ b/setup.cfg @@ -4,8 +4,7 @@ url = https://github.com/fundakol/pytest-jira-xray author = Lukasz Fundakowski author_email = fundakol@yahoo.com description = pytest plugin to integrate tests with JIRA XRAY -long_description = file: README.md -long_description_content_type = text/markdown +long_description = file: README.rst python_requires = >=3.6 keywords = pytest,JIRA,XRAY classifiers = @@ -17,6 +16,7 @@ classifiers = Programming Language :: Python :: 3.9 License :: OSI Approved :: Apache Software License Operating System :: OS Independent + Framework :: Pytest [options] packages = find: