From 8853c5bdef39c9c68bcf34cc7c35fe88232715bd Mon Sep 17 00:00:00 2001 From: holger krekel Date: Thu, 14 Oct 2010 01:25:09 +0200 Subject: [PATCH] merge install and basic usage into getting-started.txt add an assert1.txt --HG-- branch : trunk --- doc/apiref.txt | 5 +- doc/assert.txt | 135 +++++++++++++++++++ doc/cmdline.txt | 2 + doc/example/x.txt | 54 -------- doc/examples.txt | 2 + doc/{basic_usage.txt => getting-started.txt} | 38 ++++-- doc/goodpractises.txt | 13 ++ doc/install.txt | 33 ----- doc/links.inc | 2 + doc/overview.txt | 3 +- 10 files changed, 189 insertions(+), 98 deletions(-) create mode 100644 doc/assert.txt rename doc/{basic_usage.txt => getting-started.txt} (55%) delete mode 100644 doc/install.txt diff --git a/doc/apiref.txt b/doc/apiref.txt index 333b6ee32..da177c70c 100644 --- a/doc/apiref.txt +++ b/doc/apiref.txt @@ -1,10 +1,13 @@ +.. _apiref: + py.test reference documentation ================================================ .. toctree:: :maxdepth: 2 - + + assert.txt funcargs.txt xunit_setup.txt capture.txt diff --git a/doc/assert.txt b/doc/assert.txt new file mode 100644 index 000000000..a293185a0 --- /dev/null +++ b/doc/assert.txt @@ -0,0 +1,135 @@ + +Writing easy assertions in tests +============================================ + +assert with the ``assert`` statement +--------------------------------------------------------- + +``py.test`` allows to use the standard python ``assert`` for verifying +expectations and values in Python tests. For example, you can write the +following in your tests:: + + # content of test_assert1.py + def f(): + return 3 + + def test_function(): + assert f() == 4 + +to state that your object has a certain ``attribute``. In case this +assertion fails you will see the value of ``x``:: + + $ py.test test_assert1.py + =========================== test session starts ============================ + platform linux2 -- Python 2.6.5 -- pytest-2.0.0dev0 + test path 1: test_assert1.py + + test_assert1.py F + + ================================= FAILURES ================================= + ______________________________ test_function _______________________________ + + def test_function(): + > assert f() == 4 + E assert 3 == 4 + E + where 3 = f() + + test_assert1.py:5: AssertionError + ========================= 1 failed in 0.02 seconds ========================= + +Reporting details about the failing assertion is achieved by re-evaluating +the assert expression and recording intermediate values. + +Note: If evaluating the assert expression has side effects you may get a +warning that the intermediate values could not be determined safely. A +common example for this issue is reading from a file and comparing in one +line:: + + assert f.read() != '...' + +This might fail but when re-interpretation comes along it might pass. +You can rewrite this (and any other expression with side effects) easily, though: + + content = f.read() + assert content != '...' + +assertions about expected exceptions +------------------------------------------ + +In order to write assertions about raised exceptions, you can use +``py.test.raises`` as a context manager like this:: + + with py.test.raises(ZeroDivisionError): + 1 / 0 + +and if you need to have access to the actual exception info you may use:: + + with py.test.raises(RuntimeError) as excinfo: + def f(): + f() + f() + + # do checks related to excinfo.type, excinfo.value, excinfo.traceback + +If you want to write test code that works on Python2.4 as well, +you may also use two other ways to test for an expected exception:: + + py.test.raises(ExpectedException, func, *args, **kwargs) + py.test.raises(ExpectedException, "func(*args, **kwargs)") + +both of which execute the specified function with args and kwargs and +asserts that the given ``ExpectedException`` is raised. The reporter will +provide you with helpful output in case of failures such as *no +exception* or *wrong exception*. + +Making use of context-sensitive comparisons +------------------------------------------------- + +.. versionadded:: 2.0 + +py.test has rich support for providing context-sensitive informations +when it encounters comparisons. For example:: + + # content of test_assert2.py + + def test_set_comparison(): + set1 = set("1308") + set2 = set("8035") + assert set1 == set2 + +if you run this module:: + + $ py.test test_assert2.py + =========================== test session starts ============================ + platform linux2 -- Python 2.6.5 -- pytest-2.0.0dev0 + test path 1: test_assert2.py + + test_assert2.py F + + ================================= FAILURES ================================= + ___________________________ test_set_comparison ____________________________ + + def test_set_comparison(): + set1 = set("1308") + set2 = set("8035") + > assert set1 == set2 + E assert set(['0', '1', '3', '8']) == set(['0', '3', '5', '8']) + E Extra items in the left set: + E '1' + E Extra items in the right set: + E '5' + + test_assert2.py:5: AssertionError + ========================= 1 failed in 0.02 seconds ========================= + +Special comparisons are done for a number of cases: + +* comparing long strings: a context diff is shown +* comparing long sequences: first failing indices +* comparing dicts: different entries + +.. + Defining your own comparison + ---------------------------------------------- + + diff --git a/doc/cmdline.txt b/doc/cmdline.txt index f232ae914..3c33a0223 100644 --- a/doc/cmdline.txt +++ b/doc/cmdline.txt @@ -1,4 +1,6 @@ +.. _cmdline: + Using the interactive command line =============================================== diff --git a/doc/example/x.txt b/doc/example/x.txt index ef7f445e5..df63880f5 100644 --- a/doc/example/x.txt +++ b/doc/example/x.txt @@ -105,60 +105,6 @@ that do not fail. .. _captured: plugin/capture.html -assert with the ``assert`` statement -+++++++++++++++++++++++++++++++++++++++++++++ - -``py.test`` allows to use the standard python -``assert statement`` for verifying expectations -and values in Python tests. For example, you can -write the following in your tests:: - - assert hasattr(x, 'attribute') - -to state that your object has a certain ``attribute``. In case this -assertion fails you will see the value of ``x``. Intermediate -values are computed by executing the assert expression a second time. -If you execute code with side effects, e.g. read from a file like this:: - - assert f.read() != '...' - -then you may get a warning from pytest if that assertions -first failed and then succeeded. - -asserting expected exceptions -+++++++++++++++++++++++++++++++++++++++ - -In order to write assertions about exceptions, you can use -``py.test.raises`` as a context manager like this: - -.. sourcecode:: python - - with py.test.raises(ZeroDivisionError): - 1 / 0 - -and if you need to have access to the actual exception info you may use: - -.. sourcecode:: python - - with py.test.raises(RuntimeError) as excinfo: - def f(): - f() - f() - - # do checks related to excinfo.type, excinfo.value, excinfo.traceback - -If you want to write test code that works on Python2.4 as well, -you may also use two other ways to test for an expected exception: - -.. sourcecode:: python - - py.test.raises(ExpectedException, func, *args, **kwargs) - py.test.raises(ExpectedException, "func(*args, **kwargs)") - -both of which execute the specified function with args and kwargs and -asserts that the given ``ExpectedException`` is raised. The reporter will -provide you with helpful output in case of failures such as *no -exception* or *wrong exception*. information-rich tracebacks, PDB introspection +++++++++++++++++++++++++++++++++++++++++++++++++++++++ diff --git a/doc/examples.txt b/doc/examples.txt index 44bca9953..9a7935a39 100644 --- a/doc/examples.txt +++ b/doc/examples.txt @@ -1,4 +1,6 @@ +.. _examples: + Usages and Examples =========================================== diff --git a/doc/basic_usage.txt b/doc/getting-started.txt similarity index 55% rename from doc/basic_usage.txt rename to doc/getting-started.txt index 0dac45c93..1094c44ff 100644 --- a/doc/basic_usage.txt +++ b/doc/getting-started.txt @@ -1,17 +1,28 @@ -.. _`setuptools installation`: http://pypi.python.org/pypi/setuptools +Installation and Getting Started +=================================== +.. _`easy_install`: -Basic usage -================== +Installation using easy_install +---------------------------------------- -We assume you have done an :ref:`install` like this:: +**PyPI distribution name**: pytest_. **repository**: https://bitbucket.org/hpk42/pytest - easy_install -U pytest # or - pip install -U pytest +**Compatibility**: Python 2.4-3.2, Jython, PyPy on Unix/Posix and Windows -Ensure that this installed the ``py.test`` script:: +You need to have setuptools_ or Distribute_ to install or upgrade ``py.test``:: - py.test --version + 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 @@ -56,3 +67,14 @@ A few notes on this little test invocation: .. _`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 + diff --git a/doc/goodpractises.txt b/doc/goodpractises.txt index 1fd1f6b1a..a95d41dd9 100644 --- a/doc/goodpractises.txt +++ b/doc/goodpractises.txt @@ -1,4 +1,6 @@ +.. _`good practises`: + Good Practises ================================================= @@ -18,6 +20,17 @@ reproducible and reliable test environment. .. _standalone: + +Choosing a test layout +---------------------------- + +py.test supports common test layouts. + +XXX + + + + Generating a py.test standalone Script ------------------------------------------- diff --git a/doc/install.txt b/doc/install.txt deleted file mode 100644 index 87f23538e..000000000 --- a/doc/install.txt +++ /dev/null @@ -1,33 +0,0 @@ - -installing py.test -=================================================== - -**PyPI name**: pytest_ - -**hg repository**: https://bitbucket.org/hpk42/pytest - -**Compatibility**: Python 2.4-3.2, Jython, PyPy on Unix/Posix and Windows - -.. _`easy_install`: - -Installation using easy_install ----------------------------------------- - -If you have setuptools_ or Distribute_ type:: - - easy_install -U pytest - -to install the latest release of ``py.test``. The ``-U`` switch -triggers an upgrade if you already have an older version installed. -Note that setuptools works ok with Python2 interpreters while **Distribute -works with Python3 and Python2** and also avoids some issues on Windows. - -You should now be able to type:: - - $ py.test --version - -Refer to :ref:`installation issues` if you have issues. - -.. include:: links.inc - - diff --git a/doc/links.inc b/doc/links.inc index 679b7eb4b..9bcfe5cf8 100644 --- a/doc/links.inc +++ b/doc/links.inc @@ -11,4 +11,6 @@ .. _mercurial: http://mercurial.selenic.com/wiki/ .. _`setuptools`: http://pypi.python.org/pypi/setuptools .. _`distribute`: http://pypi.python.org/pypi/distribute +.. _`pip`: http://pypi.python.org/pypi/pip +.. _`virtualenv`: http://pypi.python.org/pypi/virtualenv .. _hudson: http://hudson-ci.org/ diff --git a/doc/overview.txt b/doc/overview.txt index 93406a60b..ecb50cc94 100644 --- a/doc/overview.txt +++ b/doc/overview.txt @@ -6,8 +6,7 @@ Overview and Introduction :maxdepth: 2 features.txt - install.txt - basic_usage.txt + getting-started.txt cmdline.txt goodpractises.txt faq.txt