jasmine-node
Version:
DOM-less simple JavaScript BDD testing framework for Node
299 lines (231 loc) • 12.2 kB
Markdown
jasmine-node
======
[](http://travis-ci.org/spaghetticode/jasmine-node)
This node.js module makes the wonderful [Pivotal Lab's jasmine](http://github.com/pivotal/jasmine)
spec framework available in node.js.
Project status
--------------
This project is now in maintenance mode. It is recommended to use the `jasmine` or `jasmine-npm`
package whenever possible.
jasmine
-------
Version `1.3.1` of Jasmine is currently included with node-jasmine. This is a forked version from the
[Karma project](https://github.com/karma-runner/karma-jasmine), which allows you to use the
`ddescribe` and `iit` functions to run individual suites or specs.
BETA `2.0.0` Support is available in the `Jasmine2.0` branch.
what's new
----------
* Growl notifications with the `--growl` flag (requires Growl to be installed)
* Ability to test specs written in Literate Coffee-Script
* Teamcity Reporter reinstated.
* Ability to specify multiple files to test via list in command line
* Ability to suppress stack trace with `--noStack`
* Async tests now run in the expected context instead of the global one
* `--config` flag that allows you to assign variables to process.env
* Terminal Reporters are now available in the Jasmine Object #184
* Done is now available in all timeout specs #199
* `afterEach` is available in requirejs #179
* Editors that replace instead of changing files should work with autotest #198
* Jasmine Mock Clock now works!
* Autotest now works!
* Using the latest Jasmine!
* Verbose mode tabs `describe` blocks much more accurately!
* `--coffee` now allows specs written in Literate CoffeeScript (`.litcoffee`)
install
------
To install the latest official version, use NPM:
```sh
npm install jasmine-node -g
```
To install the latest _bleeding edge_ version, clone this repository and check
out the `beta` branch.
usage
------
Write the specifications for your code in `*.js` and `*.coffee` files in the `spec/` directory.
You can use sub-directories to better organise your specs. In the specs use `describe()`, `it()` etc. exactly
as you would in client-side jasmine specs.
**Note**: your specification files must be named as `*spec.js`, `*spec.coffee` or `*spec.litcoffee`,
which matches the regular expression `/spec\.(js|coffee|litcoffee)$/i`;
otherwise jasmine-node won't find them!
For example, `sampleSpecs.js` is wrong, `sampleSpec.js` is right.
If you have installed the npm package, you can run it with:
```sh
jasmine-node spec/
```
If you aren't using npm, you should add `pwd`/lib to the `$NODE_PATH`
environment variable, then run:
```sh
node lib/jasmine-node/cli.js
```
You can supply the following arguments:
* `--autotest`, provides automatic execution of specs after each change
* `--watch`, when used with `--autotest`, paths after `--watch` will be
watched for changes, allowing to watch for changes outside of specs directory
* `--coffee`, allow execution of `.coffee` and `.litcoffee` specs
* `--color`, indicates spec output should uses color to
indicates passing (green) or failing (red) specs
* `--noColor`, do not use color in the output
* `-m, --match REGEXP`, match only specs containing "REGEXPspec"
* `--matchall`, relax requirement of "spec" in spec file names
* `--verbose`, verbose output as the specs are run
* `--junitreport`, export tests results as junitreport xml format
* `--output FOLDER`, defines the output folder for junitreport files
* `--teamcity`, converts all console output to teamcity custom test runner commands. (Normally auto detected.)
* `--growl`, display test run summary in a growl notification (in addition to other outputs)
* `--runWithRequireJs`, loads all specs using requirejs instead of node's native require method
* `--requireJsSetup`, file run before specs to include and configure RequireJS
* `--test-dir`, the absolute root directory path where tests are located
* `--nohelpers`, does not load helpers
* `--forceexit`, force exit once tests complete
* `--captureExceptions`, listen to global exceptions, report them and exit (interferes with Domains in NodeJs, so do not use if using Domains as well
* `--config NAME VALUE`, set a global variable in `process.env`
* `--noStack`, suppress the stack trace generated from a test failure
Individual files to test can be added as bare arguments to the end of the args.
Example:
```bash
jasmine-node --coffee spec/AsyncSpec.coffee spec/CoffeeSpec.coffee spec/SampleSpec.js
```
async tests
-----------
jasmine-node includes an alternate syntax for writing asynchronous tests. Accepting
a done callback in the specification will trigger jasmine-node to run the test
asynchronously waiting until the `done()` callback is called.
```javascript
var request = require('request');
it("should respond with hello world", function(done) {
request("http://localhost:3000/hello", function(error, response, body){
expect(body).toEqual("hello world");
done();
});
});
```
An asynchronous test will fail after `5000` ms if `done()` is not called. This timeout
can be changed by setting `jasmine.getEnv().defaultTimeoutInterval` or by passing a timeout
interval in the specification.
```javascript
var request = require('request');
it("should respond with hello world", function(done) {
request("http://localhost:3000/hello", function(error, response, body){
done();
});
}, 250); // timeout after 250 ms
```
or
```javascript
var request = require('request');
jasmine.getEnv().defaultTimeoutInterval = 500;
it("should respond with hello world", function(done) {
request("http://localhost:3000/hello", function(error, response, body){
done();
}); // timeout after 500 ms
});
```
Checkout [`spec/SampleSpecs.js`](https://github.com/mhevery/jasmine-node/blob/master/spec/SampleSpecs.js) to see how to use it.
requirejs
---------
There is a sample project in `/spec-requirejs`. It is comprised of:
1. `requirejs-setup.js`, this pulls in our wrapper template (next)
1. `requirejs-wrapper-template`, this builds up requirejs settings
1. `requirejs.sut.js`, this is a __SU__bject To __T__est, something required by requirejs
1. `requirejs.spec.js`, the actual jasmine spec for testing
To run it:
```sh
node lib/jasmine-node/cli.js --runWithRequireJs --requireJsSetup ./spec-requirejs/requirejs-setup.js ./spec-requirejs/
```
exceptions
----------
Often you'll want to capture an uncaught exception and log it to the console,
this is accomplished by using the `--captureExceptions` flag. Exceptions will
be reported to the console, but jasmine-node will attempt to recover and
continue. It was decided to not change the current functionality until `2.0`. So,
until then, jasmine-node will still return `0` and continue on without this flag.
### Scenario ###
You require a module, but it doesn't exist, ie `require('Q')` instead of
`require('q')`. Jasmine-Node reports the error to the console, but carries on
and returns `0`. This messes up Travis-CI because you need it to return a
non-zero status while doing CI tests.
### Mitigation ###
Before `--captureExceptions`
```sh
> jasmine-node --coffee spec
> echo $status
0
```
Run jasmine node with the `--captureExceptions` flag.
```sh
> jasmine-node --coffee --captureExceptions spec
> echo $status
1
```
growl notifications
-------------------
Jasmine node can display [Growl](http://growl.info) notifications of test
run summaries in addition to other reports.
Growl must be installed separately, see [node-growl](https://github.com/visionmedia/node-growl)
for platform-specific instructions. Pass the `--growl` flag to enable the notifications.
development
-----------
Install the dependent packages by running:
```sh
npm install
```
Run the specs before you send your pull request:
```sh
specs.sh
```
__Note:__ Some tests are designed to fail in the specs.sh. After each of the
individual runs completes, there is a line that lists what the expected
Pass/Assert/Fail count should be. If you add/remove/edit tests, please be sure
to update this with your PR.
changelog
---------
* _1.16.0_ Fix `dependencies` to prevent major package updates
* _1.15.1_ Use coffeescript@1 to avoid potentially breaking change in a minor release
* _1.15.0_ Switch to coffeescript package
* _1.14.6_ Update dependencies to resolve `npm audit` issues
* _1.14.5_ Using ~ instead of ^ for reporter version (thanks to [Maxim-Filimonov](https://github.com/Maxim-Filimonov))
* _1.14.4_ Rolled back jasmine reporter version (thanks to [tjmcduffie](https://github.com/tjmcduffie))
* _1.14.3_ Added 'onComplete' callback to TeamCityReporter (thanks to [JoergFiedler](https://github.com/JoergFiedler))
* _1.14.2_ Uhhh...not sure what happened here.
* _1.14.1_ Default to noColors if not in a TTY
* _1.14.0_ Add support for `iit`, `ddescribe` (thanks to [mgcrea](https://github.com/mgcrea))
* _1.13.1_ Add coffee-script support for 1.7.x (thanks to [nathancarter](https://github.com/nathancarter))
* _1.13.0_ Added timing to the verbose reporter (thanks to [rick-kilgore](https://github.com/rick-kilgore))
* _1.12.1_ Fixed an issue where an undefined variable caused an unhelpful
exception in --watch Resolves #278
* _1.12.0_
* Changed `util.print` to `stdout.write` (thanks to [nrstott](https://github.com/nrstott))
* Don’t affect line numbers with --requireJsSetup (thanks to [daviddaurelio](https://github.com/davidaurelio))
* Catch errors when loading helpers (thanks to [pimterry](https://github.com/pimterry))
* Keep autotesting until all tests have passed (thanks to [notclive](https://github.com/notclive))
* _1.11.0 - Added Growl notification option `--growl` (thanks to
[AlphaHydrae](https://github.com/AlphaHydrae))_
* _1.10.2 - Restored stack filter which was accidentally removed (thanks to
[kevinsawicki](https://github.com/kevinsawicki))_
* _1.10.1 - `beforeEach` and `afterEach` now properly handle the async-timeout function_
* _1.10.0 - Skipped tests now show in the terminal reporter's output (thanks
to [kevinsawicki](https://github.com/kevinsawicki))_
* _1.9.1 - Timeout now consistent between Async and Non-Async Calls (thanks to
[codemnky](https://github.com/codemnky))_
* _1.9.0 - Now re-throwing the file-not-found error, added info to README.md,
printing version with `--version`_
* _1.8.1 - Fixed silent failure due to invalid REGEX (thanks to
[pimterry](https://github.com/pimterry))_
* _1.8.0 - Fixed bug in autotest with multiple paths and added `--watch` feature
(thanks to [davegb3](https://github.com/davegb3))_
* _1.7.1 - Removed unneeded fs dependency (thanks to
[kevinsawicki](https://github.com/kevinsawicki)) Fixed broken fs call in
node `0.6` (thanks to [abe33](https://github.com/abe33))_
* _1.7.0 - Literate Coffee-Script now testable (thanks to [magicmoose](https://github.com/magicmoose))_
* _1.6.0 - Teamcity Reporter Reinstated (thanks to [bhcleek](https://github.com/bhcleek))_
* _1.5.1 - Missing files and require exceptions will now report instead of failing silently_
* _1.5.0 - Now takes multiple files for execution. (thanks to [abe33](https://github.com/abe33))_
* _1.4.0 - Optional flag to suppress stack trace on test failure (thanks to [Lastalas](https://github.com/Lastalas))_
* _1.3.1 - Fixed context for async tests (thanks to [omryn](https://github.com/omryn))_
* _1.3.0 - Added `--config` flag for changeable testing environments_
* _1.2.3 - Fixed #179, #184, #198, #199. Fixes autotest, afterEach in requirejs, terminal reporter is in jasmine object, done function missing in async tests_
* _1.2.2 - Revert Exception Capturing to avoid Breaking Domain Tests_
* _1.2.1 - Emergency fix for path reference missing_
* _1.2.0 - Fixed #149, #152, #171, #181, #195. `--autotest` now works as expected, jasmine clock now responds to the fake ticking as requested, and removed the path.exists warning_
* _1.1.1 - Fixed #173, #169 (Blocks were not indented in verbose properly, added more documentation to address #180_
* _1.1.0 - Updated Jasmine to `1.3.1`, fixed fs missing, catching uncaught exceptions, other fixes_