File: skipping.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 (470 lines) | stat: -rw-r--r-- 17,017 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>Skipping tests</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">Skipping tests</h1>



<p>Some times you have tests that you don’t want to run in certain
circumstances. This vignette describes how to <strong>skip</strong>
tests to avoid execution in undesired environments. Skipping is a
relatively advanced topic because in most cases you want all your tests
to run everywhere. The most common exceptions are:</p>
<ul>
<li><p>You’re testing a web service that occasionally fails, and you
don’t want to run the tests on CRAN. Or maybe the API requires
authentication, and you can only run the tests when you’ve <a href="https://gargle.r-lib.org/articles/articles/managing-tokens-securely.html">securely
distributed</a> some secrets.</p></li>
<li><p>You’re relying on features that not all operating systems
possess, and want to make sure your code doesn’t run on a platform where
it doesn’t work. This platform tends to be Windows, since amongst other
things, it lacks full utf8 support.</p></li>
<li><p>You’re writing your tests for multiple versions of R or multiple
versions of a dependency and you want to skip when a feature isn’t
available. You generally don’t need to skip tests if a suggested package
is not installed. This is only needed in exceptional circumstances,
e.g. when a package is not available on some operating system.</p></li>
</ul>
<div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1" tabindex="-1"></a><span class="fu">library</span>(testthat)</span></code></pre></div>
<div id="basics" class="section level2">
<h2>Basics</h2>
<p>testthat comes with a variety of helpers for the most common
situations:</p>
<ul>
<li><p><code>skip_on_cran()</code> skips tests on CRAN. This is useful
for slow tests and tests that occasionally fail for reasons outside of
your control.</p></li>
<li><p><code>skip_on_os()</code> allows you to skip tests on a specific
operating system. Generally, you should strive to avoid this as much as
possible (so your code works the same on all platforms), but sometimes
it’s just not possible.</p></li>
<li><p><code>skip_on_ci()</code> skips tests on most continuous
integration platforms (e.g. GitHub Actions, Travis, Appveyor).</p></li>
</ul>
<p>You can also easily implement your own using either
<code>skip_if()</code> or <code>skip_if_not()</code>, which both take an
expression that should yield a single <code>TRUE</code> or
<code>FALSE</code>.</p>
<p>All reporters show which tests as skipped. As of testthat 3.0.0,
ProgressReporter (used interactively) and CheckReporter (used inside of
<code>R CMD check</code>) also display a summary of skips across all
tests. It looks something like this:</p>
<pre><code>── Skipped tests  ───────────────────────────────────────────────────────
● No token (3)
● On CRAN (1)</code></pre>
<p>You should keep an on eye this when developing interactively to make
sure that you’re not accidentally skipping the wrong things.</p>
</div>
<div id="helpers" class="section level2">
<h2>Helpers</h2>
<p>If you find yourself using the same
<code>skip_if()</code>/<code>skip_if_not()</code> expression across
multiple tests, it’s a good idea to create a helper function. This
function should start with <code>skip_</code> and live in a
<code>test/helper-{something}.R</code> file:</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb3-1"><a href="#cb3-1" tabindex="-1"></a>skip_if_dangerous <span class="ot">&lt;-</span> <span class="cf">function</span>() {</span>
<span id="cb3-2"><a href="#cb3-2" tabindex="-1"></a>  <span class="cf">if</span> (<span class="sc">!</span><span class="fu">identical</span>(<span class="fu">Sys.getenv</span>(<span class="st">&quot;DANGER&quot;</span>), <span class="st">&quot;&quot;</span>)) {</span>
<span id="cb3-3"><a href="#cb3-3" tabindex="-1"></a>    <span class="fu">skip</span>(<span class="st">&quot;Not run in dangerous environments.&quot;</span>)</span>
<span id="cb3-4"><a href="#cb3-4" tabindex="-1"></a>  } <span class="cf">else</span> {</span>
<span id="cb3-5"><a href="#cb3-5" tabindex="-1"></a>    <span class="fu">invisible</span>()</span>
<span id="cb3-6"><a href="#cb3-6" tabindex="-1"></a>  }</span>
<span id="cb3-7"><a href="#cb3-7" tabindex="-1"></a>}</span></code></pre></div>
</div>
<div id="embedding-skip-in-package-functions" class="section level2">
<h2>Embedding <code>skip()</code> in package functions</h2>
<p>Another useful technique that can sometimes be useful is to build a
<code>skip()</code> directly into a package function. For example take a
look at <a href="https://github.com/r-lib/pkgdown/blob/v2.0.7/R/markdown.R#L95-L106"><code>pkgdown:::convert_markdown_to_html()</code></a>,
which absolutely, positively cannot work if the Pandoc tool is
unavailable:</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb4-1"><a href="#cb4-1" tabindex="-1"></a>convert_markdown_to_html <span class="ot">&lt;-</span> <span class="cf">function</span>(in_path, out_path, ...) {</span>
<span id="cb4-2"><a href="#cb4-2" tabindex="-1"></a>  <span class="cf">if</span> (rmarkdown<span class="sc">::</span><span class="fu">pandoc_available</span>(<span class="st">&quot;2.0&quot;</span>)) {</span>
<span id="cb4-3"><a href="#cb4-3" tabindex="-1"></a>    from <span class="ot">&lt;-</span> <span class="st">&quot;markdown+gfm_auto_identifiers-citations+emoji+autolink_bare_uris&quot;</span></span>
<span id="cb4-4"><a href="#cb4-4" tabindex="-1"></a>  } <span class="cf">else</span> <span class="cf">if</span> (rmarkdown<span class="sc">::</span><span class="fu">pandoc_available</span>(<span class="st">&quot;1.12.3&quot;</span>)) {</span>
<span id="cb4-5"><a href="#cb4-5" tabindex="-1"></a>    from <span class="ot">&lt;-</span> <span class="st">&quot;markdown_github-hard_line_breaks+tex_math_dollars+tex_math_single_backslash+header_attributes&quot;</span></span>
<span id="cb4-6"><a href="#cb4-6" tabindex="-1"></a>  } <span class="cf">else</span> {</span>
<span id="cb4-7"><a href="#cb4-7" tabindex="-1"></a>    <span class="cf">if</span> (<span class="fu">is_testing</span>()) {</span>
<span id="cb4-8"><a href="#cb4-8" tabindex="-1"></a>      testthat<span class="sc">::</span><span class="fu">skip</span>(<span class="st">&quot;Pandoc not available&quot;</span>)</span>
<span id="cb4-9"><a href="#cb4-9" tabindex="-1"></a>    } <span class="cf">else</span> {</span>
<span id="cb4-10"><a href="#cb4-10" tabindex="-1"></a>      <span class="fu">abort</span>(<span class="st">&quot;Pandoc not available&quot;</span>)</span>
<span id="cb4-11"><a href="#cb4-11" tabindex="-1"></a>    }</span>
<span id="cb4-12"><a href="#cb4-12" tabindex="-1"></a>  }</span>
<span id="cb4-13"><a href="#cb4-13" tabindex="-1"></a>  </span>
<span id="cb4-14"><a href="#cb4-14" tabindex="-1"></a>  ...</span>
<span id="cb4-15"><a href="#cb4-15" tabindex="-1"></a>}</span></code></pre></div>
<p>If Pandoc is not available when
<code>convert_markdown_to_html()</code> executes, it throws an error
<em>unless</em> it appears to be part of a test run, in which case the
test is skipped. This is an alternative to implementing a custom
skipper, e.g. <code>skip_if_no_pandoc()</code>, and inserting it into
many of pkgdown’s tests.</p>
<p>We don’t want pkgdown to have a runtime dependency on testthat, so
pkgdown includes a copy of <code>testthat::is_testing()</code>:</p>
<div class="sourceCode" id="cb5"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb5-1"><a href="#cb5-1" tabindex="-1"></a>is_testing <span class="ot">&lt;-</span> <span class="cf">function</span>() {</span>
<span id="cb5-2"><a href="#cb5-2" tabindex="-1"></a>  <span class="fu">identical</span>(<span class="fu">Sys.getenv</span>(<span class="st">&quot;TESTTHAT&quot;</span>), <span class="st">&quot;true&quot;</span>)</span>
<span id="cb5-3"><a href="#cb5-3" tabindex="-1"></a>}</span></code></pre></div>
<p>It might look like the code appears to still have a runtime
dependency on testthat, because of the call to
<code>testthat::skip()</code>. But <code>testthat::skip()</code> is only
executed during a test run, which implies that testthat is
installed.</p>
<p>We have mixed feelings about this approach. On the one hand, it feels
elegant and concise, and it absolutely guarantees that you’ll never miss
a needed skip in one of your tests. On the other hand, it mixes code and
tests in an unusual way, and when you’re focused on the tests, it’s easy
to miss the fact that a package function contains a
<code>skip()</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>