/usr/share/doc/racket/style/testing.html is in racket-doc 6.1-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 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><title>2 Testing</title><link rel="stylesheet" type="text/css" href="../scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-style.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../doc-site.css" title="default"/><script type="text/javascript" src="../scribble-common.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../doc-site.js"></script><script type="text/javascript" src="../local-redirect/local-redirect.js"></script><script type="text/javascript" src="../local-redirect/local-user-redirect.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="doc-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">▼</a></td><td></td><td><a href="index.html" class="tocviewlink" data-pltdoc="x">How to Program Racket</a></td></tr></table></div><div class="tocviewsublisttop" style="display: block;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="correct-maintain-speed.html" class="tocviewlink" data-pltdoc="x">Basic Facts of Life</a></td></tr><tr><td align="right">2 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Testing</a></td></tr><tr><td align="right">3 </td><td><a href="Units_of_Code.html" class="tocviewlink" data-pltdoc="x">Units of Code</a></td></tr><tr><td align="right">4 </td><td><a href="Choosing_the_Right_Construct.html" class="tocviewlink" data-pltdoc="x">Choosing the Right Construct</a></td></tr><tr><td align="right">5 </td><td><a href="Textual_Matters.html" class="tocviewlink" data-pltdoc="x">Textual Matters</a></td></tr><tr><td align="right">6 </td><td><a href="Language_and_Performance.html" class="tocviewlink" data-pltdoc="x">Language and Performance</a></td></tr><tr><td align="right">7 </td><td><a href="branch-and-commit.html" class="tocviewlink" data-pltdoc="x">Retiquette:<span class="mywbr"> </span> Branch and Commit</a></td></tr><tr><td align="right">8 </td><td><a href="Acknowledgment.html" class="tocviewlink" data-pltdoc="x">Acknowledgment</a></td></tr><tr><td align="right">9 </td><td><a href="Todo_List__Call_for_Contributions.html" class="tocviewlink" data-pltdoc="x">Todo List, Call for Contributions</a></td></tr></table></div></div><div class="tocviewlist"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_1");">►</a></td><td>2 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Testing</a></td></tr></table><div class="tocviewsublistbottom" style="display: none;" id="tocview_1"><table cellspacing="0" cellpadding="0"><tr><td align="right">2.1 </td><td><a href="#%28part._test-suite%29" class="tocviewlink" data-pltdoc="x">Test Suites</a></td></tr><tr><td align="right">2.2 </td><td><a href="#%28part._test-bang%29" class="tocviewlink" data-pltdoc="x">Always Test!</a></td></tr></table></div></div></div><div class="tocsub"><div class="tocsubtitle">On this page:</div><table class="tocsublist" cellspacing="0"><tr><td><span class="tocsublinknumber">2.1<tt> </tt></span><a href="#%28part._test-suite%29" class="tocsubseclink" data-pltdoc="x">Test Suites</a></td></tr><tr><td><span class="tocsublinknumber">2.2<tt> </tt></span><a href="#%28part._test-bang%29" class="tocsubseclink" data-pltdoc="x">Always Test!</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="navsettop"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.1", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.1");">top</a></span><span class="navright"> <a href="correct-maintain-speed.html" title="backward to "1 Basic Facts of Life"" data-pltdoc="x">← prev</a> <a href="index.html" title="up to "How to Program Racket"" data-pltdoc="x">up</a> <a href="Units_of_Code.html" title="forward to "3 Units of Code"" data-pltdoc="x">next →</a></span> </div><h3 x-source-module="(lib "scribblings/style/style.scrbl")" x-part-tag=""testing"">2<tt> </tt><a name="(part._testing)"></a>Testing</h3><h4 x-source-module="(lib "scribblings/style/style.scrbl")" x-part-tag=""test-suite"">2.1<tt> </tt><a name="(part._test-suite)"></a>Test Suites</h4><p>Most of our collections come with test suites. These tests suites tend to
live in <span class="stt">collects/tests/</span> in the PLT repository, though due to
historical reasons, a few collections come with their own local test
suites. If you add a new collection, create a new test suite in the
<span class="stt">tests</span> collection.</p><p>Run the test suites before you commit. To facilitate testing, we urge you
to add a <span class="stt">TESTME.txt</span> file to your collections. Ideally, you may also
wish to have a file in this directory that runs the basic tests. See the
<a href="https://github.com/plt/racket/tree/master/collects/2htdp/">2htdp</a>,
which is one of the collections with its own testing style. The file should
describe where the tests are located, how to run these tests, and what to
look for in terms of successes and failures. These files are necessary
because different collections have different needs for testing, and
testing evolved in many different ways in our history.</p><p><div class="SIntrapara">After you commit, watch for and read(!)
<a href="http://drdr.racket-lang.org/">DrDr</a>’s emails. Do <span style="font-style: italic">not</span>
ignore them. If you have tests that are known to fail and fixing this
requires a lot of work, consider splitting your test directory into two
parts: <span class="stt">success</span> and <span class="stt">failure</span>. The former is for tests that should
succeed now, and the latter is for tests that are currently expected to
fail. See the
<a href="https://github.com/plt/racket/tree/master/collects/tests/typed-scheme">Typed
Racket testing arrangement</a> for an example. When you create such
<span class="stt">failure</span> tests, you may wish to disable DrDr’s checking like this:
</div><div class="SIntrapara"><table cellspacing="0" cellpadding="0"><tr><td><p><span class="hspace"> </span><span class="stt">git prop set drdr:command-line "" <file> ...</span></p></td></tr></table></div><div class="SIntrapara">This is a Racket-specific <span class="stt">git</span> command.</div></p><h4 x-source-module="(lib "scribblings/style/style.scrbl")" x-part-tag=""test-bang"">2.2<tt> </tt><a name="(part._test-bang)"></a>Always Test!</h4><p>When you debug an existing piece of code, formulate a test case first. Put
it into the test suite for the component so the mistake will never be
accidentally re-introduced and add a note that points to the problem
report. Second, modify the code to fix the mistake. Do this second to be
sure you didn’t introduce a mistake in your tests; it is all too easy to
think you have fixed a mistake when in reality your new test just doesn’t
properly reveal the old mistake. Third, re-run the test suite to ensure
that the mistake is fixed and no existing tests fail.</p><p>If there is no test suite and you aren’t sure how to build one, then ask on
the developer mailing list. Perhaps people will explain why there isn’t
one or they will sketch how to create one. Please don’t ignore the
problem. If you cannot build a test suite, you have a few options:</p><p><div class="SIntrapara"><ol><li><p>Add functionality to the library to enable testing. Of course,
adding functionality means adding external documentation. Robby and
Matthew have done so for the GUI library, and there is now a large
automated test suite for DrRacket. So even GUI programs can come with
extended test suites.</p></li><li><p>Add an end-to-end test that may have to be verified by a human.
For example, it might be hard to test Slideshow, so you could create a
slide set and describe what it should look like so future maintainers to
verify when <span style="font-style: italic">they</span> make changes. Consider this the <span style="font-style: italic">last and
least desirable</span> option, however.</p></li></ol></div><div class="SIntrapara">The lack of tests for some collection will not disappear overnight. But if
we all contribute a little bit, we will eventually expand the test suites
to cover the entire code base, and future generations of maintainers will
be grateful.</div></p><div class="navsetbottom"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.1", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.1");">top</a></span><span class="navright"> <a href="correct-maintain-speed.html" title="backward to "1 Basic Facts of Life"" data-pltdoc="x">← prev</a> <a href="index.html" title="up to "How to Program Racket"" data-pltdoc="x">up</a> <a href="Units_of_Code.html" title="forward to "3 Units of Code"" data-pltdoc="x">next →</a></span> </div></div></div><div id="contextindicator"> </div></body></html>
|