add a --funcargs option showing available funcargs

--HG--
branch : trunk

CHANGELOG

@@ -1,6 +1,9 @@
 Changes between 1.2.1 and 1.2.0
 =====================================
 
+- add a new option "--funcargs" that shows available funcargs 
+  and their help strings (docstrings on the factory) for a
+  given test path
 - display a short and concise traceback if a funcarg lookup fails 
 - early-load "test*/conftest.py" files, i.e. conftest.py files in
   directories starting with 'test'.  allows to conveniently keep and access

py/_plugin/pytest_terminal.py

@@ -23,13 +23,19 @@ def pytest_addoption(parser):
     group._addoption('--fulltrace',
                action="store_true", dest="fulltrace", default=False,
                help="don't cut any tracebacks (default is to cut).")
-
+    group._addoption('--funcargs',
+               action="store_true", dest="showfuncargs", default=False,
+               help="show available function arguments, sorted by plugin")
 
 def pytest_configure(config):
     if config.option.collectonly:
         reporter = CollectonlyReporter(config)
+    elif config.option.showfuncargs:
+        config.setsessionclass(ShowFuncargSession)
+        reporter = None
     else:
         reporter = TerminalReporter(config)
+    if reporter:
         # XXX see remote.py's XXX 
         for attr in 'pytest_terminal_hasmarkup', 'pytest_terminal_fullwidth':
             if hasattr(config, attr):
@@ -447,3 +453,42 @@ def flatten(l):
                 yield y
         else:
             yield x
+
+from py._test.session import Session
+class ShowFuncargSession(Session):
+    def main(self, colitems):
+        self.sessionstarts()
+        try:
+            self.showargs(colitems[0])
+        finally:
+            self.sessionfinishes(exitstatus=1)
+
+    def showargs(self, colitem):
+        tw = py.io.TerminalWriter()
+        from py._test.funcargs import getplugins
+        from py._test.funcargs import FuncargRequest
+        plugins = getplugins(colitem, withpy=True)
+        verbose = self.config.getvalue("verbose")
+        for plugin in plugins:
+            available = []
+            for name, factory in vars(plugin).items():
+                if name.startswith(FuncargRequest._argprefix):
+                    name = name[len(FuncargRequest._argprefix):]
+                    if name not in available:
+                        available.append([name, factory]) 
+            if available:
+                pluginname = plugin.__name__
+                for name, factory in available:
+                    if verbose:
+                        funcargspec = "%s -- from %s" %(name, plugin,)
+                    else:
+                        funcargspec = name
+                    tw.line(funcargspec, green=True)
+                    doc = factory.__doc__ or ""
+                    if doc:
+                        for line in doc.split("\n"):
+                            tw.line("    " + line.strip())
+                    else:
+                        tw.line("    no docstring available", red=True)
+                        tw.line(factory, red=True)
+                        tw.line(plugin, red=True)

testing/plugin/test_pytest_terminal.py

@@ -588,3 +588,12 @@ def test_trace_reporting(testdir):
         "*active plugins*"
     ])
     assert result.ret == 0
+
+@py.test.mark.nodist
+def test_show_funcarg(testdir, option):
+    result = testdir.runpytest(*option._getcmdargs())
+    assert result.stdout.fnmatch_lines([
+            "*tmpdir*",
+            "*temporary directory*",
+        ]
+    ])