In the Gemfile of that application, add the following:

group :development, :test do
  gem 'konacha'
end

With that structure in place, we just need to run bundle install to install the Konacha gem, and we should be good to go.

To test that this setup works the way we expect, let’s write a simple class and a test for it.

In app/assets/javascripts, create a new file called greeter.js.coffee. In that file, let’s create a class called Greeter that has a function sayHello. The sayHello function will take a name argument and respond with a string that greets that name.

# app/assets/javascripts/greeter.js.coffee
class @Greeter
  sayHello: (name) ->
    "Hello #{name}!"

Now let’s create a simple test to assert that sayHello does what we expect it to do. By default, Konacha expects all tests to be in the spec/javascripts folder. (This can be reconfigured if you prefer a different location.) The default location works just fine for me. In the spec/javascripts directory (you’ll probably need to create these folders), create a new file called greeter_spec.js.coffee. Another default of Konacha is that tests must end with _spec. This requirement follows the RSpec style of determining what is or isn’t a test.

# spec/javascripts/greeter_spec.js.coffee
#= require application
describe "Greeter", ->
  it "says hello", ->
    greeter = new Greeter()
    greeter.sayHello("Mark").should.eql("Hello Mark!")

If you’ve seen or written RSpec tests, this test should be fairly familiar. If not, the gist of what’s happening is that we’re requiring the application.js file from the asset pipeline, which by default includes our greeter.js.coffee file. It then sets up a test and asserts that the sayHello function behaves correctly.

Running the Test Suite

With the test written, all that’s left to do is run it, in one of two ways. The first is in the browser. To do that, we can start the server with which Konacha ships:

$ rake konacha:serve

That command starts a server on port 3500. If you then navigate to http://localhost:3500, you should be greeted with a screen that looks simple and clean.

Congratulations! You have written and run your very first JavaScript/CoffeeScript test.

When we go to http://localhost:3500, it will run the entire test suite we’ve written—in this case, just the one test. However, if we want to run just this one file, we can do it by visiting http://localhost:3500/greeter_spec.

Running the test suite is really fast, but often it’s nice to be able to run the specs in the background, using a tool such as Guard, or as part of your continuous integration server. To do this, we can run the following rake task:

$ rake konacha:run

Depending on how your system is configured, when you ran that command the Firefox browser should have launched and then quickly disappeared. Why? Because we’re testing JavaScript, we need a JavaScript environment in which we can execute the test suite, so the rake task launches a browser, runs the tests, exits the browser, and prints something similar to the following to your terminal window:

Finished in 3.51 seconds
1 examples, 0 failures

Unfortunately, having Firefox popping up continually while you’re trying to work isn’t very nice. This also won’t work on continuous integration servers that most likely don’t have Firefox installed. How do we solve this problem? We need to install a headless web browser.

Going Headless

A headless web browser doesn’t have a GUI, hence the name “headless.” Think of this as a somewhat-virtual web browser. It can display web pages, and most importantly run our test suite, but it can do it all from the terminal window.

Several great headless web browsers are out there, but my personal favorite is PhantomJS. It’s very easy to install and works great—two of the main bullet points I want in a product like this.

After installing PhantomJS, we need to install the Poltergeist gem, which contains the driver that will let us hook our tests into the PhantomJS headless browser:

# Gemfile
group :development, :test do
  gem 'konacha'
  gem 'poltergeist'
end

Don’t forget to run bundle install after you’ve added the Poltergeist gem to the Gemfile.

All that’s left to do is configure Konacha to use Poltergeist and PhantomJS. In the config/initializers directory, create a new file called konacha.rb:

# config/initializers/konacha.rb
if defined?(Konacha)
  require 'capybara/poltergeist'
  Konacha.configure do |config|
    config.driver = :poltergeist
  end
end

In this file, we’re requiring the driver that Poltergeist gives us (require 'capybara/poltergeist') and telling Konacha to use that driver (config.driver = :poltergeist).

When we run rake konacha:run this time from the terminal window, the test suite should run without Firefox appearing. Perfect!

If you want to run individual specs from the command line, Konacha lets you do it like this:

$ rake konacha:run SPEC=greeter_spec