[py-svn] r10243 - py/dist/py/documentation

[hpk at codespeak.net]

Author: hpk
Date: Sat Apr  2 03:21:43 2005
New Revision: 10243

Modified:
   py/dist/py/documentation/test.txt
Log:
added a trailing chapter about planned features in py.test 



Modified: py/dist/py/documentation/test.txt
==============================================================================
--- py/dist/py/documentation/test.txt	(original)
+++ py/dist/py/documentation/test.txt	Sat Apr  2 03:21:43 2005
@@ -475,3 +475,61 @@
 
 .. _`getting started`: getting_started.html
 .. _`py-dev mailing list`: http://codespeak.net/mailman/listinfo/py-dev 
+
+
+Future/Planned Features of py.test 
+==================================
+
+Please note that the following descriptions of future features
+sound factual although they aren't implemented yet.  This
+allows easy migration to real documentation later.
+Nevertheless, none of the described planned features is
+set in stone, yet. In fact, they are open to discussion on
+py-dev at codespeak dot net. 
+
+Hey, if you want to suggest new features or command line options 
+for py.test it would be great if you could do it by providing 
+documentation for the feature.  Welcome to documentation driven 
+development :-) 
+
+selecting tests by queries/full text search 
+-------------------------------------------
+
+You can selectively run tests by specifiying words 
+on the command line in a google-like way. Example:: 
+
+    py.test simple 
+
+will run all tests that are found from the current directory 
+and that have the word "simple" somewhere in their `test address`_.  
+``test_simple1`` and ``TestSomething.test_whatever_simpleton`` would both 
+qualify.  If you want to exclude the latter test method you could say:: 
+
+    py.test -- simple -simpleton 
+
+Note that the doubledash "--" signals the end of option parsing so
+that "-simpleton" will not be misinterpreted as a command line option. 
+
+Interpreting positional arguments as specifying search queries 
+means that you can only restrict the set of tests. There is no way to 
+say "run all 'simple' in addition to all 'complex' tests".  If this proves
+to be a problem we can probably come up with a command line option 
+that allows to specify multiple queries which all add to the set of
+tests-to-consider. 
+
+.. _`test address`: 
+
+the concept of a test address
+----------------------------- 
+
+For specifiying tests it is convenient to define the notion
+of a *test address*, representable as a filesystem path and a 
+list of names leading to a test item.  If represented as a single 
+string the path and names are separated by a `/` character, for example: 
+
+    ``somedir/somepath.py/TestClass/test_method``
+
+Such representations can be used to memoize failing tests 
+by writing them out in a file or communicating them across
+process and computer boundaries. 
+