jasmine-node

jasmine-node
======


This node.js module makes the wonderful Pivotal Lab's jasmine
spec framework (version 1) 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, which allows you to use the
ddescribe and iit functions to run individual suites or specs.

NOTICE: BETA 2.0.0 Support in the Jasmine2.0 branch (with rewrite in CoffeeScript) is now abandoned and no longer supported.

Supported Node.js versions
--------------------------

* Current:
- 10
- 12
* Deprecated:
- 8 (EOL in December 2019)
- 6 (already past EOL)
- 4 (already past EOL)

Older versions of Node.js are no longer supported. It is highly recommended to upgrade to a supported version of Node.js.

what's new
----------
* Growl notifications with the --growl flag (requires Growl to be installed)
* Ability to test specs written in Literate CoffeeScript
* 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 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.

$3

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.

$3

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 notifications of test
run summaries in addition to other reports.
Growl must be installed separately, see 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.2 Back to jasmine-growl-reporter@~0.2.0 (needed by Node.js pre-4.0)
* 1.16.1 Use ~ instead of ^ in dependencies (may be needed by some really old npm versions)
* 1.16.0 Fix dependencies to prevent major package updates
* 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)
* 1.14.4 Rolled back jasmine reporter version (thanks to tjmcduffie)
* 1.14.3 Added 'onComplete' callback to TeamCityReporter (thanks to 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)
* 1.13.1 Add coffee-script support for 1.7.x (thanks to nathancarter)
* 1.13.0 Added timing to the verbose reporter (thanks to 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)
* Don’t affect line numbers with --requireJsSetup (thanks to daviddaurelio)
* Catch errors when loading helpers (thanks to pimterry)
* Keep autotesting until all tests have passed (thanks to notclive)
* 1.11.0 Added Growl notification option --growl (thanks to
AlphaHydrae)
* 1.10.2 Restored stack filter which was accidentally removed (thanks to
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)
* 1.9.1 Timeout now consistent between Async and Non-Async Calls (thanks to
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)
* 1.8.0 Fixed bug in autotest with multiple paths and added --watch feature
(thanks to davegb3)
* 1.7.1 Removed unneeded fs dependency (thanks to
kevinsawicki) Fixed broken fs call in
node 0.6 (thanks to abe33)
* 1.7.0 Literate CoffeeScript now testable (thanks to magicmoose)
* 1.6.0 Teamcity Reporter Reinstated (thanks to 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)
* 1.4.0 Optional flag to suppress stack trace on test failure (thanks to Lastalas)
* 1.3.1 Fixed context for async tests (thanks to 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