# Marking test functions with attributes

By using the `pytest.mark` helper you can easily set metadata on your test functions. There are some builtin markers, for example:

- skipif - skip a test function if a certain condition is met
- xfail - produce an “expected failure” outcome if a certain condition is met
- parametrize to perform multiple calls to the same test function.

It’s easy to create custom markers or to apply markers to whole test classes or modules. See Working with custom markers for examples which also serve as documentation.

Note

Marks can only be applied to tests, having no effect on fixtures.

## API reference for mark related objects

class `MarkGenerator`

  Factory for `MarkDecorator` objects - exposed as a `pytest.mark` singleton instance. Example:

      import py
      @pytest.mark.slowtest
      def test_function():
         pass

  will set a ‘slowtest’ `MarkInfo` object on the `test_function` object.

class `MarkDecorator`(name, args=None, kwargs=None)

  A decorator for test functions and test classes. When applied it will create `MarkInfo` objects which may be retrieved by hooks as item keywords. MarkDecorator instances are often created like this:

      mark1 = pytest.mark.NAME              # simple MarkDecorator
      mark2 = pytest.mark.NAME(name1=value) # parametrized MarkDecorator

  and can then be applied as decorators to test functions:

      @mark2
      def test_function():
          pass

  When a MarkDecorator instance is called it does the following:
    1. If called with a single class as its only positional argument and no additional keyword arguments, it attaches itself to the class so it gets applied automatically to all test cases found in that class.
    2. If called with a single function as its only positional argument and no additional keyword arguments, it attaches a MarkInfo object to the function, containing all the arguments already stored internally in the MarkDecorator.
    3. When called in any other case, it performs a ‘fake construction’ call, i.e. it returns a new MarkDecorator instance with the original MarkDecorator’s content updated with the arguments passed to this call.

  Note: The rules above prevent MarkDecorator objects from storing only a single function or class reference as their positional argument with no additional keyword or positional arguments.

class `MarkInfo`(name, args, kwargs)

  Marking object created by `MarkDecorator` instances.

  `name` = None

    name of attribute

  `args` = None

    positional argument list, empty if none specified

  `kwargs` = None

    keyword argument dictionary, empty if nothing specified

  `add`(args, kwargs)

    add a MarkInfo with the given args and kwargs.