Get your project tested and out there with minimal fuss.
Get your project tested and out there with minimal fuss.
- compile your sources and dependencies using webpack so that you can easily include other people's libraries using commonJS modules and npm
- check your source with eslint to warn you of common bugs
- generate documentation from source code and comments with jsdoc
The goal of Jester is to give you a bootstrap for integrating these tools so you can worry about your app code and not about the tooling. It can run in batch mode or it can watch your source directories for changes and rerun tests immediately when you update your sources.
- Install node.js
- Create a directory for your app
mkdir myApp; cd myApp
- Add a basic machine readable description of your app
- Install jester from npm and save it into the development dependencies. Under windows you'll have to run this as administrator (required by jsdoc for creating symlinks):
npm install --save-dev jester-tester
Initialize your project. This will create the required folders and
jester.json configuration file with default values for your project:
This will create the following directories:
And the following files:
./jester.json # configuration for jester ./jsdoc.conf # configuration for jsdoc, see: http://usejsdoc.org/about-configuring-jsdoc.html ./readme.md # the readme is in markdown and will be included in the jsdoc output
Jester assumes that you build your application from features. Each feature will
be a separate js file that you can load from an html file in the browser by
Jester packages your features with their dependencies with the help of webpack.
It accomplishes this by searching for a file named
feature.js in a subfolder
The feature is contained in
/*globals console*/// dependencies are imported using commonJSvar hello = require"../../lib/hello";console.loghello;
The hello function is found in src/lib/hello.js:
return "hello world!";moduleexports = hello;
##Generating the results file
./node_modules/.bin/jester-batch.js results in two files.
greeting.min.js and greeting.min.js.map. The .js file contains the full
maps the source code in the compiled .js file to the original files and lines
for use in the browser debuggers that support this (chrome and firefox atm).
Note!: Source maps are not always interpreted and not all browsers support the same features.
- You have to enable them manually in chrome (FF has them enabled by default)
- You won't see the stack traces source mapped in jester's shell output
- You should see the stack trace source mapped when opening the development console in chrome. Firefox doesn't source map stack traces and I haven't found a way to enable it.
You might notice some warnings in the output. This is eslint telling you that
using console in production code is frowned upon. Some other eslint tests are
configured as errors and jester will flat out refuse to generate the
greeting.min.js file if you forget to put a
var in front of hello. You can
configure eslint in the file
###If you think jester-batch is too slow
Jester-batch takes a while to launch and this gets tiresome. So you can also run
node_modules/.bin/jester-watch.js) which will keep running and
therefore generate the result files much more quickly.
unittests for that piece of code. This file must have the same name of the
tested code, with a
So let's start with hello world by creating the test file
//Tests are normal js modules, so they load the module under test using commonJSvar hello = require"./hello";// jasmine is implicitly available in .test.js filesdescribe"Greetings"it"returns `hello tested world`"expecthellotoBe"hello tested world!";;;
This test asserts that the function hello will return the string
hello tested world.
The test will run upon saving it if jester-watch is running, or else when you
Jester will now run your tests in the browsers as specified in
course the test will fail because the result of hello is different. Fix the file
src/lib/hello.js and try running jester-batch again:
return "hello tested world!";moduleexports = hello;
##Dependency injection Jester makes it easy to replace a 'require'd module in the source file with a test-stub.
Let's say we have a file called src/lib/db.js
var retrieveHello = require"db/retrieveHello"moduleexports =return retrieveHello"pgsql://mypgserver"
and that hello.js uses that:
var db = require"./db";return db;moduleexports = hello;
that implements retrieveHello and even if you would npm install it, your test
would be dependant on
Instead your test should inject a shim for db.js
/**globals console*/return "Hello tested and injected world!";var helloMaker = require"jester-tester/src/injectable!./hello";var hello = helloMaker"./db": dbShimdescribe"Greetings"it"returns `hello world`"expecthellotoBe"Hello tested and injected world!";;;
I encourage you to log the helloMaker function to the console so you can see what happens under the hood. It's not really magical.
Documentation will be generated from appropriately annotated sources by jsdoc and includes the syntax highlighted source code. See usejsdoc for how to annotate your code, especially relevant is Document CommonJS Modules.
There are many ways to export and document code. The recommended way to export functions is:
This enables jsdoc to recognize that clone is a (static) function, the clone symbol will show up in stack traces and is fully supported by IE8.
The api documentation will be written to a directory specified by the
apiDocPath setting in
jester.json, which defaults to
./doc/api/. You can set the configuration option
readme to point to a file that is a markdown formatted readme which will be included in the generated documentation on the homepage.
The api documentation will be generated when you run
jester-doc. The latter is a bit faster because it only runs jsdoc. The documentation is not automatically updated when running
An additional benefit of annotating your code with jsdoc style comments is that there are a number of tools such as ide's and compilers which can take advantages of the additional information contained in those comments.