This file is indexed.

/usr/share/doc/python-gabbi-doc/html/loader.html is in python-gabbi-doc 1.40.0-0ubuntu1.

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
317
318
319
320
321
322
<!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>Loading and Running Tests &#8212; Gabbi  documentation</title>
    <link rel="stylesheet" href="_static/classic.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="_static/theme_override.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true,
        SOURCELINK_SUFFIX: '.txt'
      };
    </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="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Example Tests" href="example.html" />
    <link rel="prev" title="Test Format" href="format.html" /> 
  </head>
  <body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="example.html" title="Example Tests"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="format.html" title="Test Format"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">Gabbi  documentation</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="loading-and-running-tests">
<h1>Loading and Running Tests<a class="headerlink" href="#loading-and-running-tests" title="Permalink to this headline"></a></h1>
<p id="test-loaders">To run gabbi tests with a test harness they must be generated in
some fashion and then run. This is accomplished by a test loader.
Initially gabbi only supported those test harnesses that supported
the <code class="docutils literal"><span class="pre">load_tests</span></code> protocol in UnitTest. It now possible to also
build and run tests with <a class="reference external" href="http://pytest.org/">pytest</a> with some limitations described below.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">It is also possible to run gabbi tests from the command
line. See <a class="reference internal" href="runner.html"><span class="doc">YAML Runner</span></a>.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">By default gabbi will load YAML files using the <code class="docutils literal"><span class="pre">safe_load</span></code>
function. This means only basic YAML types are allowed in the
file. For most use cases this is fine. If you need custom types
(for example, to match NaN) it is possible to set the <code class="docutils literal"><span class="pre">safe_yaml</span></code>
parameter of <code class="xref py py-meth docutils literal"><span class="pre">build_tests()</span></code> to <code class="docutils literal"><span class="pre">False</span></code>.
If custom types are used, please keep in mind that this can limit
the portability of the YAML files to other contexts.</p>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p>If test are being run with a runner that supports
concurrency (such as <code class="docutils literal"><span class="pre">testrepository</span></code>) it is critical
that the test runner is informed of how to group the
tests into their respective suites. The usual way to do
this is to use a regular expression that groups based
on the name of the yaml files. For example, when using
<code class="docutils literal"><span class="pre">testrepository</span></code> the <code class="docutils literal"><span class="pre">.testr.conf</span></code> file needs an
entry similar to the following:</p>
<div class="last highlight-default"><div class="highlight"><pre><span></span><span class="n">group_regex</span><span class="o">=</span><span class="n">gabbi</span>\<span class="o">.</span><span class="n">suitemaker</span>\<span class="o">.</span><span class="p">(</span><span class="n">test_</span><span class="p">[</span><span class="o">^</span><span class="n">_</span><span class="p">]</span><span class="o">+</span><span class="n">_</span><span class="p">[</span><span class="o">^</span><span class="n">_</span><span class="p">]</span><span class="o">+</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="unittest-style-loader">
<h2>UnitTest Style Loader<a class="headerlink" href="#unittest-style-loader" title="Permalink to this headline"></a></h2>
<p>To run the tests with a <code class="docutils literal"><span class="pre">load_tests</span></code> style loader a test file containing
a <code class="docutils literal"><span class="pre">load_tests</span></code> method is required. That will look a bit like:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;A sample test module.&quot;&quot;&quot;</span>

<span class="c1"># For pathname munging</span>
<span class="kn">import</span> <span class="nn">os</span>

<span class="c1"># The module that build_tests comes from.</span>
<span class="kn">from</span> <span class="nn">gabbi</span> <span class="kn">import</span> <span class="n">driver</span>

<span class="c1"># We need access to the WSGI application that hosts our service</span>
<span class="kn">from</span> <span class="nn">myapp</span> <span class="kn">import</span> <span class="n">wsgiapp</span>


<span class="c1"># We&#39;re using fixtures in the YAML files, we need to know where to</span>
<span class="c1"># load them from.</span>
<span class="kn">from</span> <span class="nn">myapp.test</span> <span class="kn">import</span> <span class="n">fixtures</span>

<span class="c1"># By convention the YAML files are put in a directory named</span>
<span class="c1"># &quot;gabbits&quot; that is in the same directory as the Python test file.</span>
<span class="n">TESTS_DIR</span> <span class="o">=</span> <span class="s1">&#39;gabbits&#39;</span>


<span class="k">def</span> <span class="nf">load_tests</span><span class="p">(</span><span class="n">loader</span><span class="p">,</span> <span class="n">tests</span><span class="p">,</span> <span class="n">pattern</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;Provide a TestSuite to the discovery process.&quot;&quot;&quot;</span>
    <span class="n">test_dir</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">dirname</span><span class="p">(</span><span class="vm">__file__</span><span class="p">),</span> <span class="n">TESTS_DIR</span><span class="p">)</span>
    <span class="c1"># Pass &quot;require_ssl=True&quot; as an argument to force all tests</span>
    <span class="c1"># to use SSL in requests.</span>
    <span class="k">return</span> <span class="n">driver</span><span class="o">.</span><span class="n">build_tests</span><span class="p">(</span><span class="n">test_dir</span><span class="p">,</span> <span class="n">loader</span><span class="p">,</span>
                              <span class="n">intercept</span><span class="o">=</span><span class="n">wsgiapp</span><span class="o">.</span><span class="n">app</span><span class="p">,</span>
                              <span class="n">fixture_module</span><span class="o">=</span><span class="n">fixtures</span><span class="p">)</span>
</pre></div>
</div>
<p>For details on the arguments available when building tests see
<code class="xref py py-meth docutils literal"><span class="pre">build_tests()</span></code>.</p>
<p>Once the test loader has been created, it needs to be run. There are <em>many</em>
options. Which is appropriate depends very much on your environment. Here are
some examples using <code class="docutils literal"><span class="pre">unittest</span></code> or <code class="docutils literal"><span class="pre">testtools</span></code> that require minimal
knowledge to get started.</p>
<p>By file:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">testtools</span><span class="o">.</span><span class="n">run</span> <span class="o">-</span><span class="n">v</span> <span class="n">test</span><span class="o">/</span><span class="n">test_loader</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>By module:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">testttols</span><span class="o">.</span><span class="n">run</span> <span class="o">-</span><span class="n">v</span> <span class="n">test</span><span class="o">.</span><span class="n">test_loader</span>

<span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">unittest</span> <span class="o">-</span><span class="n">v</span> <span class="n">test</span><span class="o">.</span><span class="n">test_loader</span>
</pre></div>
</div>
<p>Using test discovery to locate all tests in a directory tree:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">testtools</span><span class="o">.</span><span class="n">run</span> <span class="n">discover</span>

<span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">unittest</span> <span class="n">discover</span> <span class="n">test</span>
</pre></div>
</div>
<p>See the <a class="reference external" href="https://github.com/cdent/gabbi">source distribution</a> and <a class="reference external" href="https://github.com/cdent/gabbi-demo">the tutorial repo</a> for more
advanced options, including using <code class="docutils literal"><span class="pre">testrepository</span></code> and
<code class="docutils literal"><span class="pre">subunit</span></code>.</p>
</div>
<div class="section" id="pytest">
<h2>pytest<a class="headerlink" href="#pytest" title="Permalink to this headline"></a></h2>
<p id="pytest-loader">Since pytest does not support the <code class="docutils literal"><span class="pre">load_tests</span></code> system, a different
way of generating tests is required. Two techniques are supported.</p>
<p>The original method (described below) used yield statements to
generate tests which pytest would collect. This style of tests is
deprecated as of <code class="docutils literal"><span class="pre">pytest&gt;=3.0</span></code> so a new style using pytest
fixtures has been developed.</p>
<div class="section" id="pytest-3-0">
<h3>pytest &gt;= 3.0<a class="headerlink" href="#pytest-3-0" title="Permalink to this headline"></a></h3>
<p>In the newer technique, a test file is created that uses the
<code class="docutils literal"><span class="pre">pytest_generate_tests</span></code> hook. Special care must be taken to always
import the <code class="docutils literal"><span class="pre">test_pytest</span></code> method which is the base test that the
pytest hook parametrizes to generate the tests from the YAML files.
Without the method, the hook will not be called and no tests generated.</p>
<p>Here is a simple example file:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;A sample pytest module for pytest &gt;= 3.0.&quot;&quot;&quot;</span>

<span class="c1"># For pathname munging</span>
<span class="kn">import</span> <span class="nn">os</span>

<span class="c1"># The module that py_test_generator comes from.</span>
<span class="kn">from</span> <span class="nn">gabbi</span> <span class="kn">import</span> <span class="n">driver</span>

<span class="c1"># We need test_pytest so that pytest test collection works properly.</span>
<span class="c1"># Without this, the pytest_generate_tests method below will not be</span>
<span class="c1"># called.</span>
<span class="kn">from</span> <span class="nn">gabbi.driver</span> <span class="kn">import</span> <span class="n">test_pytest</span>  <span class="c1"># noqa</span>

<span class="c1"># We need access to the WSGI application that hosts our service</span>
<span class="kn">from</span> <span class="nn">myapp</span> <span class="kn">import</span> <span class="n">wsgiapp</span>

<span class="c1"># We&#39;re using fixtures in the YAML files, we need to know where to</span>
<span class="c1"># load them from.</span>
<span class="kn">from</span> <span class="nn">myapp.test</span> <span class="kn">import</span> <span class="n">fixtures</span>

<span class="c1"># By convention the YAML files are put in a directory named</span>
<span class="c1"># &quot;gabbits&quot; that is in the same directory as the Python test file.</span>
<span class="n">TESTS_DIR</span> <span class="o">=</span> <span class="s1">&#39;gabbits&#39;</span>


<span class="k">def</span> <span class="nf">pytest_generate_tests</span><span class="p">(</span><span class="n">metafunc</span><span class="p">):</span>
    <span class="n">test_dir</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">dirname</span><span class="p">(</span><span class="vm">__file__</span><span class="p">),</span> <span class="n">TESTS_DIR</span><span class="p">)</span>
    <span class="n">driver</span><span class="o">.</span><span class="n">py_test_generator</span><span class="p">(</span>
        <span class="n">test_dir</span><span class="p">,</span> <span class="n">intercept</span><span class="o">=</span><span class="n">wsgiapp</span><span class="o">.</span><span class="n">app</span><span class="p">,</span>
        <span class="n">fixture_module</span><span class="o">=</span><span class="n">fixtures</span><span class="p">,</span> <span class="n">metafunc</span><span class="o">=</span><span class="n">metafunc</span><span class="p">)</span>
</pre></div>
</div>
<p>This can then be run with the usual pytest commands. For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">py</span><span class="o">.</span><span class="n">test</span> <span class="o">-</span><span class="n">svx</span> <span class="n">pytest3</span><span class="o">.</span><span class="mi">0</span><span class="o">-</span><span class="n">example</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
</div>
<div class="section" id="id1">
<h3>pytest &lt; 3.0<a class="headerlink" href="#id1" title="Permalink to this headline"></a></h3>
<p>When using the older technique, test file must be created
that calls <code class="xref py py-meth docutils literal"><span class="pre">py_test_generator()</span></code> and yields the
generated tests. That will look a bit like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;A sample pytest module.&quot;&quot;&quot;</span>

<span class="c1"># For pathname munging</span>
<span class="kn">import</span> <span class="nn">os</span>

<span class="c1"># The module that build_tests comes from.</span>
<span class="kn">from</span> <span class="nn">gabbi</span> <span class="kn">import</span> <span class="n">driver</span>

<span class="c1"># We need access to the WSGI application that hosts our service</span>
<span class="kn">from</span> <span class="nn">myapp</span> <span class="kn">import</span> <span class="n">wsgiapp</span>

<span class="c1"># We&#39;re using fixtures in the YAML files, we need to know where to</span>
<span class="c1"># load them from.</span>
<span class="kn">from</span> <span class="nn">myapp.test</span> <span class="kn">import</span> <span class="n">fixtures</span>

<span class="c1"># By convention the YAML files are put in a directory named</span>
<span class="c1"># &quot;gabbits&quot; that is in the same directory as the Python test file.</span>
<span class="n">TESTS_DIR</span> <span class="o">=</span> <span class="s1">&#39;gabbits&#39;</span>


<span class="k">def</span> <span class="nf">test_gabbits</span><span class="p">():</span>
    <span class="n">test_dir</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">dirname</span><span class="p">(</span><span class="vm">__file__</span><span class="p">),</span> <span class="n">TESTS_DIR</span><span class="p">)</span>
    <span class="c1"># Pass &quot;require_ssl=True&quot; as an argument to force all tests</span>
    <span class="c1"># to use SSL in requests.</span>
    <span class="n">test_generator</span> <span class="o">=</span> <span class="n">driver</span><span class="o">.</span><span class="n">py_test_generator</span><span class="p">(</span>
        <span class="n">test_dir</span><span class="p">,</span> <span class="n">intercept</span><span class="o">=</span><span class="n">wsgiapp</span><span class="o">.</span><span class="n">app</span><span class="p">,</span>
        <span class="n">fixture_module</span><span class="o">=</span><span class="n">fixtures</span><span class="p">)</span>

    <span class="k">for</span> <span class="n">test</span> <span class="ow">in</span> <span class="n">test_generator</span><span class="p">:</span>
        <span class="k">yield</span> <span class="n">test</span>
</pre></div>
</div>
<p>This can then be run with the usual pytest commands. For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">py</span><span class="o">.</span><span class="n">test</span> <span class="o">-</span><span class="n">svx</span> <span class="n">pytest</span><span class="o">-</span><span class="n">example</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>The older technique will continue to work with all versions of
<code class="docutils literal"><span class="pre">pytest&lt;4.0</span></code> but <code class="docutils literal"><span class="pre">&gt;=3.0</span></code> will produce warnings. If you want to
use the older technique but not see the warnings add
<code class="docutils literal"><span class="pre">--disable-pytest-warnings</span></code> parameter to the invocation of
<code class="docutils literal"><span class="pre">py.test</span></code>.</p>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Loading and Running Tests</a><ul>
<li><a class="reference internal" href="#unittest-style-loader">UnitTest Style Loader</a></li>
<li><a class="reference internal" href="#pytest">pytest</a><ul>
<li><a class="reference internal" href="#pytest-3-0">pytest &gt;= 3.0</a></li>
<li><a class="reference internal" href="#id1">pytest &lt; 3.0</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="format.html"
                        title="previous chapter">Test Format</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="example.html"
                        title="next chapter">Example Tests</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="_sources/loader.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <div><input type="text" name="q" /></div>
      <div><input type="submit" value="Go" /></div>
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="example.html" title="Example Tests"
             >next</a> |</li>
        <li class="right" >
          <a href="format.html" title="Test Format"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">Gabbi  documentation</a> &#187;</li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.7.
    </div>
  </body>
</html>