/usr/share/doc/python-pytest-doc/html/funcarg_compare.html is in python-pytest-doc 2.8.7-4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>pytest-2.3: reasoning for fixture/funcarg evolution</title>
<link rel="stylesheet" href="_static/flasky.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '2.8.7',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="shortcut icon" href="_static/pytest1favi.ico"/>
<link rel="top" title="None" href="contents.html" />
<link rel="next" title="Release announcements" href="announce/index.html" />
<link rel="prev" title="Talks and Tutorials" href="talks.html" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">
</head>
<body role="document">
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="announce/index.html" title="Release announcements"
accesskey="N">next</a></li>
<li class="right" >
<a href="talks.html" title="Talks and Tutorials"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="contents.html">pytest-2.8.7</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="pytest-2-3-reasoning-for-fixture-funcarg-evolution">
<span id="funcargcompare"></span><h1>pytest-2.3: reasoning for fixture/funcarg evolution<a class="headerlink" href="#pytest-2-3-reasoning-for-fixture-funcarg-evolution" title="Permalink to this headline">¶</a></h1>
<p><strong>Target audience</strong>: Reading this document requires basic knowledge of
python testing, xUnit setup methods and the (previous) basic pytest
funcarg mechanism, see <a class="reference external" href="http://pytest.org/2.2.4/funcargs.html">http://pytest.org/2.2.4/funcargs.html</a>
If you are new to pytest, then you can simply ignore this
section and read the other sections.</p>
<div class="section" id="shortcomings-of-the-previous-pytest-funcarg-mechanism">
<h2>Shortcomings of the previous <code class="docutils literal"><span class="pre">pytest_funcarg__</span></code> mechanism<a class="headerlink" href="#shortcomings-of-the-previous-pytest-funcarg-mechanism" title="Permalink to this headline">¶</a></h2>
<p>The pre pytest-2.3 funcarg mechanism calls a factory each time a
funcarg for a test function is required. If a factory wants to
re-use a resource across different scopes, it often used
the <code class="docutils literal"><span class="pre">request.cached_setup()</span></code> helper to manage caching of
resources. Here is a basic example how we could implement
a per-session Database object:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c1"># content of conftest.py</span>
<span class="k">class</span> <span class="nc">Database</span><span class="p">:</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">print</span> <span class="p">(</span><span class="s2">"database instance created"</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">destroy</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">print</span> <span class="p">(</span><span class="s2">"database instance destroyed"</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">pytest_funcarg__db</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
<span class="k">return</span> <span class="n">request</span><span class="o">.</span><span class="n">cached_setup</span><span class="p">(</span><span class="n">setup</span><span class="o">=</span><span class="n">DataBase</span><span class="p">,</span>
<span class="n">teardown</span><span class="o">=</span><span class="k">lambda</span> <span class="n">db</span><span class="p">:</span> <span class="n">db</span><span class="o">.</span><span class="n">destroy</span><span class="p">,</span>
<span class="n">scope</span><span class="o">=</span><span class="s2">"session"</span><span class="p">)</span>
</pre></div>
</div>
<p>There are several limitations and difficulties with this approach:</p>
<ol class="arabic simple">
<li>Scoping funcarg resource creation is not straight forward, instead one must
understand the intricate cached_setup() method mechanics.</li>
<li>parametrizing the “db” resource is not straight forward:
you need to apply a “parametrize” decorator or implement a
<a class="reference internal" href="writing_plugins.html#_pytest.hookspec.pytest_generate_tests" title="_pytest.hookspec.pytest_generate_tests"><code class="xref py py-func docutils literal"><span class="pre">pytest_generate_tests()</span></code></a> hook
calling <a class="reference internal" href="parametrize.html#_pytest.python.Metafunc.parametrize" title="_pytest.python.Metafunc.parametrize"><code class="xref py py-func docutils literal"><span class="pre">parametrize()</span></code></a> which
performs parametrization at the places where the resource
is used. Moreover, you need to modify the factory to use an
<code class="docutils literal"><span class="pre">extrakey</span></code> parameter containing <code class="docutils literal"><span class="pre">request.param</span></code> to the
<code class="xref py py-func docutils literal"><span class="pre">cached_setup()</span></code> call.</li>
<li>Multiple parametrized session-scoped resources will be active
at the same time, making it hard for them to affect global state
of the application under test.</li>
<li>there is no way how you can make use of funcarg factories
in xUnit setup methods.</li>
<li>A non-parametrized fixture function cannot use a parametrized
funcarg resource if it isn’t stated in the test function signature.</li>
</ol>
<p>All of these limitations are addressed with pytest-2.3 and its
improved <a class="reference internal" href="fixture.html#fixture"><span>fixture mechanism</span></a>.</p>
</div>
<div class="section" id="direct-scoping-of-fixture-funcarg-factories">
<h2>Direct scoping of fixture/funcarg factories<a class="headerlink" href="#direct-scoping-of-fixture-funcarg-factories" title="Permalink to this headline">¶</a></h2>
<p>Instead of calling cached_setup() with a cache scope, you can use the
<a class="reference internal" href="fixture.html#id1"><span>@pytest.fixture</span></a> decorator and directly state
the scope:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@pytest.fixture</span><span class="p">(</span><span class="n">scope</span><span class="o">=</span><span class="s2">"session"</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">db</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
<span class="c1"># factory will only be invoked once per session -</span>
<span class="n">db</span> <span class="o">=</span> <span class="n">DataBase</span><span class="p">()</span>
<span class="n">request</span><span class="o">.</span><span class="n">addfinalizer</span><span class="p">(</span><span class="n">db</span><span class="o">.</span><span class="n">destroy</span><span class="p">)</span> <span class="c1"># destroy when session is finished</span>
<span class="k">return</span> <span class="n">db</span>
</pre></div>
</div>
<p>This factory implementation does not need to call <code class="docutils literal"><span class="pre">cached_setup()</span></code> anymore
because it will only be invoked once per session. Moreover, the
<code class="docutils literal"><span class="pre">request.addfinalizer()</span></code> registers a finalizer according to the specified
resource scope on which the factory function is operating.</p>
</div>
<div class="section" id="direct-parametrization-of-funcarg-resource-factories">
<h2>Direct parametrization of funcarg resource factories<a class="headerlink" href="#direct-parametrization-of-funcarg-resource-factories" title="Permalink to this headline">¶</a></h2>
<p>Previously, funcarg factories could not directly cause parametrization.
You needed to specify a <code class="docutils literal"><span class="pre">@parametrize</span></code> decorator on your test function
or implement a <code class="docutils literal"><span class="pre">pytest_generate_tests</span></code> hook to perform
parametrization, i.e. calling a test multiple times with different value
sets. pytest-2.3 introduces a decorator for use on the factory itself:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@pytest.fixture</span><span class="p">(</span><span class="n">params</span><span class="o">=</span><span class="p">[</span><span class="s2">"mysql"</span><span class="p">,</span> <span class="s2">"pg"</span><span class="p">])</span>
<span class="k">def</span> <span class="nf">db</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
<span class="o">...</span> <span class="c1"># use request.param</span>
</pre></div>
</div>
<p>Here the factory will be invoked twice (with the respective “mysql”
and “pg” values set as <code class="docutils literal"><span class="pre">request.param</span></code> attributes) and and all of
the tests requiring “db” will run twice as well. The “mysql” and
“pg” values will also be used for reporting the test-invocation variants.</p>
<p>This new way of parametrizing funcarg factories should in many cases
allow to re-use already written factories because effectively
<code class="docutils literal"><span class="pre">request.param</span></code> was already used when test functions/classes were
parametrized via
<code class="xref py py-func docutils literal"><span class="pre">parametrize(indirect=True)()</span></code> calls.</p>
<p>Of course it’s perfectly fine to combine parametrization and scoping:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@pytest.fixture</span><span class="p">(</span><span class="n">scope</span><span class="o">=</span><span class="s2">"session"</span><span class="p">,</span> <span class="n">params</span><span class="o">=</span><span class="p">[</span><span class="s2">"mysql"</span><span class="p">,</span> <span class="s2">"pg"</span><span class="p">])</span>
<span class="k">def</span> <span class="nf">db</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
<span class="k">if</span> <span class="n">request</span><span class="o">.</span><span class="n">param</span> <span class="o">==</span> <span class="s2">"mysql"</span><span class="p">:</span>
<span class="n">db</span> <span class="o">=</span> <span class="n">MySQL</span><span class="p">()</span>
<span class="k">elif</span> <span class="n">request</span><span class="o">.</span><span class="n">param</span> <span class="o">==</span> <span class="s2">"pg"</span><span class="p">:</span>
<span class="n">db</span> <span class="o">=</span> <span class="n">PG</span><span class="p">()</span>
<span class="n">request</span><span class="o">.</span><span class="n">addfinalizer</span><span class="p">(</span><span class="n">db</span><span class="o">.</span><span class="n">destroy</span><span class="p">)</span> <span class="c1"># destroy when session is finished</span>
<span class="k">return</span> <span class="n">db</span>
</pre></div>
</div>
<p>This would execute all tests requiring the per-session “db” resource twice,
receiving the values created by the two respective invocations to the
factory function.</p>
</div>
<div class="section" id="no-pytest-funcarg-prefix-when-using-fixture-decorator">
<h2>No <code class="docutils literal"><span class="pre">pytest_funcarg__</span></code> prefix when using @fixture decorator<a class="headerlink" href="#no-pytest-funcarg-prefix-when-using-fixture-decorator" title="Permalink to this headline">¶</a></h2>
<p>When using the <code class="docutils literal"><span class="pre">@fixture</span></code> decorator the name of the function
denotes the name under which the resource can be accessed as a function
argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@pytest.fixture</span><span class="p">()</span>
<span class="k">def</span> <span class="nf">db</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
<span class="o">...</span>
</pre></div>
</div>
<p>The name under which the funcarg resource can be requested is <code class="docutils literal"><span class="pre">db</span></code>.</p>
<p>You can still use the “old” non-decorator way of specifying funcarg factories
aka:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">pytest_funcarg__db</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
<span class="o">...</span>
</pre></div>
</div>
<p>But it is then not possible to define scoping and parametrization.
It is thus recommended to use the factory decorator.</p>
</div>
<div class="section" id="solving-per-session-setup-autouse-fixtures">
<h2>solving per-session setup / autouse fixtures<a class="headerlink" href="#solving-per-session-setup-autouse-fixtures" title="Permalink to this headline">¶</a></h2>
<p>pytest for a long time offered a pytest_configure and a pytest_sessionstart
hook which are often used to setup global resources. This suffers from
several problems:</p>
<ol class="arabic simple">
<li>in distributed testing the master process would setup test resources
that are never needed because it only co-ordinates the test run
activities of the slave processes.</li>
<li>if you only perform a collection (with “–collect-only”)
resource-setup will still be executed.</li>
<li>If a pytest_sessionstart is contained in some subdirectories
conftest.py file, it will not be called. This stems from the
fact that this hook is actually used for reporting, in particular
the test-header with platform/custom information.</li>
</ol>
<p>Moreover, it was not easy to define a scoped setup from plugins or
conftest files other than to implement a <code class="docutils literal"><span class="pre">pytest_runtest_setup()</span></code> hook
and caring for scoping/caching yourself. And it’s virtually impossible
to do this with parametrization as <code class="docutils literal"><span class="pre">pytest_runtest_setup()</span></code> is called
during test execution and parametrization happens at collection time.</p>
<p>It follows that pytest_configure/session/runtest_setup are often not
appropriate for implementing common fixture needs. Therefore,
pytest-2.3 introduces <a class="reference internal" href="fixture.html#autouse-fixtures"><span>Autouse fixtures (xUnit setup on steroids)</span></a> which fully
integrate with the generic <a class="reference internal" href="fixture.html#fixture"><span>fixture mechanism</span></a>
and obsolete many prior uses of pytest hooks.</p>
</div>
<div class="section" id="funcargs-fixture-discovery-now-happens-at-collection-time">
<h2>funcargs/fixture discovery now happens at collection time<a class="headerlink" href="#funcargs-fixture-discovery-now-happens-at-collection-time" title="Permalink to this headline">¶</a></h2>
<p>pytest-2.3 takes care to discover fixture/funcarg factories
at collection time. This is more efficient especially for large test suites.
Moreover, a call to “py.test –collect-only” should be able to in the future
show a lot of setup-information and thus presents a nice method to get an
overview of fixture management in your project.</p>
</div>
<div class="section" id="conclusion-and-compatibility-notes">
<span id="funcargscompat"></span><span id="compatibility-notes"></span><h2>Conclusion and compatibility notes<a class="headerlink" href="#conclusion-and-compatibility-notes" title="Permalink to this headline">¶</a></h2>
<p><strong>funcargs</strong> were originally introduced to pytest-2.0. In pytest-2.3
the mechanism was extended and refined and is now described as
fixtures:</p>
<ul class="simple">
<li>previously funcarg factories were specified with a special
<code class="docutils literal"><span class="pre">pytest_funcarg__NAME</span></code> prefix instead of using the
<code class="docutils literal"><span class="pre">@pytest.fixture</span></code> decorator.</li>
<li>Factories received a <code class="docutils literal"><span class="pre">request</span></code> object which managed caching through
<code class="docutils literal"><span class="pre">request.cached_setup()</span></code> calls and allowed using other funcargs via
<code class="docutils literal"><span class="pre">request.getfuncargvalue()</span></code> calls. These intricate APIs made it hard
to do proper parametrization and implement resource caching. The
new <code class="xref py py-func docutils literal"><span class="pre">pytest.fixture()</span></code> decorator allows to declare the scope
and let pytest figure things out for you.</li>
<li>if you used parametrization and funcarg factories which made use of
<code class="docutils literal"><span class="pre">request.cached_setup()</span></code> it is recommended to invest a few minutes
and simplify your fixture function code to use the <a class="reference internal" href="fixture.html#pytest-fixture"><span>Fixtures as Function arguments</span></a>
decorator instead. This will also allow to take advantage of
the automatic per-resource grouping of tests.</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="contents.html">
<img class="logo" src="_static/pytest1.png" alt="Logo"/>
</a></p><h3><a href="contents.html">Table Of Contents</a></h3>
<ul>
<li><a href="index.html">Home</a></li>
<li><a href="contents.html">Contents</a></li>
<li><a href="getting-started.html">Install</a></li>
<li><a href="example/index.html">Examples</a></li>
<li><a href="customize.html">Customize</a></li>
<li><a href="contact.html">Contact</a></li>
<li><a href="talks.html">Talks/Posts</a></li>
<li><a href="changelog.html">Changelog</a></li>
</ul>
<hr>
<ul>
<li><a class="reference internal" href="#">pytest-2.3: reasoning for fixture/funcarg evolution</a><ul>
<li><a class="reference internal" href="#shortcomings-of-the-previous-pytest-funcarg-mechanism">Shortcomings of the previous <code class="docutils literal"><span class="pre">pytest_funcarg__</span></code> mechanism</a></li>
<li><a class="reference internal" href="#direct-scoping-of-fixture-funcarg-factories">Direct scoping of fixture/funcarg factories</a></li>
<li><a class="reference internal" href="#direct-parametrization-of-funcarg-resource-factories">Direct parametrization of funcarg resource factories</a></li>
<li><a class="reference internal" href="#no-pytest-funcarg-prefix-when-using-fixture-decorator">No <code class="docutils literal"><span class="pre">pytest_funcarg__</span></code> prefix when using @fixture decorator</a></li>
<li><a class="reference internal" href="#solving-per-session-setup-autouse-fixtures">solving per-session setup / autouse fixtures</a></li>
<li><a class="reference internal" href="#funcargs-fixture-discovery-now-happens-at-collection-time">funcargs/fixture discovery now happens at collection time</a></li>
<li><a class="reference internal" href="#conclusion-and-compatibility-notes">Conclusion and compatibility notes</a></li>
</ul>
</li>
</ul>
<h3>Related Topics</h3>
<ul>
<li><a href="contents.html">Documentation overview</a><ul>
<li>Previous: <a href="talks.html" title="previous chapter">Talks and Tutorials</a></li>
<li>Next: <a href="announce/index.html" title="next chapter">Release announcements</a></li>
</ul></li>
</ul><h3>Useful Links</h3>
<ul>
<li><a href="index.html">The pytest Website</a></li>
<li><a href="contributing.html">Contribution Guide</a></li>
<li><a href="https://pypi.python.org/pypi/pytest">pytest @ PyPI</a></li>
<li><a href="https://github.com/pytest-dev/pytest/">pytest @ GitHub</a></li>
<li><a href="http://plugincompat.herokuapp.com/">3rd party plugins</a></li>
<li><a href="https://github.com/pytest-dev/pytest/issues">Issue Tracker</a></li>
<li><a href="http://pytest.org/latest/pytest.pdf">PDF Documentation</a>
</ul>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
© Copyright 2015, holger krekel and pytest-dev team.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
</div>
</body>
</html>
|