levovix
/
Nim
mirror of https://github.com/nim-lang/Nim


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348
							<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--  This file is generated by Nim. -->
<html xmlns="https://www.w3.org/1999/xhtml" xml:lang="en" lang="en" data-theme="auto">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Testament</title>

<!-- Google fonts -->
<link href='https://fonts.googleapis.com/css?family=Lato:400,600,900' rel='stylesheet' type='text/css'/>
<link href='https://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>

<!-- Favicon -->
<link rel="shortcut icon" href="data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAUAAAAF////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAIAAABbAAAAlQAAAKIAAACbAAAAmwAAAKIAAACVAAAAWwAAAAL///8A////AP///wD///8A////AAAAABQAAADAAAAAYwAAAA3///8A////AP///wD///8AAAAADQAAAGMAAADAAAAAFP///wD///8A////AP///wAAAACdAAAAOv///wD///8A////AP///wD///8A////AP///wD///8AAAAAOgAAAJ3///8A////AP///wAAAAAnAAAAcP///wAAAAAoAAAASv///wD///8A////AP///wAAAABKAAAAKP///wAAAABwAAAAJ////wD///8AAAAAgQAAABwAAACIAAAAkAAAAJMAAACtAAAAFQAAABUAAACtAAAAkwAAAJAAAACIAAAAHAAAAIH///8A////AAAAAKQAAACrAAAAaP///wD///8AAAAARQAAANIAAADSAAAARf///wD///8AAAAAaAAAAKsAAACk////AAAAADMAAACcAAAAnQAAABj///8A////AP///wAAAAAYAAAAGP///wD///8A////AAAAABgAAACdAAAAnAAAADMAAAB1AAAAwwAAAP8AAADpAAAAsQAAAE4AAAAb////AP///wAAAAAbAAAATgAAALEAAADpAAAA/wAAAMMAAAB1AAAAtwAAAOkAAAD/AAAA/wAAAP8AAADvAAAA3gAAAN4AAADeAAAA3gAAAO8AAAD/AAAA/wAAAP8AAADpAAAAtwAAAGUAAAA/AAAA3wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAADfAAAAPwAAAGX///8A////AAAAAEgAAADtAAAAvwAAAL0AAADGAAAA7wAAAO8AAADGAAAAvQAAAL8AAADtAAAASP///wD///8A////AP///wD///8AAAAAO////wD///8A////AAAAAIcAAACH////AP///wD///8AAAAAO////wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A//8AAP//AAD4HwAA7/cAAN/7AAD//wAAoYUAAJ55AACf+QAAh+EAAAAAAADAAwAA4AcAAP5/AAD//wAA//8AAA=="/>
<link rel="icon" type="image/png" sizes="32x32" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4QQQEwksSS9ZWwAAAk1JREFUWMPtll2ITVEUx39nn/O7Y5qR8f05wtCUUr6ZIS++8pEnkZInPImneaCQ5METNdOkeFBKUhMPRIkHKfEuUZSUlGlKPN2TrgfncpvmnntnmlEyq1Z7t89/rf9a6+y99oZxGZf/XeIq61EdtgKXgdXA0xrYAvBjOIF1AI9zvjcC74BSpndrJPkBWDScTF8Aa4E3wDlgHbASaANmVqlcCnwHvgDvgVfAJ+AikAAvgfVZwLnSVZHZaOuKoQi3ZOMi4NkYkpe1p4J7A8BpYAD49hfIy/oqG0+hLomiKP2L5L+1ubn5115S+3OAn4EnwBlgMzCjyt6ZAnQCJ4A7wOs88iRJHvw50HoujuPBoCKwHWiosy8MdfZnAdcHk8dxXFJ3VQbQlCTJvRBCGdRbD4M6uc5glpY3eAihpN5S5w12diSEcCCEcKUO4ljdr15T76ur1FDDLIQQ3qv71EdDOe3Kxj3leRXyk+pxdWnFWod6Wt2bY3de3aSuUHcPBVimHs7mK9WrmeOF6lR1o9qnzskh2ar2qm1qizpfXaPeVGdlmGN5pb09qMxz1Xb1kLqgzn1RyH7JUXW52lr5e/Kqi9qpto7V1atuUzfnARrV7jEib1T76gG2qxdGmXyiekkt1GswPTtek0aBfJp6YySGBfWg2tPQ0FAYgf1stUfdmdcjarbYJEniKIq6gY/Aw+zWHAC+p2labGpqiorFYgGYCEzN7oQdQClN07O1/EfDyGgC0ALMBdYAi4FyK+4H3gLPsxfR1zRNi+NP7nH5J+QntnXe5B5mpfQAAAAASUVORK5CYII=">

