From f466d357710c59a37c289eb241b27b683cf5e2a0 Mon Sep 17 00:00:00 2001 From: holger krekel Date: Sun, 24 Oct 2010 21:55:27 +0200 Subject: [PATCH] add example for catching exceptions, simplify install doc --HG-- branch : trunk --- CHANGELOG | 1 + doc/Makefile | 3 ++ doc/faq.txt | 18 +++++++++++- doc/getting-started.txt | 65 ++++++++++++++++++++++++++++------------- 4 files changed, 65 insertions(+), 22 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index 31164b9ba..64fa5eec8 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -21,6 +21,7 @@ Changes between 1.3.4 and 2.0.0dev0 - refine 'tmpdir' creation, will now create basenames better associated with test names (thanks Ronny) - "xpass" (unexpected pass) tests don't cause exitcode!=0 +- fix issue131 / issue60 - importing doctests in __init__ files used as namespace packages Changes between 1.3.3 and 1.3.4 ---------------------------------------------- diff --git a/doc/Makefile b/doc/Makefile index 1a34cf6fe..16febb959 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -36,6 +36,9 @@ help: clean: -rm -rf $(BUILDDIR)/* +install: html + rsync -avz _build/html/ code:public_html/pytest + html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo diff --git a/doc/faq.txt b/doc/faq.txt index f0ede1d73..e7b69e42f 100644 --- a/doc/faq.txt +++ b/doc/faq.txt @@ -6,7 +6,23 @@ Frequent Issues and Questions Installation issues ------------------------------ -easy_install or py.test not found on Windows machine +easy_install or pip not found? +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Consult distribute_ to install the ``easy_install`` tool on your machine. +You may also use the original but somewhat older `setuptools`_ project +although we generally recommend to use ``distribute`` because it contains +more bug fixes and also works for Python3. + +For Python2 you can also consult pip_ for the popular ``pip`` tool. + +for the according ``pip`` installation tool. installation instructions. +You can also `setuptools`_ and +If you want to install on Python3 you need to use Distribute_ which +provides the ``easy_install`` utility. + + +py.test not found on Windows despite installation? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .. _`Python for Windows`: http://www.imladris.com/Scripts/PythonForWindows.html diff --git a/doc/getting-started.txt b/doc/getting-started.txt index 26a360d87..1a2d6ba15 100644 --- a/doc/getting-started.txt +++ b/doc/getting-started.txt @@ -1,34 +1,30 @@ -Installation and Getting Started +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``:: +Installation +---------------------------------------- - easy_install -U pytest +Installation options:: -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. + easy_install -U pytest # or + pip install -U pytest -To check your installation works type:: +To check your installation has installed the correct version:: $ py.test --version If you get an error, checkout :ref:`installation issues`. -Writing a first test ------------------------------- +Writing a simple test function with an assertion +---------------------------------------------------------- -Let's create a small file with the following content:: +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): @@ -36,17 +32,17 @@ Let's create a small file with the following content:: def test_answer(): assert func(3) == 5 -That's it. Now you can already execute the test function:: +Now you can execute the test function:: $ py.test test_sample.py - =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0dev0 + ========================= 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 ________________________________ + =============================== FAILURES =============================== + _____________________________ test_answer ______________________________ def test_answer(): > assert func(3) == 5 @@ -54,7 +50,7 @@ That's it. Now you can already execute the test function:: E + where 4 = func(3) test_sample.py:4: AssertionError - ========================= 1 failed in 0.02 seconds ========================= + ======================= 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: @@ -67,6 +63,33 @@ A few notes on this little test invocation: .. _`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 -------------------------------------