|
| 1 | +Metadata-Version: 2.1 |
| 2 | +Name: pytest-metadata |
| 3 | +Version: 3.1.1 |
| 4 | +Summary: pytest plugin for test session metadata |
| 5 | +Project-URL: Homepage, https://github.com/pytest-dev/pytest-metadata |
| 6 | +Project-URL: Tracker, https://github.com/pytest-dev/pytest-metadata/issues |
| 7 | +Project-URL: Source, https://github.com/pytest-dev/pytest-metadata |
| 8 | +Author-email: Dave Hunt <dhunt@mozilla.com>, Jim Brannlund <jimbrannlund@fastmail.com> |
| 9 | +License-Expression: MPL-2.0 |
| 10 | +License-File: AUTHORS |
| 11 | +License-File: LICENSE |
| 12 | +Keywords: metadata,pytest |
| 13 | +Classifier: Development Status :: 5 - Production/Stable |
| 14 | +Classifier: Framework :: Pytest |
| 15 | +Classifier: Intended Audience :: Developers |
| 16 | +Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0) |
| 17 | +Classifier: Natural Language :: English |
| 18 | +Classifier: Operating System :: MacOS :: MacOS X |
| 19 | +Classifier: Operating System :: Microsoft :: Windows |
| 20 | +Classifier: Operating System :: POSIX |
| 21 | +Classifier: Programming Language :: Python :: 3.8 |
| 22 | +Classifier: Programming Language :: Python :: 3.9 |
| 23 | +Classifier: Programming Language :: Python :: 3.10 |
| 24 | +Classifier: Programming Language :: Python :: 3.11 |
| 25 | +Classifier: Programming Language :: Python :: 3.12 |
| 26 | +Classifier: Programming Language :: Python :: Implementation :: CPython |
| 27 | +Classifier: Programming Language :: Python :: Implementation :: PyPy |
| 28 | +Classifier: Topic :: Software Development :: Quality Assurance |
| 29 | +Classifier: Topic :: Software Development :: Testing |
| 30 | +Classifier: Topic :: Utilities |
| 31 | +Requires-Python: >=3.8 |
| 32 | +Requires-Dist: pytest>=7.0.0 |
| 33 | +Provides-Extra: test |
| 34 | +Requires-Dist: black>=22.1.0; extra == 'test' |
| 35 | +Requires-Dist: flake8>=4.0.1; extra == 'test' |
| 36 | +Requires-Dist: pre-commit>=2.17.0; extra == 'test' |
| 37 | +Requires-Dist: tox>=3.24.5; extra == 'test' |
| 38 | +Description-Content-Type: text/x-rst |
| 39 | + |
| 40 | +pytest-metadata |
| 41 | +=============== |
| 42 | + |
| 43 | +pytest-metadata is a plugin for `pytest <http://pytest.org>`_ that provides |
| 44 | +access to test session metadata. |
| 45 | + |
| 46 | +.. image:: https://img.shields.io/badge/license-MPL%202.0-blue.svg |
| 47 | + :target: https://github.com/pytest-dev/pytest-metadata/blob/master/LICENSE |
| 48 | + :alt: License |
| 49 | +.. image:: https://img.shields.io/pypi/v/pytest-metadata.svg |
| 50 | + :target: https://pypi.python.org/pypi/pytest-metadata/ |
| 51 | + :alt: PyPI |
| 52 | +.. image:: https://img.shields.io/travis/pytest-dev/pytest-metadata.svg |
| 53 | + :target: https://travis-ci.org/pytest-dev/pytest-metadata/ |
| 54 | +.. image:: https://img.shields.io/badge/code%20style-black-000000.svg |
| 55 | + :target: https://github.com/ambv/black |
| 56 | + :alt: Travis |
| 57 | +.. image:: https://img.shields.io/github/issues-raw/pytest-dev/pytest-metadata.svg |
| 58 | + :target: https://github.com/pytest-dev/pytest-metadata/issues |
| 59 | + :alt: Issues |
| 60 | +.. image:: https://img.shields.io/requires/github/pytest-dev/pytest-metadata.svg |
| 61 | + :target: https://requires.io/github/pytest-dev/pytest-metadata/requirements/?branch=master |
| 62 | + :alt: Requirements |
| 63 | + |
| 64 | +Requirements |
| 65 | +------------ |
| 66 | + |
| 67 | +You will need the following in order to use pytest-metadata: |
| 68 | + |
| 69 | +- Python 3.8+ or PyPy3 |
| 70 | + |
| 71 | +Installation |
| 72 | +------------ |
| 73 | + |
| 74 | +To install pytest-metadata: |
| 75 | + |
| 76 | +.. code-block:: bash |
| 77 | + |
| 78 | + $ pip install pytest-metadata |
| 79 | + |
| 80 | +Contributing |
| 81 | +------------ |
| 82 | + |
| 83 | +We welcome contributions. |
| 84 | + |
| 85 | +To learn more, see `Development <https://github.com/pytest-dev/pytest-metadata/blob/master/development.rst>`_ |
| 86 | + |
| 87 | +Available metadata |
| 88 | +------------------ |
| 89 | + |
| 90 | +The following metadata is gathered by this plugin: |
| 91 | + |
| 92 | +======== =============== =================================== |
| 93 | +Key Description Example |
| 94 | +======== =============== =================================== |
| 95 | +Python Python version 3.6.4 |
| 96 | +Platform Platform Darwin-17.4.0-x86_64-i386-64bit |
| 97 | +Packages pytest packages {'py': '1.5.2', 'pytest': '3.4.1'} |
| 98 | +Plugins pytest plugins {'metadata': '1.6.0'} |
| 99 | +======== =============== =================================== |
| 100 | + |
| 101 | +Additional metadata |
| 102 | +------------------- |
| 103 | + |
| 104 | +You can provide your own metadata (key, value pair) by specifying ``--metadata`` on the commandline:: |
| 105 | + |
| 106 | + pytest --metadata foo bar |
| 107 | + |
| 108 | +Note: You can provide multiple sets of ``--metadata``:: |
| 109 | + |
| 110 | + pytest --metadata foo bar --metadata baz zoo |
| 111 | + |
| 112 | +There's also the possibility of passing in metadata as a JSON string:: |
| 113 | + |
| 114 | + pytest --metadata-from-json '{"cat_says": "bring the cat nip", "human_says": "yes kitty"}' |
| 115 | + |
| 116 | +Alternatively a JSON can be read from a given file:: |
| 117 | + |
| 118 | + pytest --metadata-from-json-file path/to/valid/file.json |
| 119 | + |
| 120 | +Continuous integration |
| 121 | +---------------------- |
| 122 | + |
| 123 | +When run in a continuous integration environment, additional metadata is added |
| 124 | +from environment variables. Below is a list of the supported continuous |
| 125 | +integration providers, along with links to the environment variables that are |
| 126 | +added to metadata if they're present. |
| 127 | + |
| 128 | +* `AppVeyor <https://www.appveyor.com/docs/environment-variables/>`_ |
| 129 | +* `Bitbucket <https://confluence.atlassian.com/bitbucket/environment-variables-794502608.html>`_ |
| 130 | +* `CircleCI <https://circleci.com/docs/1.0/environment-variables/>`_ |
| 131 | +* `GitLab CI <http://docs.gitlab.com/ce/ci/variables/README.html>`_ |
| 132 | +* `Jenkins <https://wiki.jenkins-ci.org/display/JENKINS/Building+a+software+project#Buildingasoftwareproject-JenkinsSetEnvironmentVariables>`_ |
| 133 | +* `TaskCluster <https://docs.taskcluster.net/reference/workers/docker-worker/environment>`_ |
| 134 | +* `Travis CI <https://docs.travis-ci.com/user/environment-variables/>`_ |
| 135 | + |
| 136 | +Note that if you're using `Tox <http://tox.readthedocs.io/>`_ to run your tests |
| 137 | +then you will need to `pass down any additional environment variables <http://tox.readthedocs.io/en/latest/example/basic.html#passing-down-environment-variables>`_ |
| 138 | +for these to be picked up. |
| 139 | + |
| 140 | +Viewing metadata |
| 141 | +---------------- |
| 142 | + |
| 143 | +If you pass ``--verbose`` on the command line when running your tests, then the |
| 144 | +metadata will be displayed in the terminal report header:: |
| 145 | + |
| 146 | + pytest --verbose |
| 147 | + ============================ test session starts ============================ |
| 148 | + platform darwin -- Python 3.6.4, pytest-3.4.1, py-1.5.2, pluggy-0.6.0 -- /usr/bin/python |
| 149 | + cachedir: .pytest_cache |
| 150 | + metadata: {'Python': '3.6.4', 'Platform': 'Darwin-17.4.0-x86_64-i386-64bit', 'Packages': {'pytest': '3.4.1', 'py': '1.5.2', 'pluggy': '0.6.0'}, 'Plugins': {'metadata': '1.6.0'}} |
| 151 | + plugins: metadata-1.6.0 |
| 152 | + |
| 153 | +Including metadata in Junit XML |
| 154 | +------------------------------- |
| 155 | + |
| 156 | +Pytest-metadata provides the session scoped fixture :code:`include_metadata_in_junit_xml` that you may use to include any metadata in Junit XML as ``property`` tags. |
| 157 | +For example the following test module |
| 158 | + |
| 159 | +.. code-block:: python |
| 160 | + |
| 161 | + import pytest |
| 162 | + |
| 163 | + pytestmark = pytest.mark.usefixtures('include_metadata_in_junit_xml') |
| 164 | + |
| 165 | + def test(): |
| 166 | + pass |
| 167 | + |
| 168 | +when called with |
| 169 | + |
| 170 | +.. code-block:: bash |
| 171 | + |
| 172 | + pytest --metadata Daffy Duck --junit-xml=results.xml |
| 173 | + |
| 174 | +would produce the following XML |
| 175 | + |
| 176 | +.. code-block:: xml |
| 177 | + |
| 178 | + <?xml version="1.0" encoding="utf-8"?> |
| 179 | + <testsuites> |
| 180 | + <testsuite name="pytest" errors="0" failures="0" skipped="0" tests="1" time="0.009" timestamp="2020-11-27T06:38:44.407674" hostname="sam"> |
| 181 | + <properties> |
| 182 | + <property name="Daffy" value="Duck"/> |
| 183 | + ... |
| 184 | + |
| 185 | +Accessing metadata |
| 186 | +------------------ |
| 187 | + |
| 188 | +To add/modify/delete metadata at the end of metadata collection, you can use the ``pytest_metadata`` hook: |
| 189 | + |
| 190 | +.. code-block:: python |
| 191 | + |
| 192 | + import pytest |
| 193 | + @pytest.hookimpl(optionalhook=True) |
| 194 | + def pytest_metadata(metadata): |
| 195 | + metadata.pop("password", None) |
| 196 | + |
| 197 | +To access the metadata from a test or fixture, you can use the ``metadata`` |
| 198 | +fixture: |
| 199 | + |
| 200 | +.. code-block:: python |
| 201 | + |
| 202 | + def test_metadata(metadata): |
| 203 | + assert 'metadata' in metadata['Plugins'] |
| 204 | + |
| 205 | +To access the metadata from a plugin, you can use the ``stash`` attribute of |
| 206 | +the ``config`` object. This can be used to read/add/modify the metadata: |
| 207 | + |
| 208 | +.. code-block:: python |
| 209 | + |
| 210 | + def pytest_configure(config): |
| 211 | + metadata = config.pluginmanager.getplugin("metadata") |
| 212 | + if metadata: |
| 213 | + from pytest_metadata.plugin import metadata_key |
| 214 | + config.stash[metadata_key]['foo'] = 'bar' |
| 215 | + |
| 216 | +Plugin integrations |
| 217 | +------------------- |
| 218 | + |
| 219 | +Here's a handy list of plugins that either read or contribute to the metadata: |
| 220 | + |
| 221 | +* `pytest-base-url <https://pypi.python.org/pypi/pytest-base-url/>`_ - Adds the |
| 222 | + base URL to the metadata. |
| 223 | +* `pytest-html <https://pypi.python.org/pypi/pytest-html/>`_ - Displays the |
| 224 | + metadata at the start of each report. |
| 225 | +* `pytest-reporter-html1 <https://pypi.org/project/pytest-reporter-html1/>`_ - |
| 226 | + Presents metadata as part of the report. |
| 227 | +* `pytest-selenium <https://pypi.python.org/pypi/pytest-selenium/>`_ - Adds the |
| 228 | + driver, capabilities, and remote server to the metadata. |
| 229 | + |
| 230 | +Resources |
| 231 | +--------- |
| 232 | + |
| 233 | +- `Release Notes <http://github.com/davehunt/pytest-metadata/blob/master/CHANGES.rst>`_ |
| 234 | +- `Issue Tracker <http://github.com/davehunt/pytest-metadata/issues>`_ |
| 235 | +- `Code <http://github.com/davehunt/pytest-metadata/>`_ |
0 commit comments