holger krekel committed d12ea5e

fix issue127 improve pytest_addoption docs, add new config.getoption(name) method for consistency.

  • Participants
  • Parent commits 8bd54f9

Comments (0)

Files changed (10)

 - fix issue217 - support mock.patch with pytest's fixtures - note that
   you need either mock-1.0.1 or the python3.3 builtin unittest.mock.
+- fix issue127 - improve documentation for pytest_addoption() and
+  add a ``config.getoption(name)`` helper function for consistency.
 Changes between 2.3.1 and 2.3.2


-__version__ = '2.3.3.dev4'
+__version__ = '2.3.3.dev5'


 class Config(object):
     """ access to configuration values, pluginmanager and plugin hooks.  """
     def __init__(self, pluginmanager=None):
-        #: command line option values, which must have been previously added
-        #: via calls like ``parser.addoption(...)`` or
-        #: ``parser.getgroup(groupname).addoption(...)``
+        #: access to command line option as attributes.
+        #: (deprecated), use :py:func:`getoption() <_pytest.config.Config.getoption>` instead
         self.option = CmdOptions()
         self._parser = Parser(
             usage="usage: %prog [options] [file_or_dir] [file_or_dir] [...]",
         self._conftest = Conftest(onimport=self._onimportconftest)
         self.hook = self.pluginmanager.hook
         self._inicache = {}
+        self._opt2dest = {}
         self._cleanup = []
     def _processopt(self, opt):
+        for name in opt._short_opts + opt._long_opts:
+            self._opt2dest[name] = opt.dest
         if hasattr(opt, 'default') and opt.dest:
             if not hasattr(self.option, opt.dest):
                 setattr(self.option, opt.dest, opt.default)
         x.append(line) # modifies the cached list inline
     def getini(self, name):
-        """ return configuration value from an ini file. If the
-        specified name hasn't been registered through a prior ``parse.addini``
+        """ return configuration value from an :ref:`ini file <inifiles>`. If the
+        specified name hasn't been registered through a prior
+        :py:func:`parser.addini <pytest.config.Parser.addini>`
         call (usually from a plugin), a ValueError is raised. """
             return self._inicache[name]
         return self._conftest.rget(name, path)
+    def getoption(self, name):
+        """ return command line option value.
+        :arg name: name of the option.  You may also specify
+            the literal ``--OPT`` option instead of the "dest" option name.
+        """
+        name = self._opt2dest.get(name, name)
+        try:
+            return getattr(self.option, name)
+        except AttributeError:
+            raise ValueError("no option named %r" % (name,))
     def getvalue(self, name, path=None):
-        """ return ``name`` value looked set from command line options.
+        """ return command line option value.
+        :arg name: name of the command line option
         (deprecated) if we can't find the option also lookup
         the name in a matching conftest file.


     """modify command line arguments before option parsing. """
 def pytest_addoption(parser):
-    """use the parser to add optparse-style options and ini-style
-    config values via calls, see :py:func:`parser.addoption(...)
-    <_pytest.config.Parser.addoption>`
-    and :py:func:`parser.addini(...) <_pytest.config.Parser.addini>`.
+    """register optparse-style options and ini-style config values.
+    This function must be implemented in a :ref:`plugin <pluginorder>` and is
+    called once at the beginning of a test run.
+    :arg parser: To add command line options, call
+        :py:func:`parser.addoption(...) <_pytest.config.Parser.addoption>`.
+        To add ini-file values call :py:func:`parser.addini(...)
+        <_pytest.config.Parser.addini>`.
+    Options can later be accessed through the
+    :py:class:`config <_pytest.config.Config>` object, respectively:
+    - :py:func:`config.getoption(name) <_pytest.config.Config.getoption>` to
+      retrieve the value of a command line option.
+    - :py:func:`config.getini(name) <_pytest.config.Config.getini>` to retrieve
+      a value read from an ini-style file.
+    The config object is passed around on many internal objects via the ``.config``
+    attribute or can be retrieved as the ``pytestconfig`` fixture or accessed
+    via (deprecated) ``pytest.config``.
 def pytest_cmdline_main(config):
 pytest_cmdline_main.firstresult = True
 def pytest_configure(config):
-    """ called after command line options have been parsed.
+    """ called after command line options have been parsed
         and all plugins and initial conftest files been loaded.


 This will display command line and configuration file settings
 which were registered by installed plugins.
+.. _inifiles:
 How test configuration is read from configuration INI-files


     import pytest
     def pytest_addoption(parser):
-        parser.addoption("-E", dest="env", action="store", metavar="NAME",
+        parser.addoption("-E", action="store", metavar="NAME",
             help="only run tests matching the environment NAME.")
     def pytest_configure(config):
         envmarker = item.keywords.get("env", None)
         if envmarker is not None:
             envname = envmarker.args[0]
-            if envname != item.config.option.env:
+            if envname != item.config.getoption("-E"):
                 pytest.skip("test requires env %r" % envname)
 A test file using this local plugin::


     def cmdopt(request):
-        return request.config.option.cmdopt
+        return request.config.getoption("--cmdopt")
 Let's run this without supplying our new option::
             help="run slow tests")
     def pytest_runtest_setup(item):
-        if 'slow' in item.keywords and not item.config.getvalue("runslow"):
+        if 'slow' in item.keywords and not item.config.getoption("--runslow"):
             pytest.skip("need --runslow option to run")
 We can now write a test module like this::


 py.test implements all aspects of configuration, collection, running and reporting by calling `well specified hooks`_.  Virtually any Python module can be registered as a plugin.  It can implement any number of hook functions (usually two or three) which all have a ``pytest_`` prefix, making hook functions easy to distinguish and find.  There are three basic location types:
-* `builtin plugins`_: loaded from py.test's own ``pytest/plugin`` directory.
+* `builtin plugins`_: loaded from py.test's internal ``_pytest`` directory.
 * `external plugins`_: modules discovered through `setuptools entry points`_
 * ` plugins`_: modules auto-discovered in test directories
 ``myproject.pluginmodule`` as a plugin which can define
 `well specified hooks`_.
+.. _`pluginorder`:
 Plugin discovery order at tool startup
 * by recursively loading all plugins specified by the
   ``pytest_plugins`` variable in ```` files
 Requiring/Loading plugins in a test module or conftest file
         description='py.test: simple powerful testing with Python',
         long_description = long_description,
-        version='2.3.3.dev4',
+        version='2.3.3.dev5',
         license='MIT license',
         platforms=['unix', 'linux', 'osx', 'cygwin', 'win32'],


         assert config.getvalue("x", o) == 1
         pytest.raises(KeyError, 'config.getvalue("y", o)')
+    def test_config_getoption(self, testdir):
+        testdir.makeconftest("""
+            def pytest_addoption(parser):
+                parser.addoption("--hello", "-X", dest="hello")
+        """)
+        config = testdir.parseconfig("--hello=this")
+        for x in ("hello", "--hello", "-X"):
+            assert config.getoption(x) == "this"
+        pytest.raises(ValueError, "config.getoption('qweqwe')")
     def test_config_getvalueorskip(self, testdir):
         config = testdir.parseconfig()