<!-- CSS -->
<link rel="stylesheet" type="text/css" href="nimdoc.out.css?v=2.3.1">

<!-- JS -->
<script type="text/javascript" src="dochack.js?v=2.3.1"></script>
</head>
<body>
  <div class="document" id="documentId">
    <div class="container">
      <h1 class="title">Testament</h1>
      <div class="row">
  <div class="three columns">
    <div class="theme-select-wrapper">
      <label for="theme-select">Theme:&nbsp;</label>
      <select id="theme-select" onchange="setTheme(this.value)">
        <option value="auto">🌗 Match OS</option>
        <option value="dark">🌑 Dark</option>
        <option value="light">🌕 Light</option>
      </select>
    </div>
    <div id="global-links">
      <ul class="simple-boot">
        <li><a href="manual.html">Manual</a></li>
        <li><a href="lib.html">Standard library</a></li>
        <li> <a id="indexLink" href="theindex.html">Index</a></li>
        <li><a href="compiler/theindex.html">Compiler docs</a></li>
        <li><a href="https://nim-lang.github.io/fusion/theindex.html">Fusion docs</a></li>
        <li><a href="https://nim-lang.github.io/Nim/">devel</a>, <a href="https://nim-lang.org/documentation.html">stable</a></li>
      </ul>
    </div>
    <div id="searchInputDiv">
      Search: <input type="search" id="searchInput"
        oninput="search()" />
    </div>
    <div class="search-groupby">
  Group by:
  <select onchange="groupBy(this.value)">
    <option value="section">Section</option>
    <option value="type">Type</option>
  </select>
</div>

    <ul class="simple simple-toc" id="toc-list">
  <li><a class="reference" id="test-files-location_toc" href="#test-files-location">Test files location</a></li>
<li><a class="reference" id="commands_toc" href="#commands">Commands</a></li>
<li><a class="reference" id="options_toc" href="#options">Options</a></li>
<li><a class="reference" id="running-a-single-test_toc" href="#running-a-single-test">Running a single test</a></li>
<li><a class="reference" id="running-all-tests-from-a-directory_toc" href="#running-all-tests-from-a-directory">Running all tests from a directory</a></li>
<li><a class="reference" id="html-reports_toc" href="#html-reports">HTML Reports</a></li>
<li><a class="reference" id="writing-unit-tests_toc" href="#writing-unit-tests">Writing Unit tests</a></li>
<ul class="simple"><li><a class="reference" id="writing-unit-tests-inline-hints-warnings-and-errors-notes_toc" href="#writing-unit-tests-inline-hints-warnings-and-errors-notes">Inline hints, warnings and errors (notes)</a></li>
<li><a class="reference" id="writing-unit-tests-output-message-variable-interpolation_toc" href="#writing-unit-tests-output-message-variable-interpolation">Output message variable interpolation</a></li>
<li><a class="reference" id="writing-unit-tests-cmd-variable-interpolation_toc" href="#writing-unit-tests-cmd-variable-interpolation">Cmd variable interpolation</a></li>
</ul><li><a class="reference" id="unit-test-examples_toc" href="#unit-test-examples">Unit test Examples</a></li>

</ul>

  </div>
  <div class="nine columns" id="content">
    <a href="https://github.com/nim-lang/Nim/tree/devel/doc/testament.md#L1" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
<a href="https://github.com/nim-lang/Nim/edit/devel/doc/testament.md#L1" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;

    <div id="tocRoot"></div>
    
    <p class="module-desc"><p>Testament is an advanced automatic unittests runner for Nim tests, is used for the development of Nim itself, offers process isolation for your tests, it can generate statistics about test cases, supports multiple targets (C, C++, ObjectiveC, JavaScript, etc.), simulated <a class="reference external" href="https://en.wikipedia.org/wiki/Dry_run_(testing)">Dry-Runs</a>, has logging, can generate HTML reports, skip tests from a file, and more, so can be useful to run your tests, even the most complex ones.</p>

