test_ok2/doc/getting-started.txt

Installation and Getting Started
===================================

.. _`easy_install`:

Installation using easy_install
----------------------------------------

**PyPI distribution name**: pytest_.  **repository**: https://bitbucket.org/hpk42/pytest

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

You need to have setuptools_ or Distribute_ to install or upgrade ``py.test``::

    easy_install -U pytest

Note that setuptools works for Python2 interpreters and
**Distribute works for both Python3 and Python2** and fixes some issues
on Windows.  You may also use pip_ for installation on Python2 interpreters.

To check your installation works type::

    $ py.test --version

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


Writing a first test
------------------------------

Let's create a small file with the following content::

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

That's it.  Now you can already execute the test function::

    $ py.test test_sample.py
    =========================== test session starts ============================
    platform linux2 -- Python 2.6.5 -- pytest-2.0.0dev0
    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


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