<commit_before>
.. _`mark examples`:

Working with custom markers
=================================================

Here are some example using the :ref:`mark` mechanism.

Marking test functions and selecting them for a run
----------------------------------------------------

You can "mark" a test function with custom metadata like this::

    # content of test_server.py

    import pytest
    @pytest.mark.webtest
    def test_send_http():
        pass # perform some webtest test for your app
    def test_something_quick():
        pass
    def test_another():
        pass
    class TestClass:
        def test_method(self):
            pass

.. versionadded:: 2.2

You can then restrict a test run to only run tests marked with ``webtest``::

    $ py.test -v -m webtest
    =========================== test session starts ============================
    platform linux -- Python 3.4.0 -- py-1.4.26 -- pytest-2.7.0 -- /home/hpk/p/pytest/.tox/regen/bin/python3.4
    rootdir: /tmp/doc-exec-167, inifile: 
    collecting ... collected 4 items
    
    test_server.py::test_send_http PASSED
    
    =================== 3 tests deselected by "-m 'webtest'" ===================
    ================== 1 passed, 3 deselected in 0.01 seconds ==================

Or the inverse, running all tests except the webtest ones::

    $ py.test -v -m "not webtest"
    =========================== test session starts ============================
    platform linux -- Python 3.4.0 -- py-1.4.26 -- pytest-2.7.0 -- /home/hpk/p/pytest/.tox/regen/bin/python3.4
    rootdir: /tmp/doc-exec-167, inifile: 
    collecting ... collected 4 items
    
    test_server.py::test_something_quick PASSED
    test_server.py::test_another PASSED
    test_server.py::TestClass::test_method PASSED
    
    ================= 1 tests deselected by "-m 'not webtest'" =================
    ================== 3 passed, 1 deselected in 0.01 seconds ==================

Selecing tests based on their node ID
-------------------------------------

You can provide one or more :ref:`node IDs <node-id>` as positional
arguments to select only specified tests. This makes it easy to select
tests based on their module, class, method, or function name::

    $ py.test -v test_server.py::TestClass::test_method
    =========================== test session starts ============================
    platform linux -- Python 3.4.0 -- py-1.4.26 -- pytest-2.7.0 -- /home/hpk/p/pytest/.tox/regen/bin/python3.4
    rootdir: /tmp/doc-exec-167, inifile: 
    collecting ... collected 5 items
    
    test_server.py::TestClass::test_method PASSED
    
    ========================= 1 passed in 0.01 seconds =========================

You can also select on the class::

    $ py.test -v test_server.py::TestClass
    =========================== test session starts ============================
    platform linux -- Python 3.4.0 -- py-1.4.26 -- pytest-2.7.0 -- /home/hpk/p/pytest/.tox/regen/bin/python3.4
    rootdir: /tmp/doc-exec-167, inifile: <commit_msg>Doc typo<commit_after>
.. _`mark examples`:

Working with custom markers
=================================================

Here are some example using the :ref:`mark` mechanism.

Marking test functions and selecting them for a run
----------------------------------------------------

You can "mark" a test function with custom metadata like this::

    # content of test_server.py

    import pytest
    @pytest.mark.webtest
    def test_send_http():
        pass # perform some webtest test for your app
    def test_something_quick():
        pass
    def test_another():
        pass
    class TestClass:
        def test_method(self):
            pass

.. versionadded:: 2.2

You can then restrict a test run to only run tests marked with ``webtest``::

    $ py.test -v -m webtest
    =========================== test session starts ============================
    platform linux -- Python 3.4.0 -- py-1.4.26 -- pytest-2.7.0 -- /home/hpk/p/pytest/.tox/regen/bin/python3.4
    rootdir: /tmp/doc-exec-167, inifile: 
    collecting ... collected 4 items
    
    test_server.py::test_send_http PASSED
    
    =================== 3 tests deselected by "-m 'webtest'" ===================
    ================== 1 passed, 3 deselected in 0.01 seconds ==================

Or the inverse, running all tests except the webtest ones::

    $ py.test -v -m "not webtest"
    =========================== test session starts ============================
    platform linux -- Python 3.4.0 -- py-1.4.26 -- pytest-2.7.0 -- /home/hpk/p/pytest/.tox/regen/bin/python3.4
    rootdir: /tmp/doc-exec-167, inifile: 
    collecting ... collected 4 items
    
    test_server.py::test_something_quick PASSED
    test_server.py::test_another PASSED
    test_server.py::TestClass::test_method PASSED
    
    ================= 1 tests deselected by "-m 'not webtest'" =================
    ================== 3 passed, 1 deselected in 0.01 seconds ==================

Selecting tests based on their node ID
--------------------------------------

You can provide one or more :ref:`node IDs <node-id>` as positional
arguments to select only specified tests. This makes it easy to select
tests based on their module, class, method, or function name::

    $ py.test -v test_server.py::TestClass::test_method
    =========================== test session starts ============================
    platform linux -- Python 3.4.0 -- py-1.4.26 -- pytest-2.7.0 -- /home/hpk/p/pytest/.tox/regen/bin/python3.4
    rootdir: /tmp/doc-exec-167, inifile: 
    collecting ... collected 5 items
    
    test_server.py::TestClass::test_method PASSED
    
    ========================= 1 passed in 0.01 seconds =========================

You can also select on the class::

    $ py.test -v test_server.py::TestClass
    =========================== test session starts ============================
    platform linux -- Python 3.4.0 -- py-1.4.26 -- pytest-2.7.0 -- /home/hpk/p/pytest/.tox/regen/bin/python3.4
    rootdir: /tmp/doc-exec-167, inifile: 
{'fraction_non_alphanumeric': 0.27076770021555296, 'fraction_numerical': 0.026861217045266124, 'mean_word_length': 2.8008821676118463, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6581718', 'n_tokens_mistral': 1861, 'n_tokens_neox': 1700, 'n_words': 513}