source: pyenvjasmine/pyenvjasmine/envjasmine/README.textile@ 19:ab5f65372038

h1. EnvJasmine: Jasmine test runner for EnvJS. !https://secure.travis-ci.org/trevmex/EnvJasmine.png!

EnvJasmine allows you to run headless JavaScript tests.

h2. Creating New Specs

Add your Jasmine Spec files to the specs directory to be run.

IMPORTANT: Make sure to load the file you are planning to test as the first line of the spec file using the @EnvJasmine.load("file.js");@ function.

h2. Running JavaScript tests

To run the JavaScript test suite, execute the following:

bc. bin/run_all_tests.sh

To run an individual spec file, execute the following:

bc. bin/run_test.sh specs/[your spec file].js

In Windows you do the same by running:

bc. bin/run_all_tests.bat

bc. bin/run_test.bat specs/[your spec file].js

h2. Adding Dependencies

Sometimes you will have libraries that you need to load for any of your JavaScript files to work. To make sure these are loaded before your tests are run, include them in the @include/dependencies.js@ file using the @EnvJasmine.load("file.js");@ function.

You can alsodefine a custom config file location to replace @include/dependencies.js@ by calling run_test or run_all_tests with the @--configFile=<config js file>@ option.

h2. Based on info from:

    * "JavaScript BDD, with Jasmine, without a browser":http://www.build-doctor.com/2010/12/08/javascript-bdd-jasmine/
    * "Rhino":http://www.mozilla.org/rhino/
    * "EnvJS":http://www.envjs.com/
    * "Jasmine":http://pivotal.github.com/jasmine/
    * "Jasmine Jquery":https://github.com/velesin/jasmine-jquery

Originally created by Jeff Avallone and Trevor Lalish-Menagh. See "LICENSE":https://github.com/trevmex/EnvJasmine/blob/master/LICENSE for lincensing information.

See "CHANGELOG":https://github.com/trevmex/EnvJasmine for changelog information.

Current version is found in the "VERSION":https://github.com/trevmex/EnvJasmine/blob/master/VERSION file.

h2. A Basic Tutorial

How to set up EnvJasmine within a basic web project. Note that this tutorial assumes you're working within a *nix environment.

h3. 1. Create a project directory.

Create a directory in which to house your project. Let's call this @demo@. After creating the directory, enter it:

bc. mkdir demo
cd demo

h3. 2. Create a JavaScript directory.

Create a @js@ directory inside @demo@ to house JavaScript files:

bc. mkdir js

h3. 3. Create a tests directory.

Create a directory in @demo@ to house your tests. As is often customary, let's call this directory @tests@:

bc. mkdir tests

h3. 4. Integrate EnvJasmine into the project.

Clone EnvJasmine into your @tests@ directory:

bc. git clone https://github.com/trevmex/EnvJasmine.git tests/EnvJasmine

or

bc. git clone git://github.com/trevmex/EnvJasmine.git tests/EnvJasmine

h3. 5. Create a JavaScript file.

For the purposes of this example, let's assume we need to create some JavaScript that adds two numbers and returns their sum. Let's create a JavaScript file to house this code:

bc. touch js/add-numbers.js

h3. 6. Create a spec file.

Create an EnvJasmine spec file, inside of which we'll write a test against the functionality of @js/add-numbers.js@:

bc. touch tests/EnvJasmine/specs/add-numbers.spec.js

h3. 7. Load the necessary JavaScript into the test spec.

Inside @tests/EnvJasmine/specs/add-numbers.spec.js@, let's load the file containing the code we're testing, in this case @js/add-numbers.js@. This can be done by adding the following line:

bc. EnvJasmine.load(EnvJasmine.jsDir + "/add-numbers.js");

h3. 8. Configure your EnvJasmine.

But what's this @EnvJasmine.jsDir@ business? It's a configuration variable used to define the primary directory housing your JavaScript. It's defined in @tests/EnvJasmine/include/dependencies.js@ and defaults to a top-level directory of @js@. Change this if you're using a different scheme:

bc. mkdir -p tests/EnvJasmine/etc/conf

bc. cp tests/EnvJasmine/include/dependencies.js tests/EnvJasmine/etc/conf/demo.conf.js

And edit the following line:

bc. EnvJasmine.jsDir = EnvJasmine.rootDir + "/../../js";

in @tests/EnvJasmine/etc/conf/demo.conf.js@ with your favourite text editor.

Please note the need for the leading slash.

h3. 9. Write the framework for a basic test.

In @add-numbers.spec.js@, sketch out the basic framework for a unit test against the functionality within @js/add-numbers.js@. Let's assume this file contains a single function, @addNumbers()@:

bc. describe("addNumbers", function () {
    it("returns the sum of the two integers it's passed", function() {
        // test specifics will go here
    });
});

h3. 10. Write the code testing outlining expected behavior of a unit of JavaScript.

Utilizing Jasmine "syntax":https://github.com/pivotal/jasmine/wiki and "matchers":https://github.com/pivotal/jasmine/wiki/Matchers, write the code testing the expected behavior of @addNumbers()@:

bc. describe("addNumbers", function () {
    it("returns the sum of the two integers it's passed", function() {
        expect(addNumbers(1, 2)).toEqual(3);
    });
});

h3. 11. Run the test.

Run the test from the command line:

bc. ./tests/EnvJasmine/bin/run_test.sh --configFile=</absolute/path/to/demo/tests/EnvJasmine/etc/conf/demo.conf.js> specs/add-numbers.spec.js

Note that the above command will run just the @add-numbers.spec.js@ code.

Also note that at this stage, the test should fail as we have not yet written the @addNumbers()@ function.

h3. 12. Write your JavaScript

Write just enough code in @js/add-numbers.js@ to make the test pass:

bc. function addNumbers(a, b) {
    return a + b;
}

h3. 13. Run the test again.

Run the test again and confirm that it passes:

bc. ./tests/EnvJasmine/bin/run_test.sh --configFile=</absolute/path/to/demo/tests/EnvJasmine/etc/conf/demo.conf.js> specs/add-numbers.spec.js


h2. Code Coverage

See @lib/jscover/README.textile@


h2. EnvJasmine as a Ruby gem

EnvJasmine can also be compiled to a Ruby gem.

h3. How to build and install the EnvJasmine gem

    git clone git://github.com/trevmex/EnvJasmine.git
    cd EnvJasmine
    gem build EnvJasmine.gemspec
    gem install EnvJasmine-1.7.1.gem

h3. Using the EnvJasmine Ruby gem

Note that, when used as a Ruby gem, EnvJasmine requires a few command line arguments be specified.

Here is a Ruby usage example:

    envjs_run_test --configFile='some_spec_helper.js' --testDir='specs' --rootDir='some_project'

That's it! For more help on Jasmine docs at https://github.com/pivotal/jasmine/wiki

Please contact Trevor Lalish-Menagh through github (https://github.com/trevmex) with any defects or feature requests!