Getting Started
===================================

.. _`easy_install`:

**Compatibility**: Python 2.4-3.2, Jython, PyPy on Unix/Posix and Windows

Installation
----------------------------------------

Installation options::

    easy_install -U pytest  # or
    pip install -U pytest

To check your installation has installed the correct version::

    $ py.test --version

If you get an error, checkout :ref:`installation issues`.


Writing a simple test function with an assertion
----------------------------------------------------------

Let's create a small file with a test function testing a function
computes a certain value::

    # content of test_sample.py
    def func(x):
        return x + 1
    def test_answer():
        assert func(3) == 5

Now you can execute the test function::

    $ py.test test_sample.py
    ========================= test session starts ==========================
    platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev4
    test path 1: test_sample.py
    
    test_sample.py F
    
    =============================== FAILURES ===============================
    _____________________________ test_answer ______________________________
    
        def test_answer():
    >       assert func(3) == 5
    E       assert 4 == 5
    E        +  where 4 = func(3)
    
    test_sample.py:4: AssertionError
    ======================= 1 failed in 0.02 seconds =======================

We got a failure because our little ``func(3)`` call did not return ``5``.
A few notes on this little test invocation:

* ``test_answer`` was identified as a test function because of the
  ``test_`` prefix,

*  we conveniently used the standard `assert statement`_ and the failure
   report shows us the intermediate values.

.. _`assert statement`: http://docs.python.org/reference/simple_stmts.html#the-assert-statement

Asserting that a certain exception is raised
--------------------------------------------------------------

If you want to assert a test raises a certain exception you can
use the ``raises`` helper::

    # content of test_sysexit.py
    import py
    def f():
        raise SystemExit(1)

    def test_mytest():
        with py.test.raises(SystemExit):
            f()

Running it with::

    $ py.test test_sysexit.py
    ========================= test session starts ==========================
    platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev4
    test path 1: test_sysexit.py
    
    test_sysexit.py .
    
    ======================= 1 passed in 0.01 seconds =======================

.. For further ways to assert exceptions see the :pyfunc:`raises`

where to go from here
-------------------------------------

Here are a few suggestions where to go next:

* :ref:`cmdline` for command line invocation examples
* :ref:`good practises` for virtualenv, test layout, genscript support
* :ref:`apiref` for documentation and examples on writing Python tests
* :ref:`examples` for more complex examples

.. include:: links.inc