File: special-files.html

package info (click to toggle)
r-cran-testthat 3.2.3-1
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 3,452 kB
sloc: cpp: 9,261; ansic: 37; sh: 14; makefile: 5
file content (460 lines) | stat: -rw-r--r-- 14,713 bytes
<!DOCTYPE html>

<html>

<head>

<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta http-equiv="X-UA-Compatible" content="IE=EDGE" />

<meta name="viewport" content="width=device-width, initial-scale=1" />



<title>Special files</title>

<script>// Pandoc 2.9 adds attributes on both header and div. We remove the former (to
// be compatible with the behavior of Pandoc < 2.8).
document.addEventListener('DOMContentLoaded', function(e) {
  var hs = document.querySelectorAll("div.section[class*='level'] > :first-child");
  var i, h, a;
  for (i = 0; i < hs.length; i++) {
    h = hs[i];
    if (!/^h[1-6]$/i.test(h.tagName)) continue;  // it should be a header h1-h6
    a = h.attributes;
    while (a.length > 0) h.removeAttribute(a[0].name);
  }
});
</script>

<style type="text/css">
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
</style>



<style type="text/css">
code {
white-space: pre;
}
.sourceCode {
overflow: visible;
}
</style>
<style type="text/css" data-origin="pandoc">
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { display: inline-block; text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } 
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.at { color: #7d9029; } 
code span.bn { color: #40a070; } 
code span.bu { color: #008000; } 
code span.cf { color: #007020; font-weight: bold; } 
code span.ch { color: #4070a0; } 
code span.cn { color: #880000; } 
code span.co { color: #60a0b0; font-style: italic; } 
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.do { color: #ba2121; font-style: italic; } 
code span.dt { color: #902000; } 
code span.dv { color: #40a070; } 
code span.er { color: #ff0000; font-weight: bold; } 
code span.ex { } 
code span.fl { color: #40a070; } 
code span.fu { color: #06287e; } 
code span.im { color: #008000; font-weight: bold; } 
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.kw { color: #007020; font-weight: bold; } 
code span.op { color: #666666; } 
code span.ot { color: #007020; } 
code span.pp { color: #bc7a00; } 
code span.sc { color: #4070a0; } 
code span.ss { color: #bb6688; } 
code span.st { color: #4070a0; } 
code span.va { color: #19177c; } 
code span.vs { color: #4070a0; } 
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } 
</style>
<script>
// apply pandoc div.sourceCode style to pre.sourceCode instead
(function() {
  var sheets = document.styleSheets;
  for (var i = 0; i < sheets.length; i++) {
    if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue;
    try { var rules = sheets[i].cssRules; } catch (e) { continue; }
    var j = 0;
    while (j < rules.length) {
      var rule = rules[j];
      // check if there is a div.sourceCode rule
      if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") {
        j++;
        continue;
      }
      var style = rule.style.cssText;
      // check if color or background-color is set
      if (rule.style.color === '' && rule.style.backgroundColor === '') {
        j++;
        continue;
      }
      // replace div.sourceCode by a pre.sourceCode rule
      sheets[i].deleteRule(j);
      sheets[i].insertRule('pre.sourceCode{' + style + '}', j);
    }
  }
})();
</script>




<style type="text/css">body {
background-color: #fff;
margin: 1em auto;
max-width: 700px;
overflow: visible;
padding-left: 2em;
padding-right: 2em;
font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
font-size: 14px;
line-height: 1.35;
}
#TOC {
clear: both;
margin: 0 0 10px 10px;
padding: 4px;
width: 400px;
border: 1px solid #CCCCCC;
border-radius: 5px;
background-color: #f6f6f6;
font-size: 13px;
line-height: 1.3;
}
#TOC .toctitle {
font-weight: bold;
font-size: 15px;
margin-left: 5px;
}
#TOC ul {
padding-left: 40px;
margin-left: -1.5em;
margin-top: 5px;
margin-bottom: 5px;
}
#TOC ul ul {
margin-left: -2em;
}
#TOC li {
line-height: 16px;
}
table {
margin: 1em auto;
border-width: 1px;
border-color: #DDDDDD;
border-style: outset;
border-collapse: collapse;
}
table th {
border-width: 2px;
padding: 5px;
border-style: inset;
}
table td {
border-width: 1px;
border-style: inset;
line-height: 18px;
padding: 5px 5px;
}
table, table th, table td {
border-left-style: none;
border-right-style: none;
}
table thead, table tr.even {
background-color: #f7f7f7;
}
p {
margin: 0.5em 0;
}
blockquote {
background-color: #f6f6f6;
padding: 0.25em 0.75em;
}
hr {
border-style: solid;
border: none;
border-top: 1px solid #777;
margin: 28px 0;
}
dl {
margin-left: 0;
}
dl dd {
margin-bottom: 13px;
margin-left: 13px;
}
dl dt {
font-weight: bold;
}
ul {
margin-top: 0;
}
ul li {
list-style: circle outside;
}
ul ul {
margin-bottom: 0;
}
pre, code {
background-color: #f7f7f7;
border-radius: 3px;
color: #333;
white-space: pre-wrap; 
}
pre {
border-radius: 3px;
margin: 5px 0px 10px 0px;
padding: 10px;
}
pre:not([class]) {
background-color: #f7f7f7;
}
code {
font-family: Consolas, Monaco, 'Courier New', monospace;
font-size: 85%;
}
p > code, li > code {
padding: 2px 0px;
}
div.figure {
text-align: center;
}
img {
background-color: #FFFFFF;
padding: 2px;
border: 1px solid #DDDDDD;
border-radius: 3px;
border: 1px solid #CCCCCC;
margin: 0 5px;
}
h1 {
margin-top: 0;
font-size: 35px;
line-height: 40px;
}
h2 {
border-bottom: 4px solid #f7f7f7;
padding-top: 10px;
padding-bottom: 2px;
font-size: 145%;
}
h3 {
border-bottom: 2px solid #f7f7f7;
padding-top: 10px;
font-size: 120%;
}
h4 {
border-bottom: 1px solid #f7f7f7;
margin-left: 8px;
font-size: 105%;
}
h5, h6 {
border-bottom: 1px solid #ccc;
font-size: 105%;
}
a {
color: #0033dd;
text-decoration: none;
}
a:hover {
color: #6666ff; }
a:visited {
color: #800080; }
a:visited:hover {
color: #BB00BB; }
a[href^="http:"] {
text-decoration: underline; }
a[href^="https:"] {
text-decoration: underline; }

code > span.kw { color: #555; font-weight: bold; } 
code > span.dt { color: #902000; } 
code > span.dv { color: #40a070; } 
code > span.bn { color: #d14; } 
code > span.fl { color: #d14; } 
code > span.ch { color: #d14; } 
code > span.st { color: #d14; } 
code > span.co { color: #888888; font-style: italic; } 
code > span.ot { color: #007020; } 
code > span.al { color: #ff0000; font-weight: bold; } 
code > span.fu { color: #900; font-weight: bold; } 
code > span.er { color: #a61717; background-color: #e3d2d2; } 
</style>




</head>

<body>




<h1 class="title toc-ignore">Special files</h1>



<p>This vignette describes the various special files that testthat
understands: test, helper, setup/teardown, snapshot, and everything
else.</p>
<div id="test-files" class="section level2">
<h2>Test files</h2>
<p>These are the bread and butter of testthat. Test files live in
<code>tests/testthat/</code>, start with either <code>test-</code> or
<code>test_</code>, and end with <code>.r</code> or <code>.R</code>. We
recommend organising your test files so that there’s a one-to-one
correspondence between the files in <code>R/</code> and the files in
<code>tests/testthat/</code> so that (e.g.) <code>R/myfile.R</code> has
a matching <code>tests/testthat/test-myfile.R</code>. This
correspondence is maintained by functions like
<code>usethis::use_r()</code> and <code>usethis::use_test()</code> and
is taken advantage of by functions like
<code>devtools::test_active_file()</code> and
<code>devtools::test_coverage_active_file()</code>.</p>
<p>Test files are executed in alphabetical order, but you should strive
to avoid dependencies between test files. In principle, you should be
able to be run your test files in any order or even at the same
time.</p>
</div>
<div id="helper-files" class="section level2">
<h2>Helper files</h2>
<p>Helper files live in <code>tests/testthat/</code>, start with
<code>helper</code>, and end with <code>.r</code> or <code>.R</code>.
They are sourced by <code>devtools::load_all()</code> (so they’re
available interactively when developing your packages) and by
<code>test_check()</code> and friends (so that they’re available no
matter how your tests are executed).</p>
<p>Helper files are a useful place for functions that you’ve extracted
from repeated code in your tests, whether that be test fixtures
(<code>vignette(&quot;test-fixtures&quot;)</code>), custom expectations
(<code>vignette(&quot;custom-expectation&quot;)</code>), or skip helpers
(<code>vignette(&quot;skipping&quot;)</code>).</p>
</div>
<div id="setup-files" class="section level2">
<h2>Setup files</h2>
<p>Setup files live in <code>tests/testthat/</code>, start with
<code>setup</code>, and end with <code>.r</code> or <code>.R</code>.
Typically there is only one setup file which, by convention, is
<code>tests/testthat/setup.R</code>. Setup files are sourced by
<code>test_check()</code> and friends (so that they’re available no
matter how your tests are executed), but they are <em>not</em> sourced
by <code>devtools::load_all()</code>.</p>
<p>Setup files are good place to put truly global test setup that would
be impractical to build into every single test and that might be
tailored for test execution in non-interactive or remote environments.
Examples:</p>
<ul>
<li>Turning off behaviour aimed at an interactive user, such as
messaging or writing to the clipboard.</li>
<li>Setting up a cache folder.</li>
</ul>
<p>If any of your setup should be reversed after test execution (i.e. it
needs to be torn down), we recommend maintaining that teardown code
alongside the setup code, in <code>setup.R</code>, because this makes it
easier to ensure they stay in sync. The artificial environment
<code>teardown_env()</code> exists as a magical handle to use in
<code>withr::defer()</code> and <code>withr::local_*()</code>. A legacy
approach (which still works, but is no longer recommended) is to put
teardown code in <code>tests/testthat/teardown.R</code>.</p>
<p>Here’s a <code>setup.R</code> example from the reprex package, where
we turn off clipboard and HTML preview functionality during testing:</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1" tabindex="-1"></a>op <span class="ot">&lt;-</span> <span class="fu">options</span>(<span class="at">reprex.clipboard =</span> <span class="cn">FALSE</span>, <span class="at">reprex.html_preview =</span> <span class="cn">FALSE</span>)</span>
<span id="cb1-2"><a href="#cb1-2" tabindex="-1"></a></span>
<span id="cb1-3"><a href="#cb1-3" tabindex="-1"></a>withr<span class="sc">::</span><span class="fu">defer</span>(<span class="fu">options</span>(op), <span class="fu">teardown_env</span>())</span></code></pre></div>
<p>Since we are just modifying options here, we can be even more concise
and use the pre-built function <code>withr::local_options()</code> and
pass <code>teardown_env()</code> as the <code>.local_envir</code>:</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb2-1"><a href="#cb2-1" tabindex="-1"></a>withr<span class="sc">::</span><span class="fu">local_options</span>(</span>
<span id="cb2-2"><a href="#cb2-2" tabindex="-1"></a>  <span class="fu">list</span>(<span class="at">reprex.clipboard =</span> <span class="cn">FALSE</span>, <span class="at">reprex.html_preview =</span> <span class="cn">FALSE</span>),</span>
<span id="cb2-3"><a href="#cb2-3" tabindex="-1"></a>  <span class="at">.local_envir =</span> <span class="fu">teardown_env</span>()</span>
<span id="cb2-4"><a href="#cb2-4" tabindex="-1"></a>)</span></code></pre></div>
<div id="teardown-files" class="section level3">
<h3>Teardown files</h3>
<p>Teardown files live in <code>tests/testhat/</code>, start with
<code>teardown</code> and end with <code>.r</code> or <code>.R</code>.
They are executed after the tests are run, but we no longer recommend
using them as it’s easier to check that you clean up every mess that you
make if you interleave setup and tear down code as described above.</p>
</div>
</div>
<div id="snapshot-files" class="section level2">
<h2>Snapshot files</h2>
<p>Snapshot files live in <code>tests/testthat/_snaps/</code>. Snapshot
file are named automatically based on the name of the test file so that
<code>tests/testthat/test-one.R</code> will generated
<code>tests/testthat/_snaps/one.md</code>. Learn more about snapshot
tests in <code>vignette(&quot;snapshotting&quot;)</code>.</p>
</div>
<div id="other-files-and-folders" class="section level2">
<h2>Other files and folders</h2>
<p>Other files and folders in <code>tests/testthat/</code> are ignored
by testthat, making them a good place to store persistent test data.
Since the precise location of the <code>test/testthat/</code> directory
varies slightly depending on how you’re running the test, we recommend
creating paths to these files and directories using
<code>test_path()</code>.</p>
</div>



<!-- code folding -->


<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
  (function () {
    var script = document.createElement("script");
    script.type = "text/javascript";
    script.src  = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
    document.getElementsByTagName("head")[0].appendChild(script);
  })();
</script>

</body>
</html>