JavaScript Tests

Why JavaScript Tests (aka functional tests)

Tests not executing JavaScript can only go so far. They can only validate HTML elements and the general page structure. They can be imagined much like a browser with JavaScript disabled or you viewing the source of the the webpage (tryCTRL+U).

The time came when Tom wrote the first bits of JavaScript for our soon-to-be workshop portal. In his quest for 100% code coverage and following our ideals to test every single bit of code we write, he thought about how to test the freakin' JavaScript. This is when he introduced Poltergeist and PhantomJS - a test driver able to use a headless (read: invisible) webbrowser to access pages like a normal user would, and most importantly, execute JavaScript.

Poltergeist? PhantomJS?

Poltergeist 👻

Poltergeist is a a test driver for Capybara, the acceptance test framework we use for our tests inside the features folder. What's different about Poltergeist compared to the default test driver we use for our tests? Well, Poltergeist is using PhantomJS to open pages in a somewhat real webbrowser and as such - surprise - is able to execute JavaScript.

PhantomJS

PhantomJS is a headless WebKit scriptable with a JavaScript API. It has fast and native support for various web standards: DOM handling, CSS selector, JSON, Canvas, and SVG.

PhantomJS can be used for a variety of tasks which involve the need for a modern headless browser with JavaScript support that can be controlled from the command line. In our case it is used to execute the functional tests which require JavaScript. To give an example, the visit '/hello' methods will cause PhantomJS to navigate to this page just like a real browser would.

How to write your own JavaScript test

Simply add js: true to the scenario or it block of your test. Here's an example:

scenario "logged in as Pupil I cannot see notes", js: true do
  visit '/some-path'
end

Why you should write as few Javascript tests as possible

As you can imagine, spinning up a headless browser, executing JavaScript and rendering the page takes significantly longer than just calling some Rails functions and evaluating the plain HTML code.

Installation and setup

You will need to run bundle install regardless of your environment and whether or not you actually want to execute the functional tests to install the Poltergeist gem and it's dependencies. This is all you need to get your tests up and running again. However, you will not be able to run the JavaScript tests if you don't read on.

This is when you also need to install PhantomJS. For those of you using the Vagrant box, a simple vagrant reload --provision is sufficient to install PhantomJS. For those of you not using Vagrant, follow Tom's initial installation instructions:

Ubuntu: apt-get install phantomjs

Mac: brew install phantomjs

Windows: https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-1.9.8-windows.zip

If you encounter problems, detailed instructions can be found here: https://github.com/teampoltergeist/poltergeist

Troubleshooting

• A bunch of tests fail and you receive Could not find cliver-0.3.2 in any of the sources when running them: Executebundle install
• A bunch of tests fail and there is no Run options: exclude {:js=>true} right after you type rspec: You don't have the latest changes from dev in your branch. Execute git fetch and git merge dev.
• A bunch of tests fail although you have installed PhantomJS and you receive an error coming directly from it: Your development configuration might not be able to handle PhantomJS's headless browser. Nils reported it wouldn't work for him in Bash on Windows. Consider to ask me or Google, or, at last resort, uninstalling PhantomJS to skip the tests.