p53209761
/
test_ok2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fix up install docs and plugin docs for the final release 

have CHANGELOG be a file containing links instead of a symlink
beause it causes issues with pip-install on some systems.

--HG--
branch : trunk
This commit is contained in:
holger krekel 2009-11-05 17:46:14 +01:00
parent a5a94c4e8f
commit e0bca8fe51
10 changed files with 166 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGELOG
View File

@ -1 +0,0 @@
doc/changelog.txt

7
CHANGELOG Normal file
View File

@ -0,0 +1,7 @@
see doc/announce/release-1.1.0.txt for a summary
of the last minor release
and
see doc/changelog.txt for details

12
doc/announce/release-1.1.0.txt
View File

@ -3,30 +3,30 @@ py.test/pylib 1.1.0: Python3, Jython, advanced skipping, cleanups ...
Features:
* compatible to Python3 (single py2/py3 source), works with Distribute
* compatible to Python3 (single py2/py3 source), `easy to install`_
* generalized marking_: mark tests one a whole-class or whole-module basis
* conditional skipping_: skip/xfail based on platform/dependencies
Fixes:
* code reduction and "de-magification" (e.g. 23 KLoc -> 11 KLOC)
* distribute testing requires the now separately released 'execnet' package
* distribute testing requires the now separately released execnet_ package
* funcarg-setup/caching, "same-name" test modules now cause an exlicit error
* de-cluttered reporting, --report option for skipped/xfail details
* de-cluttered reporting options, --report for skipped/xfail details
Compatibilities
1.1.0 should allow running test code that already worked well with 1.0.2
plus some more due to improved unittest/nose compatibility.
More information:
http://pytest.org
More information: http://pytest.org
thanks and have fun,
holger (http://twitter.com/hpk42)
.. _execnet: http://codespeak.net/execnet
.. _`easy to install`: ../install.html
.. _marking: ../test/plugin/mark.html
.. _skipping: ../test/plugin/skipping.html

113
doc/install.txt
View File

@ -5,27 +5,75 @@
.. _`PyPI project page`: http://pypi.python.org/pypi/py/
Latest Release, see `PyPI project page`_
using easy_install (via Distribute or setuptools)
py.test/pylib compat/install info in a nutshell
===================================================
It is recommended to use `Distribute for installation`_ as a drop-in
replacement for setuptools_. While setuptools should work well on
Python2 versions, `Distribute`_ allows to install py.test on Python3
and it avoids issue on Windows. With either packaging system
you can type::
PyPI Pyckage name: "**py**", see `PyPI project page`_ for latest version
Installers: easy_install_ and pip_, setuptools_ or Distribute_
Pythons: 2.4, 2.5, 2.6, 3.0, 3.1, Jython-2.5.1, PyPy-1.1
Operating systems: Linux, Windows and OSX + probably many others
Best practise: install tool and dependencies virtually
===========================================================
It is recommended to work with virtual environments
(e.g. virtualenv_ or buildout_ based) and use easy_install_
(or pip_) for installing py.test/pylib and any dependencies
you need to run your tests. Local virtual Python environments
(as opposed to system-wide "global" environments) make for a more
reproducible and reliable test environment.
Note: as of November 2009 pytest/pylib 1.1 RPMs and DEB packages
are not available. If you want to easy_install the newest py.test
and pylib do everyone a favour and uninstall older versions
from the global system e.g. like this on Ubuntu::
sudo apt-get remove --purge python-codespeak-lib
.. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
.. _`buildout`: http://www.buildout.org/
.. _pip: http://pypi.python.org/pypi/pip
.. _`easy_install`:
using easy_install (from setuptools or Distribute)
===================================================
Both `Distribute`_ and setuptools_ provide the ``easy_install``
installation tool. While setuptools should work ok with
Python2 interpreters, `Distribute`_ also works with Python3
and it avoids some issues on Windows. In both cases you
can open a command line window and then type::
easy_install -U py
to get the latest release of the py lib and py.test. The ``-U`` switch
to install the latest release of the py lib and py.test. The ``-U`` switch
will trigger an upgrade if you already have an older version installed.
On Linux systems you may need to execute the command as superuser and
on Windows you might need to write down the full path to ``easy_install``.
The py lib and its tools are expected to work well on Linux,
Windows and OSX, Python versions 2.4, 2.5, 2.6 through to
the Python3 versions 3.0 and 3.1 and Jython
If you now type::
py.test --version
you should see the version number and the import location of the tool.
Maybe you want to head on with the `quickstart`_ now?
.. _quickstart: test/quickstart.html
Troubleshooting
========================
**On Linux**: If ``easy_install`` fails because it needs to run
as the superuser you are trying to install things globally
and need to put ``sudo`` in front of the command.
**On Windows**: If "easy_install" or "py.test" are not found
please see here: `How do i run a Python program under Windows?`_
.. _`How do i run a Python program under Windows?`: http://www.python.org/doc/faq/windows/#how-do-i-run-a-python-program-under-windows
.. _mercurial: http://mercurial.selenic.com/wiki/
.. _`Distribute`:
@ -37,9 +85,8 @@ the Python3 versions 3.0 and 3.1 and Jython
Working from version control or a tarball
=================================================
To follow development or help with fixing things
for the next release, checkout the complete code
and documentation source with mercurial_::
To follow development or start experiments, checkout the
complete code and documentation source with mercurial_::
hg clone https://bitbucket.org/hpk42/py-trunk/
@ -71,11 +118,11 @@ in order to work inline with the tools and the lib of your checkout.
directly use a checkout or tarball
-------------------------------------------------------------
Once you got yourself a checkout_ or tarball_ you only need to
set ``PYTHONPATH`` and ``PATH`` environment variables.
It is usually a good idea to add the parent directory of the ``py`` package
directory to your ``PYTHONPATH`` and ``py/bin`` or ``py\bin\win32`` to your
system wide ``PATH`` settings. There are helper scripts that set ``PYTHONPATH`` and ``PATH`` on your system:
Once you got yourself a checkout_ or tarball_ it is usually a good
idea to add the parent directory of the ``py`` package directory
to your ``PYTHONPATH`` and ``py/bin`` or ``py\bin\win32`` to your
system wide ``PATH`` settings. There are helper scripts that
set ``PYTHONPATH`` and ``PATH`` on your system:
on windows execute::
@ -90,6 +137,9 @@ on linux/OSX add this to your shell initialization::
both of which which will get you good settings
for ``PYTHONPATH`` and ``PATH``.
If you install ``py.test`` this way you can easily
``hg pull && hg up`` your checkout to follow the
development tree.
note: scripts look for "nearby" py-lib
-----------------------------------------------------
@ -104,22 +154,15 @@ for "nearby" py libs, so if you have a layout like this::
py/
issuing ``py.test subpkg1`` will use the py lib
from that projects root directory.
from that projects root directory. Giving the
state of Python packaging there can be confusion
in which case issuing::
py.test --version
tells you both version and import location of the tool.
.. _`command line scripts`: bin.html
Debian and RPM packages
===================================
As of August 2009 pytest/pylib 1.0 RPMs and Debian packages
are not available. You will only find 0.9 versions -
on Debian systems look for ``python-codespeak-lib``
and Dwayne Bailey has put together a Fedora `RPM`_.
If you can help with providing/upgrading distribution
packages please use of the contact_ channels in case
of questions or need for changes.
.. _contact: contact.html
.. _`RPM`: http://translate.sourceforge.net/releases/testing/fedora/pylib-0.9.2-1.fc9.noarch.rpm

7
doc/test/plugin/coverage.txt
View File

@ -1,10 +1,9 @@
pytest_xmlresult plugin (EXTERNAL)
pytest_coverage plugin (EXTERNAL)
==========================================
This plugin allows to write results in an XML format
compatible to CruiseControl_, see here for download:
This plugin allows to use Ned's coverage_ package, see
http://github.com/rozza/py.test-plugins
.. _CruiseControl: http://cruisecontrol.sourceforge.net/
.. _coverage: http://pypi.python.org/pypi/coverage

8
doc/test/plugin/mark.txt
View File

@ -72,6 +72,14 @@ Later called markers may overwrite previous key-value settings.
Positional arguments are all appended to the same 'args' list
of the Marker object.
Using "-k MARKNAME" to select tests
----------------------------------------------------
You can use the ``-k`` command line option to select
tests::
py.test -k webtest # will only run tests marked as webtest
Start improving this plugin in 30 seconds
=========================================

31
doc/test/plugin/skipping.txt
View File

@ -9,7 +9,7 @@ advanced skipping for python test functions, classes or modules.
With this plugin you can mark test functions for conditional skipping
or as "xfail", expected-to-fail. Skipping a test will avoid running it
while xfail-marked tests will run and result in an inverted outcome:
at all while xfail-marked tests will run and result in an inverted outcome:
a pass becomes a failure and a fail becomes a semi-passing one.
The need for skipping a test is usually connected to a condition.
@ -22,29 +22,37 @@ at the end of a test run.
.. _skipif:
mark a test function to be skipped
Skipping a single function
-------------------------------------------
Here is an example for skipping a test function when
running on Python3::
Here is an example for marking a test function to be skipped
when run on a Python3 interpreter::
@py.test.mark.skipif("sys.version_info >= (3,0)")
def test_function():
...
During test function setup the skipif condition is
evaluated by calling ``eval(expr, namespace)``. The namespace
contains the ``sys`` and ``os`` modules as well as the
test ``config`` object. The latter allows you to skip based
contains the ``sys`` and ``os`` modules and the test
``config`` object. The latter allows you to skip based
on a test configuration value e.g. like this::
@py.test.mark.skipif("not config.getvalue('db')")
def test_function(...):
...
Create a shortcut for your conditional skip decorator
at module level like this::
mark many test functions at once
win32only = py.test.mark.skipif("sys.platform != 'win32'")
@win32only
def test_function():
...
skip groups of test functions
--------------------------------------
As with all metadata function marking you can do it at
@ -58,11 +66,12 @@ for skipping all methods of a test class based on platform::
# will not be setup or run under 'win32' platform
#
The ``pytestmark`` decorator will be applied to each test function.
.. _`whole class- or module level`: mark.html#scoped-marking
mark a test function as expected to fail
mark a test function as **expected to fail**
-------------------------------------------------------
You can use the ``xfail`` marker to indicate that you
@ -79,7 +88,7 @@ when it fails. Instead terminal reporting will list it in the
Same as with skipif_ you can also selectively expect a failure
depending on platform::
@py.test.mark.xfail(if"sys.version_info >= (3,0)")
@py.test.mark.xfail("sys.version_info >= (3,0)")
def test_function():
...
@ -89,7 +98,7 @@ skipping on a missing import dependency
--------------------------------------------------
You can use the following import helper at module level
or within a test or setup function.
or within a test or test setup function::
docutils = py.test.importorskip("docutils")

7
doc/test/plugin/xmlresult.txt
View File

@ -1,6 +1,9 @@
pytest_coverage plugin (EXTERNAL)
pytest_xmlresult plugin (EXTERNAL)
==========================================
This plugin allows to use Ned's coverage package, see
This plugin allows to write results in an XML format
compatible to CruiseControl_, see here for download:
http://github.com/rozza/py.test-plugins
.. _CruiseControl: http://cruisecontrol.sourceforge.net/

13
doc/test/quickstart.txt
View File

@ -7,7 +7,7 @@ Quickstart
.. _here: ../install.html
If you have any ``easy_install`` (otherwise see here_) just type::
If you have the ``easy_install`` tool (otherwise see here_) just type::
easy_install -U py
@ -30,7 +30,7 @@ and will see output like this:
.. sourcecode:: python
=========================== test session starts ============================
python: platform linux2 -- Python 2.6.2
python: platform linux2 -- Python 2.6.2 -- pytest-1.1.0
test object 1: test_sample.py
test_sample.py F
@ -51,15 +51,18 @@ a progress report and important details of the failure.
**Where to go from here**
`tutorials`_: a collection of starting points with code examples
`features`_: overview and description of test features
`contact`_: many ways for feedback and questions
`plugins`_: a list of available plugins which each contain usage examples
`tutorials`_: some blog entries and starting points with code examples
`contact`_: if you want to feedback or have problems
.. _`contact`: ../contact.html
.. _`automatically collected`: features.html#autocollect
.. _install: ../install.html
.. _plugins: plugin/index.html
.. _features: features.html
.. _tutorials: talks.html

9
py/plugin/pytest_mark.py
View File

@ -65,6 +65,15 @@ The order in which marker functions are called is this::
Later called markers may overwrite previous key-value settings.
Positional arguments are all appended to the same 'args' list
of the Marker object.
Using "-k MARKNAME" to select tests
----------------------------------------------------
You can use the ``-k`` command line option to select
tests::
py.test -k webtest # will only run tests marked as webtest
"""
import py

29
py/plugin/pytest_skipping.py
View File

@ -3,7 +3,7 @@ advanced skipping for python test functions, classes or modules.
With this plugin you can mark test functions for conditional skipping
or as "xfail", expected-to-fail. Skipping a test will avoid running it
while xfail-marked tests will run and result in an inverted outcome:
at all while xfail-marked tests will run and result in an inverted outcome:
a pass becomes a failure and a fail becomes a semi-passing one.
The need for skipping a test is usually connected to a condition.
@ -16,29 +16,37 @@ at the end of a test run.
.. _skipif:
mark a test function to be skipped
Skipping a single function
-------------------------------------------
Here is an example for skipping a test function when
running on Python3::
Here is an example for marking a test function to be skipped
when run on a Python3 interpreter::
@py.test.mark.skipif("sys.version_info >= (3,0)")
def test_function():
...
During test function setup the skipif condition is
evaluated by calling ``eval(expr, namespace)``. The namespace
contains the ``sys`` and ``os`` modules as well as the
test ``config`` object. The latter allows you to skip based
contains the ``sys`` and ``os`` modules and the test
``config`` object. The latter allows you to skip based
on a test configuration value e.g. like this::
@py.test.mark.skipif("not config.getvalue('db')")
def test_function(...):
...
Create a shortcut for your conditional skip decorator
at module level like this::
mark many test functions at once
win32only = py.test.mark.skipif("sys.platform != 'win32'")
@win32only
def test_function():
...
skip groups of test functions
--------------------------------------
As with all metadata function marking you can do it at
@ -52,11 +60,12 @@ for skipping all methods of a test class based on platform::
# will not be setup or run under 'win32' platform
#
The ``pytestmark`` decorator will be applied to each test function.
.. _`whole class- or module level`: mark.html#scoped-marking
mark a test function as expected to fail
mark a test function as **expected to fail**
-------------------------------------------------------
You can use the ``xfail`` marker to indicate that you
@ -73,7 +82,7 @@ when it fails. Instead terminal reporting will list it in the
Same as with skipif_ you can also selectively expect a failure
depending on platform::
@py.test.mark.xfail(if"sys.version_info >= (3,0)")
@py.test.mark.xfail("sys.version_info >= (3,0)")
def test_function():
...