siesta-lite

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