Table of Contents
- Introduction
- Setup and Installation
- Project Structure
- Unit Tests for Functions
- Unit Tests for Classes
- Unit Tests with Mocks
- Integration Tests for REST APIs
- End-to-End Tests for Web UIs
- Basic Test Execution
- Advanced Test Execution with Karma
- Angular Testing
Introduction
Jasmine is one of the most popular JavaScript test frameworks available. Its tests are intuitively recognizable by their describe/it format. Jasmine is inspired by Behavior-Driven Development and comes with many basic features out-of-the-box. While Jasmine is renowned for its Node.js support, it also supports Python and Ruby. Jasmine also works with JavaScript-based languages like TypeScript and CoffeeScript.
This guide shows how to write tests in JavaScript on Node.js using Jasmine. It uses the jasmine-node-js-example project (hosted on GitHub). Content includes:
- Basic white-box unit tests
- REST API integration tests with frisby
- Web UI end-to-end tests with Protractor
- Spying with sinon
- Monkeypatching with rewire
- Handling config data with JSON files
- Advanced execution features with Karma
- Special considerations for Angular projects
The Jasmine API Reference is also indispensable when writing tests.
Setup and Installation
The official Jasmine Node.js Setup Guide explains how to set up and install Jasmine. Jasmine tests may be added to an existing project or to an entirely new project. As a prerequisite, Node.js must already be installed. Use the following commands to set things up.
# Initialize a new project (if necessary)
# This will create the package.json file
$ mkdir [project-name]
$ cd [project-name]
$ npm init
# Install Jasmine locally for the project and globally for the CLI
$ npm install jasmine
$ npm install -g jasmine
# Create a spec directory with configuration file for Jasmine
$ jasmine init
# Optional: Install official Jasmine examples
# Do this only for self-education in a separate project
$ jasmine examples
The code used by this guide is available in GitHub at jasmine-node-js-example. Feel free to clone this repository to try things out yourself!
Recommended editors and IDEs include Visual Studio Code with the Jasmine Snippets extensions, Atom, and JetBrains WebStorm.
Project Structure
Jasmine does not require the project to have a specific directory layout, but it does use a configuration file to specify where to find tests. The default, conventional project structure created by “jasmine init” puts all Jasmine code into a “spec” directory, which contains “*spec.js” files for tests, helpers that run before specs, and a support directory for config. The JASMINE_CONFIG_PATH environment variable can be set to change the config file used. (The default config file is spec/support/jasmine.json.)
[project-name]
|-- [product source code]
|-- spec
| |-- [spec sub-directory]
| | `-- *spec.js
| |-- helpers
| | `-- [helper sub-directory]
| `-- support
| `-- jasmine.json
`-- package.json
This structure may be changed using the “spec_dir”, “spec_files”, and “helpers” properties in the config file. For example, it may be useful to change the structure to include more than one level of directories to the hierarchy. However, it is typically best to leave the conventional directory layout in place. The default config values as of Jasmine 2.8 are below.
{
"spec_dir": "spec",
"spec_files": [
"**/*[sS]pec.js"
],
"helpers": [
"helpers/**/*.js"
],
"stopSpecOnExpectationFailure": false,
"random": false
}
It is also a best practice to separate tests between different levels of the Testing Pyramid. The example project has spec subdirectories for unit, integration, and end-to-end tests. Directory-level organization makes it easy to filter tests by level when executed.
Unit Tests for Functions
The most basic unit of code to be tested in JavaScript is a function. The “lib/calculator.functions.js” module contains some basic math functions for easy testing.
// --------------------------------------------------
// lib/calculator.functions.js
// --------------------------------------------------
// Calculator Functions
function add(a, b) {
return a + b;
}
function subtract(a, b) {
return a - b;
}
function multiply(a, b) {
return a * b;
}
function divide(a, b) {
let value = a * 1.0 / b;
if (!isFinite(value))
throw new RangeError('Divide-by-zero');
else
return value;
}
function maximum(a, b) {
return (a >= b) ? a : b;
}
function minimum(a, b) {
return (a <= b) ? a : b;
}
// Module Exports
module.exports = {
add: add,
subtract: subtract,
multiply: multiply,
divide: divide,
maximum: maximum,
minimum: minimum,
}
Its tests are in “spec/unit/calculator.function.spec.js”. Below is a snippet showing simple tests for the “add” function. A describe block groups a “suite” of specs together. Each it block is an individual spec (or test). Titles for specs are often written as what the spec should do. Describe blocks may be nested for hierarchical grouping, but it blocks (being bottom-level) may not. Assertions are made using Jasmine’s fluent-like expect and matcher methods. Since the functions are stateless, no setup or cleanup is needed. Tests for other math functions are similar.
// --------------------------------------------------
// spec/unit/calculator.function.spec.js
// --------------------------------------------------
const calc = require('../../lib/calculator.functions');
describe("Calculator Functions", function() {
describe("add", function() {
it("should add two positive numbers", function() {
let value = calc.add(3, 2);
expect(value).toBe(5);
});
it("should add a positive and a negative number", function() {
let value = calc.add(3, -2);
expect(value).toBe(1);
});
it("should give the same value when adding zero", function() {
let value = calc.add(3, 0);
expect(value).toBe(3);
});
});
});
The divide-by-zero test for the “divide” function is special because it must verify that an exception is thrown. The divide call is wrapped in a function so that it may be passed into the expect call.
describe("divide", function() {
// ...
it("should throw an exception when dividing by zero", function() {
let divideByZero = function() { calc.divide(3, 0); };
expect(divideByZero).toThrowError(RangeError, 'Divide-by-zero');
});
// ...
});
The “maximum” and “minimum” functions have parametrized tests using the Array class’s forEach method. This is a nifty trick for hitting multiple input sets without duplicating code or combining specs. Note that the spec titles are also parametrized. Tests for “maximum” are shown below.
describe("maximum", function() {
[
[1, 2, 2],
[2, 1, 2],
[2, 2, 2],
].forEach(([a, b, expected]) => {
it(`should return ${expected} when given ${a} and ${b}`, () => {
let value = calc.maximum(a, b);
expect(value).toBe(expected);
});
});
});
Unit Tests for Classes
Jasmine can also test classes. When testing classes, setup and cleanup routines become more helpful. The Calculator class in the “lib/calculator.class.js” module calls the math functions and caches the last answer.
// --------------------------------------------------
// lib/calculator.class.js
// --------------------------------------------------
// Imports
const calcFunc = require('./calculator.functions');
// Calculator Class
class Calculator {
constructor() {
this.last_answer = 0;
}
do_math(a, b, func) {
return (this.last_answer = func(a, b));
}
add(a, b) {
return this.do_math(a, b, calcFunc.add);
}
subtract(a, b) {
return this.do_math(a, b, calcFunc.subtract);
}
multiply(a, b) {
return this.do_math(a, b, calcFunc.multiply);
}
divide(a, b) {
return this.do_math(a, b, calcFunc.divide);
}
maximum(a, b) {
return this.do_math(a, b, calcFunc.maximum);
}
minimum(a, b) {
return this.do_math(a, b, calcFunc.minimum);
}
}
// Module Exports
module.exports = {
Calculator: Calculator,
}
The Jasmine specs in “spec/unit/calculator.class.spec.js” are very similar but now call the beforeEach method to construct the Calculator object before each scenario. (Jasmine also has methods for afterEach, beforeAll, and afterAll.) The verifyAnswer helper function also makes assertions easier. The addition tests are shown below.
// --------------------------------------------------
// spec/unit/calculator.class.spec.js
// --------------------------------------------------
const calc = require('../../lib/calculator.class');
describe("Calculator Class", function() {
let calculator;
beforeEach(function() {
calculator = new calc.Calculator();
});
function verifyAnswer(actual, expected) {
expect(actual).toBe(expected);
expect(calculator.last_answer).toBe(expected);
}
describe("add", function() {
it("should add two positive numbers", function() {
verifyAnswer(calculator.add(3, 2), 5);
});
it("should add a positive and a negative number", function() {
verifyAnswer(calculator.add(3, -2), 1);
});
it("should give the same value when adding zero", function() {
verifyAnswer(calculator.add(3, 0), 3);
});
});
// ...
});
Unit Tests with Mocks
Mocks help to keep unit tests focused narrowly upon the unit under test. They are essential when units of code depend upon other callable entities. For example, mocks can be used to provide dummy test values for REST APIs instead of calling the real endpoints so that receiving code can be tested independently.
Jasmine’s out-of-the-box spies can do some mocking and spying, but it is not very powerful. For example, it doesn’t work when members of one module call members of another, or even when members of the same module call each other (unless they are within the same class). It is better to use rewire for monkey-patching (mocking via member substitution) and sinon for stubbing and spying.
The “lib/weather.js” module shows how mocking can be done with member dependencies. The WeatherCaller class’s “getForecast” method calls the “callForecast” function, which is meant to represent a service call to get live weather forecasts. The “callForecast” function returns an empty object, but the specs will “rewire” it to return dummy test values that can be used by the WeatherCaller class. Rewiring will work even though “callForecast” is not exported!
// --------------------------------------------------
// lib/weather.js
// --------------------------------------------------
function callForecast(month, day, year, zipcode) {
return {};
}
class WeatherCaller {
constructor() {
this.forecasts = {};
}
getForecast(month, day, year, zipcode) {
let key = `${month}/${day}/${year} for ${zipcode}`;
if (!(key in this.forecasts)) {
this.forecasts[key] = callForecast(month, day, year, zipcode);
}
return this.forecasts[key];
}
}
module.exports = {
WeatherCaller: WeatherCaller,
}
The tests in “spec/unit/weather.mock.spec.js” monkey-patch the “callForecast” function with a sinon stub in the beforeEach call so that each test has a fresh spy count. Note that the weather method is imported using “rewire” instead of “require” so that it can be monkey-patched. Even though the original function returns an empty object, the tests pass because the mock returns the dummy test value.
// --------------------------------------------------
// spec/unit/weather.mock.spec.js
// --------------------------------------------------
// Imports
const rewire = require('rewire');
const sinon = require('sinon');
// Rewirings
const weather = rewire('../../lib/weather');
// WeatherCaller Specs
describe("WeatherCaller Class", function() {
// Test constants
const dummyForecast = {"high": 42, "low": 26};
// Test variables
let callForecastMock;
let weatherModuleRestore;
let weatherCaller;
beforeEach(function() {
// Mock the inner function's return value using sinon
// Do this for each test to avoid side effects of call count
callForecastMock = sinon.stub().returns(dummyForecast);
weatherModuleRestore = weather.__set__("callForecast", callForecastMock);
// Construct the main caller object
weatherCaller = new weather.WeatherCaller();
});
it("should be empty upon construction", function() {
// No mocks required here
expect(Object.keys(weatherCaller.forecasts).length).toBe(0);
});
it("should get a forecast for a date and a zipcode", function() {
// This simply verifies that the return value is correct
let forecast = weatherCaller.getForecast(12, 25, 2017, 21047);
expect(forecast).toEqual(dummyForecast);
});
it("should get a fresh forecast the first time", function() {
// The inner function should be called and the value should be cached
// Note the sequence of assertions, which guarantee safety
let forecast = weatherCaller.getForecast(12, 25, 2017, 21047);
const forecastKey = "12/25/2017 for 21047";
expect(callForecastMock.called).toBeTruthy();
expect(Object.keys(weatherCaller.forecasts).length).toBe(1);
expect(forecastKey in weatherCaller.forecasts).toBeTruthy();
expect(weatherCaller.forecasts[forecastKey]).toEqual(dummyForecast);
});
it("should get a cached forecast the second time", function() {
// The inner function should be called only once
// The same object should be returned by both method calls
let forecast1 = weatherCaller.getForecast(12, 25, 2017, 21047);
let forecast2 = weatherCaller.getForecast(12, 25, 2017, 21047);
expect(callForecastMock.calledOnce).toBeTruthy();
expect(forecast1).toBe(forecast2);
});
it("should get and cache multiple forecasts", function() {
// The other tests verify the mechanics of individual calls
// This test verifies that the caller can handle multiple forecasts
// Initial forecasts
let forecast1 = weatherCaller.getForecast(12, 25, 2017, 27518);
let forecast2 = weatherCaller.getForecast(12, 25, 2017, 27518);
let forecast3 = weatherCaller.getForecast(12, 25, 2017, 21047);
// Change forecast value
weatherModuleRestore();
const newForecast = {"high": 39, "low": 18}
callForecastMock = sinon.stub().returns(newForecast);
weatherModuleRestore = weather.__set__("callForecast", callForecastMock);
// More forecasts
let forecast4 = weatherCaller.getForecast(12, 26, 2017, 21047);
let forecast5 = weatherCaller.getForecast(12, 27, 2017, 21047);
// Assertions
expect(Object.keys(weatherCaller.forecasts).length).toBe(4);
expect("12/25/2017 for 27518" in weatherCaller.forecasts).toBeTruthy();
expect("12/25/2017 for 21047" in weatherCaller.forecasts).toBeTruthy();
expect("12/26/2017 for 21047" in weatherCaller.forecasts).toBeTruthy();
expect("12/27/2017 for 21047" in weatherCaller.forecasts).toBeTruthy();
expect(forecast1).toEqual(dummyForecast);
expect(forecast2).toEqual(dummyForecast);
expect(forecast3).toEqual(dummyForecast);
expect(forecast4).toEqual(newForecast);
expect(forecast5).toEqual(newForecast);
});
afterEach(function() {
// Undo the monkeypatching
weatherModuleRestore();
});
});
Integration Tests for REST APIs
Jasmine can do black-box tests just as well as it can do white-box tests. Testing REST API service calls are some of the most common integration-level tests. There are many REST request packages for Node.js, but frisby is particularly designed for testing. Frisby even has its own expect methods (though the standard Jasmine expect and matchers may still be used).
A best practice for black-box tests is to put config data for external dependencies into a config file. Config data for REST API calls could be URLs, usernames, and passwords. Never hard-code config data into test automation. JavaScript config files are super simple: just write a JSON file and read it during test setup using the “require” function, just like any module. The config data will be automatically parsed as a JavaScript object!
Below is an example test for calling Wikipedia’s REST API. It reads the base URL from a config file and uses it in the frisby call. The config file:
// --------------------------------------------------
// spec/support/env.json
// --------------------------------------------------
{
"integration" : {
"wikipediaServiceBaseUrl": "https://en.wikipedia.org/api/rest_v1"
}
}
And the spec:
// --------------------------------------------------
// spec/integration/wikipedia.service.spec.js
// --------------------------------------------------
const frisby = require('frisby');
describe("English Wikipedia REST API", function() {
const ENV = require("../support/env.json");
const BASE_URL = ENV.integration.wikipediaServiceBaseUrl;
describe("GET /page/summary/{title}", function() {
it("should return the summary for the given page title", function(done) {
frisby
.get(BASE_URL + "/page/summary/Pikachu")
.then(function(response) {
expect(response.status).toBe(200);
expect(response.json.title).toBe("Pikachu");
expect(response.json.pageid).toBe(269816);
expect(response.json.extract).toContain("Pokémon");
})
.done(done);
})
});
// ...
});
End-to-End Tests for Web UIs
Jasmine can also be used for end-to-end Web UI tests. One of the most popular packages for web browser automation is Selenium WebDriver, which uses programming calls to interact with a browser like a real user. Selenium releases a WebDriver package for JavaScript for Node.js, but it is typically a better practice to use Protractor.
Protractor integrates WebDriver with JavaScript test frameworks to make it easier to use. By default, Jasmine is the default framework for Protractor, but Mocha, Cucumber, and any other JavaScript framework could be used. One of the best advantages Protractor has over WebDriver by itself is that Protractor does automatic waiting: explicit calls to wait for page elements are not necessary. This is a wonderful feature that eliminates a lot of repetitive automation code. Protractor also provides tools to easily set up the Selenium Server and browsers (including mobile browsers). Even though Protractor is designed for Angular apps, it can nevertheless be used for non-Angular front-ends.
Web UI tests can be quite complicated because they cover many layers and require extra configuration. Web page interactions frequently need to be reused, too. It is a best practice to use a pattern like the Page Object Model to handle web interactions in one reusable layer. Page objects pull WebDriver locators and actions out of test fixtures (like describe/it functions) so that they may be updated more easily when changes are developed for the actual web pages. (In fact, some teams choose to co-locate page object classes with product source code for the web app so that both are updated simultaneously.) The Page Object Model is a great way to manage the inherently complicated Web automation design.
This guide does not provide a custom example for Protractor with Jasmine because the Protractor documentation is pretty good. It contains a decent tutorial, setup and config instructions, framework integrations, and a full reference. Furthermore, proper Protractor setup requires careful local setup with a live site to test. Please refer to the official doc for more information. Most of the examples in the doc use Jasmine.
Basic Test Execution
The simplest way to run Jasmine tests is to use the “jasmine” command. Make sure you are in the project’s root directory when running tests. Below are example invocations.
# Run all specs in the project (according to the Jasmine config)
$ jasmine
# Run a specific spec by file path
$ jasmine spec/integration/wikipedia.service.spec.js
# Run all specs that match a path pattern
# Warning: this call is NOT recursive and will not search sub-directories!
$ jasmine spec/unit/*
# Run all specs whose titles match a regex filter
# This searches both "describe" and "it" titles
$ jasmine --filter="Calculator"
# Stop testing after the first failure happens
$ jasmine --stop-on-failure=true
# Run tests in a random order
# Optionally include a seed value
$ jasmine --random=true --seed=4321
Test execution options may also be set in the Jasmine config file.
Advanced Test Execution with Karma
Karma is a self-described “spectacular test runner for JavaScript.” Its main value is that it runs JavaScript tests in live web browsers (rather than merely on Node.js), testing actual browser compatibility. In fact, developers can keep Karma running while they develop code so they can see test results in real time as they make changes. Karma integrates with many test tools (including Istanbul for code coverage) and frameworks (including Jasmine). Karma itself runs on Node.js and is distributed as a number of packages for different browsers and frameworks. Check out this Google Testing Blog article to learn the original impetus behind developing Karma, originally called “Testacular.”
Karma and Protractor are similar in that they run tests against real web browsers, but they serve different purposes. Karma is meant for running unit tests against JavaScript code, whereas Protractor is meant for running end-to-end tests against a full, live site like a user. Karma tests go through a “back door” to exercise pieces of a site. Karma and Protractor are not meant to be used together for the same tests (see Protractor Issue #9 on GitHub). However, one project can use both tools at their appropriate test layers, as done for standard Angular testing.
This guide does not provide a custom example for Karma with Jasmine because it requires local setup with the right packages and browser versions. Karma packages are distributed through npm. Karma with Jasmine requires the main karma package, the karma-jasmine package, and a launcher package for each desired browser (like karma-chrome-launcher). There are also plenty of decent examples online here, here, and here. Please refer to the official Karma documentation for more info.
Running Jasmine tests with Karma is not without its difficulties, however. One challenge is handling modules and imports. ECMAScript 6 (ES6) has a totally new syntax for modules and imports that is incompatible with the CommonJS module system with require used by Node.js. Node.js is working on ES6-style module support, but at the time this article was written, full support was not yet available. Module imports are troublesome for Karma because Karma is launched from Node.js (requiring require) but runs in a browser (which doesn’t support require). There are a few workarounds:
- Use RequireJS to load modules.
- Use Browserify to make require work in browsers.
- Use rollup.js to bundle all modules into one to sidestep imports.
- Use Angular with TypeScript, which builds and links everything automatically.
Angular Testing
Angular is a very popular front-end Web framework. It is a complete rewrite of AngularJS and is seen as an alternative to React. One of Angular’s perks is its excellent support for testing. Out of the box, new Angular projects come with config for unit testing with Jasmine/Karma and end-to-end testing with Jasmine/Protractor. It’s easy to integrate other automation tools like Istanbul code coverage or HTML reporting. Standard Angular projects using TypeScript also don’t suffer from the module import problem: imports are linked properly when TypeScript is compiled into JavaScript.
Angular unit tests are written just like any other Jasmine unit tests except for one main difference: the Angular testing utilities. These extra packages create a test environment (a “TestBed”) for testing each part of the Angular app internally and independently. Dependencies can be easily stubbed and mocked using Jasmine’s spies, with no need for sinon since everything binds. NGRX also provides extended test utilities. The Angular testing utilities can seem overwhelming at first, but together with Jasmine, they make it easy to write laser-precise unit tests.
Another interesting best practice for Angular unit tests is to co-locate them with the modules they cover. For every *.js/*.ts file, there should be a *.spec.js/*.spec.ts file with the covering describe/it tests. This is not common practice for unit tests, but the Angular doc notes many advantages: tests are easy to find, coverage is roughly visual, and updates are less likely forgotten. The automatically-generated test config has settings to search the whole project for spec files.
Angular end-to-end tests are treated differently from unit tests, however. Since they test the app as a whole, they don’t use the Angular testing utilities, and they should be located in their own directory (usually named “e2e”). Thus, Angular end-to-end tests are really no different than any other Web UI tests that use Protractor. Jasmine is the default test framework, but it may be advantageous to switch to Cucumber.js for all the advantages of BDD.
This guide does not provide Angular testing examples because the official Angular documentation is stellar. It contains a tutorial, a whole page on testing, and live examples of tests (linked from the testing page).
Automation Panda 