<h1><a class="toc-backref" id="test-files-location" href="#test-files-location">Test files location</a></h1><p>By default, Testament looks for test files on <tt class="docutils literal"><span class="pre">&quot;./tests/category/*.nim&quot;</span></tt>. You can overwrite this pattern glob using <tt class="docutils literal"><span class="pre option">pattern &lt;glob&gt;</span></tt>. The default working directory path can be changed using <tt class="docutils literal"><span class="pre option">--directory:&quot;folder/subfolder/&quot;</span></tt>.</p>
<p>Testament uses the <tt class="docutils literal"><span class="pre"><span class="program">nim</span></span></tt> compiler on <tt class="docutils literal"><span class="pre"><span class="Identifier">PATH</span></span></tt>. You can change that using <tt class="docutils literal"><span class="pre option">--nim:&quot;folder/subfolder/nim&quot;</span></tt>. Running JavaScript tests with <tt class="docutils literal"><span class="pre option">--targets:&quot;js&quot;</span></tt> requires a working NodeJS on <tt class="docutils literal"><span class="pre"><span class="Identifier">PATH</span></span></tt>.</p>

<h1><a class="toc-backref" id="commands" href="#commands">Commands</a></h1><p>p|pat|pattern &lt;glob&gt;        run all the tests matching the given pattern all                         run all tests inside of category folders c|cat|category &lt;category&gt;   run all the tests of a certain category r|run &lt;test&gt;                run single test file html                        generate testresults.html from the database</p>

<h1><a class="toc-backref" id="options" href="#options">Options</a></h1><div class="option-list"><div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--print</span></tt></div><div class="option-list-description">print results to the console</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--verbose</span></tt></div><div class="option-list-description">print commands (compiling and running tests)</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--simulate</span></tt></div><div class="option-list-description">see what tests would be run but don't run them (for debugging)</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--failing</span></tt></div><div class="option-list-description">only show failing/ignored tests</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--targets:&quot;c cpp js objc&quot; run tests for specified targets (default: c)</span></tt></div><div class="option-list-description"></div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--nim:path</span></tt></div><div class="option-list-description">use a particular nim executable (default: $PATH/nim)</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--directory:dir</span></tt></div><div class="option-list-description">Change to directory dir before reading the tests or doing anything else.</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--colors:on|off</span></tt></div><div class="option-list-description">Turn messages coloring on|off.</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--backendLogging:on|off</span></tt></div><div class="option-list-description">Disable or enable backend logging. By default turned on.</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--megatest:on|off</span></tt></div><div class="option-list-description">Enable or disable megatest. Default is on.</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--valgrind:on|off</span></tt></div><div class="option-list-description">Enable or disable valgrind support. Default is on.</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--skipFrom:file</span></tt></div><div class="option-list-description">Read tests to skip from <tt class="docutils literal"><span class="pre"><span class="Identifier">file</span></span></tt> - one test per line, # comments ignored</div></div>
</div>
<h1><a class="toc-backref" id="running-a-single-test" href="#running-a-single-test">Running a single test</a></h1><p>This is a minimal example to understand the basics, not very useful for production, but easy to understand:</p>
<p><pre class="listing"><span class="Prompt">$ </span><span class="program">mkdir</span> <span class="option">-p</span> <span class="Identifier">tests/category</span>
<span class="Prompt">$ </span><span class="program">echo</span> <span class="option">&quot;assert 42 == 42&quot;</span> <span class="option">&gt;</span> <span class="Identifier">tests/category/test0.nim</span>
<span class="Prompt">$ </span><span class="program">testament</span> <span class="option">run</span> <span class="Identifier">tests/category/test0.nim</span>
<span class="ProgramOutput">PASS: tests/category/test0.nim c                           ( 0.2 sec)</span>
<span class="Prompt">$ </span><span class="program">testament</span> <span class="option">r</span> <span class="Identifier">tests/category/test0</span>
<span class="ProgramOutput">PASS: tests/category/test0.nim C                           ( 0.2 sec)</span></pre></p>

<h1><a class="toc-backref" id="running-all-tests-from-a-directory" href="#running-all-tests-from-a-directory">Running all tests from a directory</a></h1><p>This will run all tests in the top level tests/ directory. NOTE: these tests are skipped by <tt class="docutils literal"><span class="pre"><span class="Identifier">testament</span> <span class="Identifier">all</span></span></tt>.</p>
<p><pre class="listing"><span class="Prompt">$ </span><span class="program">testament</span> <span class="option">pattern</span> <span class="option">&quot;tests/*.nim&quot;</span></pre></p>
<p>To search for tests deeper in a directory, use</p>
<p><pre class="listing"><span class="Prompt">$ </span><span class="program">testament</span> <span class="option">pattern</span> <span class="option">&quot;tests/**/*.nim&quot;</span>    <span class="Comment"># one level deeper</span>
<span class="Prompt">$ </span><span class="program">testament</span> <span class="option">pattern</span> <span class="option">&quot;tests/**/**/*.nim&quot;</span> <span class="Comment"># two levels deeper</span></pre></p>

<h1><a class="toc-backref" id="html-reports" href="#html-reports">HTML Reports</a></h1><p>Generate HTML Reports <tt class="docutils literal"><span class="pre">testresults.html</span></tt> from unittests, you have to run at least 1 test <em>before</em> generating a report:</p>
<p><pre class="listing"><span class="Prompt">$ </span><span class="program">testament</span> <span class="option">html</span></pre></p>

<h1><a class="toc-backref" id="writing-unit-tests" href="#writing-unit-tests">Writing Unit tests</a></h1><p>Example &quot;template&quot; <strong>to edit</strong> and write a Testament unittest:</p>
<p><pre class="listing"><span class="Keyword">discard</span> <span class="LongStringLit">&quot;&quot;&quot;
  
  # What actions to expect completion on.
  # Options:
  #   &quot;compile&quot;: expect successful compilation
  #   &quot;run&quot;: expect successful compilation and execution
  #   &quot;reject&quot;: expect failed compilation. The &quot;reject&quot; action can catch
  #             {.error.} pragmas but not {.fatal.} pragmas because
  #             {.error.} calls are expected to originate from the test-file,
  #             and can explicitly be specified using the &quot;file&quot;, &quot;line&quot; and
  #             &quot;column&quot; options.
  #             {.fatal.} pragmas guarantee that compilation will be aborted.
  action: &quot;run&quot;
  
  # For testing failed compilations you can specify the expected origin of the
  # compilation error.
  # With the &quot;file&quot;, &quot;line&quot; and &quot;column&quot; options you can define the file,
  # line and column that a compilation-error should have originated from.
  # Use only with action: &quot;reject&quot; as it expects a failed compilation.
  # Requires errormsg or msg to be defined.
  # file: &quot;&quot;
  # line: &quot;&quot;
  # column: &quot;&quot;
  
  # The exit code that the test is expected to return. Typically, the default
  # value of 0 is fine. Note that if the test will be run by valgrind, then
  # the test will exit with either a code of 0 on success or 1 on failure.
  exitcode: 0
  
  # Provide an `output` string to assert that the test prints to standard out
  # exactly the expected string. Provide an `outputsub` string to assert that
  # the string given here is a substring of the standard out output of the
  # test (the output includes both the compiler and test execution output).
  output: &quot;&quot;
  outputsub: &quot;&quot;
  
  # Whether to sort the compiler output lines before comparing them to the
  # expected output.
  sortoutput: true
  
  # Provide a `nimout` string to assert that the compiler during compilation
  # prints the defined lines to the standard out.
  # The lines must match in order, but there may be more lines that appear
  # before, after, or in between them.
  nimout: '''
a very long,
multi-line
string'''
  
  # This is the Standard Input the test should take, if any.
  input: &quot;&quot;
  
  # Error message the test should print, if any.
  errormsg: &quot;&quot;
  
  # Can be run in batch mode, or not.
  batchable: true
  
  # Can be run Joined with other tests to run all together, or not.
  joinable: true
  
  # On Linux 64-bit machines, whether to use Valgrind to check for bad memory
  # accesses or memory leaks. On other architectures, the test will be run
  # as-is, without Valgrind.
  # Options:
  #   true: run the test with Valgrind
  #   false: run the without Valgrind
  #   &quot;leaks&quot;: run the test with Valgrind, but do not check for memory leaks
  valgrind: false   # Can use Valgrind to check for memory leaks, or not (Linux 64Bit only).
  
  # Checks that the specified piece of C-code is within the generated C-code.
  ccodecheck: &quot;'Assert error message'&quot;
  
  # Command the test should use to run. If left out or an empty string is
  # provided, the command is taken to be:
  # &quot;nim $target --hints:on -d:testing --nimblePath:build/deps/pkgs $options $file&quot;
  # Subject to variable interpolation.
  cmd: &quot;nim c -r $file&quot;
  
  # Maximum generated temporary intermediate code file size for the test.
  maxcodesize: 666
  
  # Timeout seconds to run the test. Fractional values are supported.
  timeout: 1.5
  
  # Targets to run the test into (c, cpp, objc, js). Defaults to c.
  targets: &quot;c js&quot;
  
  # flags with which to run the test, delimited by `;`
  matrix: &quot;; -d:release; -d:caseFoo -d:release&quot;
  
  # Conditions that will skip this test. Use of multiple &quot;disabled&quot; clauses
  # is permitted.
  disabled: &quot;bsd&quot;   # Can disable OSes...
  disabled: &quot;win&quot;
  disabled: &quot;32bit&quot; # ...or architectures
  disabled: &quot;i386&quot;
  disabled: &quot;azure&quot; # ...or pipeline runners
  disabled: true    # ...or can disable the test entirely

&quot;&quot;&quot;</span>
<span class="Identifier">assert</span> <span class="Identifier">true</span>
<span class="Identifier">assert</span> <span class="DecNumber">42</span> <span class="Operator">==</span> <span class="DecNumber">42</span><span class="Punctuation">,</span> <span class="StringLit">&quot;Assert error message&quot;</span></pre></p>
<ul class="simple"><li>As you can see the &quot;Spec&quot; is just a <tt class="docutils literal"><span class="pre"><span class="Keyword">discard</span> <span class="LongStringLit">&quot;&quot;&quot; &quot;&quot;&quot;</span></span></tt>.</li>
<li>Spec has sane defaults, so you don't need to provide them all, any simple assert will work just fine.</li>
<li>This is not the full spec of Testament, check <a class="reference external" href="https://github.com/nim-lang/Nim/blob/devel/testament/specs.nim#L317">the Testament Spec on GitHub, see parseSpec()</a>.</li>
<li>Nim itself uses Testament, so <a class="reference external" href=" https://github.com/nim-lang/Nim/tree/devel/tests">there are plenty of test examples</a>.</li>
<li>Has some built-in CI compatibility, like Azure Pipelines, etc.</li>
</ul>

<h2><a class="toc-backref" id="writing-unit-tests-inline-hints-warnings-and-errors-notes" href="#writing-unit-tests-inline-hints-warnings-and-errors-notes">Inline hints, warnings and errors (notes)</a></h2><p>Testing the line, column, kind and message of hints, warnings and errors can be written inline like so:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">warning</span><span class="Punctuation">:</span> <span class="StringLit">&quot;warning!!&quot;</span><span class="Punctuation">}</span> <span class="LongComment">#[tt.Warning
         ^ warning!! [User] ]#</span></pre></p>
<p>The opening <tt class="docutils literal"><span class="pre"><span class="LongComment">#[tt.</span></span></tt> marks the message line. The <tt class="docutils literal"><span class="pre"><span class="Operator">^</span></span></tt> marks the message column.</p>
<p>Inline messages can be combined with <tt class="docutils literal"><span class="pre"><span class="Identifier">nimout</span></span></tt> when <tt class="docutils literal"><span class="pre"><span class="Identifier">nimoutFull</span></span></tt> is false (default). This allows testing for expected messages from other modules:</p>
<p><pre class="listing"><span class="Keyword">discard</span> <span class="LongStringLit">&quot;&quot;&quot;
  nimout: &quot;config.nims(1, 1) Hint: some hint message [User]&quot;
&quot;&quot;&quot;</span>
<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">warning</span><span class="Punctuation">:</span> <span class="StringLit">&quot;warning!!&quot;</span><span class="Punctuation">}</span> <span class="LongComment">#[tt.Warning
         ^ warning!! [User] ]#</span></pre></p>
<p>Multiple messages for a line can be checked by delimiting messages with ';':</p>
<p><pre class="listing"><span class="Keyword">discard</span> <span class="LongStringLit">&quot;&quot;&quot;
  matrix: &quot;--errorMax:0 --styleCheck:error&quot;
&quot;&quot;&quot;</span>

<span class="Keyword">proc</span> <span class="Identifier">generic_proc</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">a_a</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="LongComment">#[tt.Error
     ^ 'generic_proc' should be: 'genericProc'; tt.Error
                      ^ 'a_a' should be: 'aA' ]#</span>
  <span class="Keyword">discard</span></pre></p>
<p>Use <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">errorMax</span><span class="Punctuation">:</span><span class="DecNumber">0</span></span></tt> in <tt class="docutils literal"><span class="pre"><span class="Identifier">matrix</span></span></tt>, or <tt class="docutils literal"><span class="pre"><span class="Identifier">cmd</span><span class="Punctuation">:</span> <span class="StringLit">&quot;nim check $file&quot;</span></span></tt> when testing for multiple 'Error' messages.</p>

<h2><a class="toc-backref" id="writing-unit-tests-output-message-variable-interpolation" href="#writing-unit-tests-output-message-variable-interpolation">Output message variable interpolation</a></h2><p><tt class="docutils literal"><span class="pre"><span class="Identifier">errormsg</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">nimout</span></span></tt>, and inline messages are subject to these variable interpolations:</p>
<ul class="simple"><li><tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Punctuation">{</span><span class="Operator">/</span><span class="Punctuation">}</span></span></tt> - platform's directory separator</li>
<li><tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Identifier">file</span></span></tt> - the filename (without directory) of the test</li>
</ul>
<p>All other <tt class="docutils literal"><span class="pre"><span class="Operator">$</span></span></tt> characters need escaped as <tt class="docutils literal"><span class="pre"><span class="Operator">$$</span></span></tt>.</p>

<h2><a class="toc-backref" id="writing-unit-tests-cmd-variable-interpolation" href="#writing-unit-tests-cmd-variable-interpolation">Cmd variable interpolation</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">cmd</span></span></tt> option is subject to these variable interpolations:</p>
<ul class="simple"><li><tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Identifier">target</span></span></tt> - the compilation target, e.g. <tt class="docutils literal"><span class="pre"><span class="Identifier">c</span></span></tt>.</li>
<li><tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Identifier">options</span></span></tt> - the options for the compiler.</li>
<li><tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Identifier">file</span></span></tt> - the file path of the test.</li>
<li><tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Identifier">filedir</span></span></tt> - the directory of the test file.</li>
</ul>
<pre class="listing"><span class="Keyword">discard</span> <span class="LongStringLit">&quot;&quot;&quot;
  cmd: &quot;nim $target --nimblePath:./nimbleDir/simplePkgs $options $file&quot;
&quot;&quot;&quot;</span></pre><p>All other <tt class="docutils literal"><span class="pre"><span class="Operator">$</span></span></tt> characters need escaped as <tt class="docutils literal"><span class="pre"><span class="Operator">$$</span></span></tt>.</p>

<h1><a class="toc-backref" id="unit-test-examples" href="#unit-test-examples">Unit test Examples</a></h1><p>Expected to fail:</p>
<p><pre class="listing"><span class="Keyword">discard</span> <span class="LongStringLit">&quot;&quot;&quot;
  errormsg: &quot;undeclared identifier: 'not_defined'&quot;
&quot;&quot;&quot;</span>
<span class="Identifier">assert</span> <span class="Identifier">not_defined</span> <span class="Operator">==</span> <span class="StringLit">&quot;not_defined&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;not_defined is not defined&quot;</span></pre></p>
<p>Expected to fail with error thrown from another file:</p>
<p><pre class="listing"><span class="Comment"># test.nim</span>
<span class="Keyword">discard</span> <span class="LongStringLit">&quot;&quot;&quot;
  action: &quot;reject&quot;
  errorMsg: &quot;I break&quot;
  file: &quot;breakPragma.nim&quot;
&quot;&quot;&quot;</span>
<span class="Keyword">import</span> <span class="Operator">./</span><span class="Identifier">breakPragma</span>

<span class="Keyword">proc</span> <span class="Identifier">x</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">justDo</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">discard</span>

<span class="Comment"># breakPragma.nim</span>
<span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">macros</span>

<span class="Keyword">macro</span> <span class="Identifier">justDo</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">procDef</span><span class="Punctuation">:</span> <span class="Identifier">typed</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span> <span class="Operator">=</span>
  <span class="Identifier">error</span><span class="Punctuation">(</span><span class="StringLit">&quot;I break&quot;</span><span class="Punctuation">)</span>
  <span class="Keyword">return</span> <span class="Identifier">procDef</span></pre></p>
<p>Expecting generated C to contain a given piece of code:</p>
<p><pre class="listing"><span class="Keyword">discard</span> <span class="LongStringLit">&quot;&quot;&quot;
  # Checks that the string &quot;Assert error message&quot; is in the generated
  # C code.
  ccodecheck: &quot;'Assert error message'&quot;
&quot;&quot;&quot;</span>
<span class="Identifier">assert</span> <span class="DecNumber">42</span> <span class="Operator">==</span> <span class="DecNumber">42</span><span class="Punctuation">,</span> <span class="StringLit">&quot;Assert error message&quot;</span></pre></p>
<p>Non-Zero exit code:</p>
<p><pre class="listing"><span class="Keyword">discard</span> <span class="LongStringLit">&quot;&quot;&quot;
  exitcode: 1
&quot;&quot;&quot;</span>
<span class="Identifier">quit</span> <span class="StringLit">&quot;Non-Zero exit code&quot;</span><span class="Punctuation">,</span> <span class="DecNumber">1</span></pre></p>
<p>Standard output checking:</p>
<p><pre class="listing"><span class="Keyword">discard</span> <span class="LongStringLit">&quot;&quot;&quot;
  
  output: '''
0
1
2
3
4
5
'''

&quot;&quot;&quot;</span>
<span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.</span><span class="DecNumber">5</span><span class="Punctuation">:</span> <span class="Identifier">echo</span> <span class="Identifier">i</span></pre></p>
<p>JavaScript tests:</p>
<p><pre class="listing"><span class="Keyword">discard</span> <span class="LongStringLit">&quot;&quot;&quot;
  targets: &quot;js&quot;
&quot;&quot;&quot;</span>
<span class="Keyword">when</span> <span class="Identifier">defined</span><span class="Punctuation">(</span><span class="Identifier">js</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">jsconsole</span>
  <span class="Identifier">console</span><span class="Operator">.</span><span class="Identifier">log</span><span class="Punctuation">(</span><span class="StringLit">&quot;My Frontend Project&quot;</span><span class="Punctuation">)</span></pre></p>
<p>Compile-time tests:</p>
<p><pre class="listing"><span class="Keyword">discard</span> <span class="LongStringLit">&quot;&quot;&quot;
  action: &quot;compile&quot;
&quot;&quot;&quot;</span>
<span class="Keyword">static</span><span class="Punctuation">:</span> <span class="Identifier">assert</span> <span class="DecNumber">9</span> <span class="Operator">==</span> <span class="DecNumber">9</span><span class="Punctuation">,</span> <span class="StringLit">&quot;Compile time assert&quot;</span></pre></p>
<p>Tests without Spec:</p>
<p><pre class="listing"><span class="Identifier">assert</span> <span class="DecNumber">1</span> <span class="Operator">==</span> <span class="DecNumber">1</span></pre></p>
<p>See also:</p>
<ul class="simple"><li><a class="reference external" href="unittest.html">Unittest</a></li>
</ul>
</p>
    
  </div>
</div>

      <div class="twelve-columns footer">
        <span class="nim-sprite"></span>
        <br>
        <small style="color: var(--hint);">Made with Nim. Generated: 2024-12-25 13:27:24 UTC</small>
      </div>
    </div>
  </div>
      <script defer data-domain="nim-lang.org" src="https://plausible.io/js/plausible.js"></script>
    
</body>
</html>