Make unit tests great again – Integrate Jasmine into Rails

Install Jasmine To make Jasmine available to your Rails app, you just have to place the jasmine-gem (link) in your Gemfile. That will do the magic. Just make sure you have it under Development and Test group in the Gemfile as follows:

group :development, :test do
  gem "jasmine"
end
Then run this to install the gem:
bundle install
After all the gems are installed, run this code to generate necessary files for Jasmine to run:
rails generate jasmine:install
This will create the jasmine helper file and the yml file where you configure how it should run the tests.

Run tests

You can use Jasmine right after it’s installed. It can be run in several ways, the most important ones being,
  1. In your browser
  2. Continuous Integration Mode (CI)
The CI mode is usually used when you have to integrate it into your build system.

Browser Mode

You have to start the Jasmine server to run it in a browser. This server runs all the tests and serves the results to a webpage. Run this to start the Jasmine Server:
rake jasmine
With the default settings, you can view the output in:
http://localhost:8888/
But this page would be pretty empty since you don’t have any tests written for your Javascript code. There is a method provided to generate sample tests. Try running this:
rails generate jasmine:examples
Now refresh the webpage and you can see something similar to this: Jasmine test page

Configurable Settings

Clicking on the options button in the top right corner will display a list of options that change how Jasmine runs the tests. Let’s get into each one of them:

Raise Exceptions

This option disables the error catching mechanism of Jasmine in the JavaScript source code and in the test file. The default setting is to wrap all the errors in a catch block.

Stop Spec on Expectation Failure

With this option turned on, Jasmine will stop the test at the first occurrence of an error. The default setting is to run the full test suit and then display all the tests which fail.

Run Tests in Random Order

This option enables the test to be run in a random sequence every time the test runs. The benefit of enabling this option is to reveal dependencies between tests, therefore, you can reduce test dependencies and each test will have good isolation.

Continous Integration Mode

A headless browser is used to integrate Jasmine into your continuous integration workflow. To make our lives easier, this gem that we are using supports integration with a headless browser out of the box. The default headless browser is Phantom JS. So it will download automatically if not installed when you try to run in CI mode. Run this code to run in CI mode:
rake jasmine:ci
By default, Jasmine will attempt to find a random open port. To set a default port manually, just add this to the jasmine_helper.rb
Jasmine.configure do |config|
   config.ci_port = 1234
end

Configuration

The two files which you should be looking into, if you need to alter the behavior of tests are:
  • jasmine.yml
  • jasmine_helper.rb
Jasmine reads the jasmine.yml first and then overrides it with the settings mentioned in jasmine_helper.rb

Sample configuration:

# spec/javascripts/support/jasmine.yml
random: true
show_console_log: false
stop_spec_on_expectation_failure: true
# spec/javascripts/support/jasmine_helper.rb
Jasmine.configure do |config|
  config.random = false
  config.show_console_log = false
  config.stop_spec_on_expectation_failure: false
  config.show_full_stack_trace = false
  config.prevent_phantom_js_auto_install = false
end

Testing

Writing tests for Javascript in a Rails app should be fairly straightforward as it uses same standards as Jasmine in general. But there are things that need to be considered specific to a Jasmine installation in Rails.

Testing JavaScript

Test files for JavaScript in a rails application reside in the spec/javascripts folder. For each javascript file, you need to put the test file in the same path as the file. For example, if you have the following javascript file in your app: app/assets/javascripts/jasmine_examples/Calculator.js You place the spec file in the following path: spec/javascripts/jasmine_examples/CalculatorSpec.js Jasmine will include the test on the next test run. There is no configuration to have your test run.

Plugins worth considering

  • Jasmine-Jquery – this plugin provides a lot of jquery related matchers. Download it here
  • Jasmine-Matchers – a tool to provide additional matchers. Download it here
  • Jasmine-Fixture – a plugin that provides DOM creation using CSS selectors, therefore you can interact with the DOM much easier. Download it here

Write Beautiful Unit tests

95% of the developers I know write unit tests in order to prevent defects from being deployed to production. But the essential ingredients to a great unit test is unknown to most of them. There have been countless times that I’ve seen a test fails, only to investigate and discover that I have no idea what feature the developer was trying to test, let alone how it went wrong or why it matters.

Importance of Test Discipline

Your tests are the best set of weapons to defend your code from bugs. They are more important that linting and static analysis. A few reasons why tests are your secret weapon:
  • Writing tests first gives you a clearer perspective on the ideal API design.
  • Does the developer understand the problem enough to articulate in code all critical component requirements?
  • Manual QA is error-prone. In my experience, it’s impossible for a developer to remember all features that need testing after making a change to refactor, add new features, or remove features.
  • Continous Integration prevents failed builds from getting deployed to production.

Bug Report vs plain Unit Test

The test fail report comes to save your life when a test fails. So you better make it loud and clear. I came up with a list of must-have info in your bug report.
  • What are you trying to test?
  • What should it do?
  • What is the real-time output (actual behavior)?
  • What is the expected output (expected behavior)?
Here is a sample test with all of these info:
describe("CalculatorAddMethod", function() {
  var calculator = new Calculator();
  it("should return number", function() {
    const actual = typeof Calculator.add(5,10);
    const expected = 'number'
    expect(actual).toEqual(expected);
  });
});
This test suit answers all the questions above. Let’s go through each one of them.
  • What are you trying to test?
    • -> Go for the test description. It is testing for the return type of the add method of Calculator().
  • What should it do?
    • -> Again, look at the test description. It clearly says that it is testing for the return type of add method.
  • What is the actual output?
    • -> There is a dedicated variable which holds the actual result and how you got the actual result. TWO FOR ONE!
  • What is the expected output?
    • -> Again, there is a dedicated variable which holds the actual result. Straight as a ruler!

Make your tests even better

This is from my experiences and the knowledge I gained from good articles. This worked for me in the long run even if I find it a little difficult to implement when I started. Write every single test using toEqual(). Don’t worry about the quality impact on your test suit. It will get better with exercise.

Easter Egg

This method I suggested would answer one more question, which is by far the most important question I guess. How can you reproduce the test? The const actual holds the answer to this question. Please go take a look at the variable in my sample test suit above and get delighted.

Conclusion

Integrating Jasmine into your Rails app is done by the jasmine-gem. This gem gives you the ability to run tests in a browser or as Continous Integration mode. The usage of right plugins will improve your productivity and helps you write tests faster and better. Next time you write a test, remember to see if your test answers the following questions:
  • What are you trying to test?
  • What should it do?
  • What is the real-time output (actual behavior)?
  • What is the expected output (expected behavior)?
  • How can be the test reproduced?
]]>