siesta-lite/docs/guides/getting_started_nodejs/README.js

Stress-free JavaScript unit testing and functional testing tool, works in NodeJS and browsers

Ext.data.JsonP.getting_started_nodejs({"guide":"<h1 id='getting_started_nodejs-section-getting-started-with-siesta-in-node.js-environment'>Getting started with Siesta in Node.js environment</h1>\n<div class='toc'>\n<p><strong>Contents</strong></p>\n<ol>\n<li><a href='#!/guide/getting_started_nodejs-section-installation'>Installation</a></li>\n<li><a href='#!/guide/getting_started_nodejs-section-siesta-test-file'>Siesta test file</a></li>\n<li><a href='#!/guide/getting_started_nodejs-section-launching-the-test-'>Launching the test </a></li>\n<li><a href='#!/guide/getting_started_nodejs-section-siesta-node.js-project'>Siesta Node.js project</a></li>\n<li><a href='#!/guide/getting_started_nodejs-section-sandboxing'>Sandboxing</a></li>\n<li><a href='#!/guide/getting_started_nodejs-section-configuring-the-project'>Configuring the project</a></li>\n<li><a href='#!/guide/getting_started_nodejs-section-configuring-the-individual-test'>Configuring the individual test</a></li>\n<li><a href='#!/guide/getting_started_nodejs-section-command-line-arguments'>Command-line arguments</a></li>\n<li><a href='#!/guide/getting_started_nodejs-section-debugging-'>Debugging </a></li>\n<li><a href='#!/guide/getting_started_nodejs-section-using-ecma-modules.-'>Using Ecma modules. </a></li>\n<li><a href='#!/guide/getting_started_nodejs-section-using-typescript'>Using Typescript</a></li>\n<li><a href='#!/guide/getting_started_nodejs-section-code-coverage'>Code coverage</a></li>\n<li><a href='#!/guide/getting_started_nodejs-section-further-reading'>Further reading</a></li>\n<li><a href='#!/guide/getting_started_nodejs-section-buy-this-product'>Buy this product</a></li>\n<li><a href='#!/guide/getting_started_nodejs-section-support'>Support</a></li>\n<li><a href='#!/guide/getting_started_nodejs-section-see-also'>See also</a></li>\n<li><a href='#!/guide/getting_started_nodejs-section-attribution'>Attribution</a></li>\n<li><a href='#!/guide/getting_started_nodejs-section-copyright-and-license'>COPYRIGHT AND LICENSE</a></li>\n</ol>\n</div>\n\n<p>Siesta is a stress-free JavaScript unit and UI-testing tool. It is known that change of activity is a form of rest,\nso stop writing code, write some tests and have some rest! Your application will win from both.</p>\n\n<p>Siesta is very easy to learn and as your test suite grows and your requirements becomes more complex it still scales very well.</p>\n\n<p>Siesta is also cross-platform - the same tests can run in browsers and NodeJS, on Linux, MacOs and Windows\n(assuming of course they are written in a platform-independent manner). Headless browser modes are supported.</p>\n\n<p><p><img src=\"guides/getting_started_nodejs/images/demo.png\" alt=\"autogen\" width=\"1600\" height=\"1200\"></p></p>\n\n<p>In this guide, we assume a setup, pointed toward running tests in Node.js.</p>\n\n<p>For the setup, targeting browser environment, please refer to this guide <a href=\"#!/guide/getting_started_browser\">Getting started with Siesta in browser environment</a></p>\n\n<h2 id='getting_started_nodejs-section-installation'>Installation</h2>\n\n<p>Siesta Lite is published in Npm, so it can be installed with:</p>\n\n<pre><code>&gt; npm install siesta-lite --save-dev\n</code></pre>\n\n<p>Siesta Standard is distributed as plain archive file, you just unpack it in the preferred location.</p>\n\n<h2 id='getting_started_nodejs-section-siesta-test-file'>Siesta test file</h2>\n\n<p>Lets start by looking at the basic Siesta test (save it somewhere as <code>sample.t.js</code>) :</p>\n\n<pre><code class=\"javascript\">const path      = require('path')\n\nStartTest(t =&gt; {\n\n    t.it(\"Sanity\", t =&gt; {\n\n        t.ok(process, '`process` is here');\n\n        t.is(1, \"1\", \"Relaxed equality\")\n\n        t.exact(1, 1, \"Exact equality\")\n\n        t.is(1, t.anyNumberApprox(0.95, 0.1), \"Fuzzy equality\")\n\n        t.like(__filename, /010_sanity\\.t\\.js/, \"Location of the test file is as expected\")\n\n        t.throwsOk(\n            () =&gt; { vixie },\n            /vixie/,\n            \"Correct exception thrown\"\n        )\n    });\n})    \n</code></pre>\n\n<p>The test code is wrapped with <code>StartTest(t =&gt; { ... })</code> construct, which is required for compatibility with browser environment.\nThe function passed to it will receive an instance of the <a href=\"#!/api/Siesta.Test.NodeJS\" rel=\"Siesta.Test.NodeJS\" class=\"docClass\">Siesta.Test.NodeJS</a> class, as the 1st argument.</p>\n\n<p>Alternative wrapper form is supported:</p>\n\n<pre><code class=\"javascript\">describe('Test case name', t =&gt; {\n    t.it(\"Sanity\", t =&gt; {\n        ...\n    });\n})    \n</code></pre>\n\n<p>The instance of the test class has various <em>assertion</em> methods. An \"assertion\" is any statement about your code,\nwhich can be either truthy (we say \"assertion pass\") or false (assertion fail). It may have arbitrary meaning,\nranging from very simple like \"this variable is equal to that variable\" to complex and domain specific:\n\"this instance of EventEmitter will fire this event exactly N times during the following X milliseconds\".</p>\n\n<p>Siesta has many general-purpose assertions built-in and it also allows you to <a href=\"#!/guide/extending_test_class\">create your own assertions.</a></p>\n\n<p>In the example above we use the simplest possible assertion: <code>t.ok(value, description)</code>. It passes when the provided <code>value</code> is \"truthy\",\nlike : <code>true</code>, <code>1</code>, <code>{}</code> etc and fails otherwise. Each assertion also has an optional description which should contain\nan explanation of what's being asserted.</p>\n\n<p>We also used <code>throwsOk</code> assertion, which, accept a function, run it, and verify that it does throw exception, which serializes to the string,\nmatching a given <code>RegExp</code>. You've probably get the idea.</p>\n\n<p>To see the list of all <strong>generic</strong> assertions, supported by Siesta, please refer to: <a href=\"#!/api/Siesta.Test\" rel=\"Siesta.Test\" class=\"docClass\">Siesta.Test</a> class.</p>\n\n<h2 id='getting_started_nodejs-section-launching-the-test-'>Launching the test </h2>\n\n<p>To launch the test, type in the console (assuming you've installed Siesta Lite from npm):</p>\n\n<pre><code>&gt; npx siesta path/to/sample.t.js\n</code></pre>\n\n<p>Here the <code>npx</code> is a Node.js utility (comes with Node) to execute binary files from npm packages.</p>\n\n<p>When using unpacked Siesta Standard archive, use the <code>nodejs</code> launcher:</p>\n\n<pre><code>&gt; bin/nodejs path/to/sample.t.js\n</code></pre>\n\n<p>You should see something like:</p>\n\n<pre><code>Launching test suite, OS: Linux, agent: NodeJS v10.1.0\n[PASS]  sample.t.js\n6 passed, 0 failed assertions took 656ms to complete\n</code></pre>\n\n<p>Instead of path to the specific test file, you can also pass a directory, in this case, all <code>*.t.js</code> files in it will be launched.</p>\n\n<p>Also, you can pass a glob string, which will be resolved with <a href=\"https://www.npmjs.com/package/glob\">glob</a> package. Use trailing slash <code>/</code> to match\ndirectories and <code>**</code> to match directory recursively:</p>\n\n<pre><code>&gt; bin/nodejs path/to/dir/\n\n&gt; bin/nodejs path/to/file*.t.js\n\n&gt; bin/nodejs path/to/**/files_in_dir*.t.js\n</code></pre>\n\n<p>Quick remainder for the <code>OR</code> logic in the files glob:</p>\n\n<pre><code>&gt; bin/nodejs path/to/**/*@(test1|test2)*.t.js \n</code></pre>\n\n<h2 id='getting_started_nodejs-section-siesta-node.js-project'>Siesta Node.js project</h2>\n\n<p>Alternatively, instead of the individual test file, you can launch the Siesta project file, which contains all the information about the test suite.\nLets see how Siesta Node.js project look like (lets name it <code>siesta.js</code>):</p>\n\n<pre><code>let Siesta      = require('siesta-lite')\n\nlet project     = new <a href=\"#!/api/Siesta.Project.NodeJS\" rel=\"Siesta.Project.NodeJS\" class=\"docClass\">Siesta.Project.NodeJS</a>()\n\nproject.configure({\n    title               : 'My NodeJS test suite',\n\n    autoCheckGlobals    : true\n})\n\nproject.planDirectory(__dirname)\n\nproject.start()\n</code></pre>\n\n<p>Everything should be pretty self-explanatory. The <a href=\"#!/api/Siesta.Project.NodeJS-method-planDirectory\" rel=\"Siesta.Project.NodeJS-method-planDirectory\" class=\"docClass\">planDirectory</a> method scans the directory\nfor the <code>*.t.js</code> files and adds them to the project plan. You can also add some files explicitly, using <a href=\"#!/api/Siesta.Project.NodeJS-method-plan\" rel=\"Siesta.Project.NodeJS-method-plan\" class=\"docClass\">plan</a> method:</p>\n\n<pre><code>project.plan([\n    'some_test.t.js',\n    'path/to/some_other_test.t.js'\n]) \n</code></pre>\n\n<p>You can launch the project file as any other regular Node script:</p>\n\n<pre><code>&gt; node siesta.js\n</code></pre>\n\n<h2 id='getting_started_nodejs-section-sandboxing'>Sandboxing</h2>\n\n<p>By default, <a href=\"#!/api/Siesta.Project.NodeJS-cfg-sandbox\" rel=\"Siesta.Project.NodeJS-cfg-sandbox\" class=\"docClass\">sandboxing</a> is enabled. Every test is launched in isolated NodeJS context. Isolation is\ndone using child NodeJS process. This is the safest approach, but there's an overhead of launching extra Node process.</p>\n\n<p>This behavior is configurable with the <a href=\"#!/api/Siesta.Project.NodeJS-cfg-sandbox\" rel=\"Siesta.Project.NodeJS-cfg-sandbox\" class=\"docClass\">sandbox</a> option, we recommend to keep it enabled\nuntil you start feeling comfortable with Siesta.</p>\n\n<h2 id='getting_started_nodejs-section-configuring-the-project'>Configuring the project</h2>\n\n<p>Please refer to the corresponding section in the <a href=\"#!/guide/getting_started_browser\">Getting started with Siesta in browser environment</a> guide.</p>\n\n<h2 id='getting_started_nodejs-section-configuring-the-individual-test'>Configuring the individual test</h2>\n\n<p>Please refer to the corresponding section in the <a href=\"#!/guide/getting_started_browser\">Getting started with Siesta in browser environment</a> guide.</p>\n\n<h2 id='getting_started_nodejs-section-command-line-arguments'>Command-line arguments</h2>\n\n<p>When launching individual tests using NodeJS launcher, general rule is - all arguments on the left side from the test filename goes to Node binary,\narguments on the right side - to the Siesta launcher, so this command will output Node.js help screen:</p>\n\n<pre><code>siesta$ bin/nodejs --help path/to/sanity.t.js\n</code></pre>\n\n<p>And this - the Siesta help screen:</p>\n\n<pre><code>siesta$ bin/nodejs path/to/sanity.t.js --help \n</code></pre>\n\n<p>If there's no test filename, all arguments goes to Siesta, so the following command will output Siesta help again:</p>\n\n<pre><code>siesta$ bin/nodejs --help \n</code></pre>\n\n<p>You can use the Siesta's <code>--node-arg</code> command line argument to pass arguments to the Node.js processes of individual tests.</p>\n\n<h2 id='getting_started_nodejs-section-debugging-'>Debugging </h2>\n\n<p>To enable the debugging mode, pass <code>--inspect[=[host:]port]</code> command line option. It is translated to the <code>--inspect</code> option of the Node.js\nprocess and will start a debugger instance on the given host/port. It will also switch a test suite to the <code>--max-workers=1</code> mode,\nto avoid collisions between the debugger instances (because they use the same port).</p>\n\n<p>There's also <code>--inspect-brk[=[host:]port]</code>, which is the same as <code>--inspect</code> but also issues a <code>debugger</code> statement before the\nevery test.</p>\n\n<p>You can use the <code>--node-arg</code> switch to pass the <code>--inspect/--inspect-brk</code> command line options to Node.js process directly.</p>\n\n<h2 id='getting_started_nodejs-section-using-ecma-modules.-'>Using Ecma modules. </h2>\n\n<p>Siesta is Ecma modules friendly by default, by using the <a href=\"https://www.npmjs.com/package/esm\"><code>esm</code></a> module loader. No special configuration is needed,\njust write your tests as Ecma modules:</p>\n\n<pre><code>import {some} from 'some/src/file.js'\n\nStartTest(t =&gt; {\n    t.is(value, 1, 'Imported correct')\n})\n</code></pre>\n\n<p>Please consider including the <code>esm</code> into your project, to stop the fragmentation in JavaScript module systems implementations.</p>\n\n<p>However, using absolute urls in your <code>import</code> won't be compatible with browsers implementations (without bundler build step).\nIf you want to write code \"isomorphically\" and do not want an extra build step, you should use relative urls:</p>\n\n<pre><code>// not compatible with browsers w/o a webpack pass\nimport {someFunc} from 'some'\n\n// works in modern browsers w/o any changes\nimport {some} from '../node_modules/some/src/file.js'\n\nStartTest(t =&gt; {\n    t.is(value, 1, 'Imported correct')\n})\n</code></pre>\n\n<h2 id='getting_started_nodejs-section-using-typescript'>Using Typescript</h2>\n\n<p>You can write tests in TypeScript. Currently you need to declare the <code>StartTest</code> entry point:</p>\n\n<pre><code>import {Something} from \"../../lib/util/SomeUtil.js\";\nimport {SomethingElse} from \"../../lib/SomeOther.js\";\n\ndeclare const StartTest : any\n\nStartTest(t =&gt; {\n    ...\n})\n</code></pre>\n\n<p>Then, using TypeScript compilation step, this test will be converted to a library system of your choice.</p>\n\n<p>Note, that in the Siesta project file, you need to specify the paths of the JavaScript sources, compiled from TypeScript.</p>\n\n<h2 id='getting_started_nodejs-section-code-coverage'>Code coverage</h2>\n\n<p>Please refer to <a href=\"#!/guide/code_coverage\">this guide</a></p>\n\n<h2 id='getting_started_nodejs-section-further-reading'>Further reading</h2>\n\n<p>The <a href=\"#!/guide/getting_started_browser-section-structuring-the-test-suite\">Getting started with Siesta in browser environment</a> guide\ncontains additional information about structuring the test suite, testing asynchronous code, waiting for conditions and some other.\nPlease continue reading there.</p>\n\n<h2 id='getting_started_nodejs-section-buy-this-product'>Buy this product</h2>\n\n<p>Visit our store: <a href=\"https://bryntum.com/store/siesta\">https://bryntum.com/store/siesta</a></p>\n\n<h2 id='getting_started_nodejs-section-support'>Support</h2>\n\n<p>Ask question in our community forum: <a href=\"https://www.bryntum.com/forum/viewforum.php?f=20\">https://www.bryntum.com/forum/viewforum.php?f=20</a></p>\n\n<p>Subscribers can post expedited questions in Premium Forum: <a href=\"https://www.bryntum.com/forum/viewforum.php?f=21\">https://www.bryntum.com/forum/viewforum.php?f=21</a></p>\n\n<p>Please report any bugs through the web interface at <a href=\"https://www.assembla.com/spaces/bryntum/support/tickets\">https://www.assembla.com/spaces/bryntum/support/tickets</a></p>\n\n<h2 id='getting_started_nodejs-section-see-also'>See also</h2>\n\n<p>Siesta web-page: <a href=\"https://bryntum.com/products/siesta\">https://bryntum.com/products/siesta</a></p>\n\n<p>Other Bryntum products: <a href=\"https://bryntum.com/products\">https://bryntum.com/products</a></p>\n\n<h2 id='getting_started_nodejs-section-attribution'>Attribution</h2>\n\n<p>This software contains icons from the following icon packs (licensed under Creative Common 2.5/3.0 Attribution licenses)</p>\n\n<ul>\n<li><a href=\"http://www.famfamfam.com/lab/icons/silk/\">http://www.famfamfam.com/lab/icons/silk/</a></li>\n<li><a href=\"http://led24.de/iconset/\">http://led24.de/iconset/</a></li>\n<li><a href=\"http://p.yusukekamiyamane.com/\">http://p.yusukekamiyamane.com/</a></li>\n<li><a href=\"http://rrze-icon-set.berlios.de/index.html\">http://rrze-icon-set.berlios.de/index.html</a></li>\n<li><a href=\"http://www.smashingmagazine.com/2009/05/20/flavour-extended-the-ultimate-icon-set-for-web-designers/\">http://www.smashingmagazine.com/2009/05/20/flavour-extended-the-ultimate-icon-set-for-web-designers/</a></li>\n<li><a href=\"http://www.doublejdesign.co.uk/products-page/icons/super-mono-icons/\">http://www.doublejdesign.co.uk/products-page/icons/super-mono-icons/</a></li>\n<li><a href=\"http://pixel-mixer.com/\">http://pixel-mixer.com/</a></li>\n</ul>\n\n\n<p>Thanks a lot to the authors of the respective icons packs.</p>\n\n<h2 id='getting_started_nodejs-section-copyright-and-license'>COPYRIGHT AND LICENSE</h2>\n\n<p>Copyright (c) 2009-2022, Bryntum &amp; Nickolay Platonov</p>\n\n<p>All rights reserved.</p>\n","title":"Node environment"});