Get Started

This ain’t Selenium

Before we get to the interesting stuff, installation, APIs and all these important things, please take 5 minutes, grab a nice cup of coffee or tea & let me tell you why I started this massive pile of code in the first place.

Back in December 2012, I was working on a few web apps (you could call them single page apps, if you feel buzzwordy), for a yet unreleased big web platform. For the first time in my career, I had the opportunity to work with a testing team, people who would test the things that I've programmed 8 to 10 hours a day. And yes, they tested, they tested the hell out of my code, spotted bugs I had never encountered, even if I would have been really keen on testing my stuff (I wasn't, and by the way, if that reads like a christmas carol, it's just you - it was mid July when I wrote this).
But week after week, the applications changed, and the code changed, and the code produced side effects, and sometimes, some old really well tested feature broke. Nobody noticed until some of our "friendly test users" (or even worse, stakeholders) reported an issue. Embarassing, a shame, an affront to my (Klingon like) programmer honor, but hey, we all heard of this testing framework Selenium, right?! Some tool that promises to make us stop worry about this & instead lets us write an automated testcase once, and magically replaying it everytime we want. Maybe after every commit, maybe every night, we didn't care as long as our CI server greets us with a green light every morning, everything should be fine. So our testers began writing tests, in Java, because that was the language that we're taught to do so back in the days in university. And yes, we had tests, 100, 200, 300, ... and so on. In the end, they had written around 500 to 600 tests. We ran them twice a day, against Chrome & before the end of sprint, we ran them in various other browsers, too.

They worked, they worked by the time they were written & they mostly stopped working when we changed something in our existing codebase (agile development FTW!). So what needed to be done, when we changed our code, behaviour, markup, whatever of an already tested feature? Our testers needed to change the tests accordingly. So we were 8 developers and 2 testers in our team, naturally, they couldn't keep up with the changes, the CI Servers always showed us failing tests (you stop worrying about the "build failed" mails after some months, believe me), basically our complete test automation suite was useless (oh, jUnit, I kinda miss your 300 lines long stacktraces, when a <h1> tag was missing *sniff*).
So, we as a group (6 JavaScript devs/2 Web Designers/2 Testers) decided that we developers should change the Selenium tests when we change the underlying codebase, and yes we tried (have you ever heard the joke about the 6 javascript devs trying to change Java code, written by two "non programmers", no?, good, because it isn't funny at all). In the end we kinda gave up, too much time & effort spend on writing the tests, we needed to speed up with feature implementations & the shame came back (Oh, I felt so dishonored).

The process we've been through made me think, how should such a tool represent itself to the developers, how can it be "a nobrainer" for web developers, for the people who build what you see in the internetz, the frontend devs, for everyone?! I came to the conclusion that only JavaScript can be considered as a "common knowledge programming language" in web land.
Also the setup process for running the tools that ran the Selenium tests (Java jrde*whatever, Maven, Ant, jUnit, Eclipse, etc.) was a major pain point in my opinion, I wan't it to be as easy as installing a tool via npm.
So my dear reader, here we are now, introducing a new testing tool for your Webpages, one that hopefully makes you love testing, one that holds your hand instead of pushing you away, one that makes you wanna contribute to it...

Okay, just one more thing, DalekJS was born in battle, full of blood & anger and therefore is buggy as hell & not ready for production yet.
Only you can make it better, report bugs as you never ever reported before, send pull requests that will make me sleepless merging them, discuss in the mailing list about what you wan't. This aint Selenium, this is DalekJS, this is your tool.

Installation

Dalek's installation is pretty forward, just make sure you have Node.js installed. If you don't have Node installed, just go to nodejs.org & follow the instructions of the graphical installer.

With node comes a handy package management tool called `npm`. You can verify, if the installation succeeded when you open your command line & type

$ npm --version

then you should see some output like this

$ 1.1.62

where the version number depends on your installed version of Node.

If that worked, you should be able to install DalekJS.
Dalek is split up in a few different parts, to get it working initially, you first have to install the "Dalek Command Line Tools", this is as easy as typing

$ npm install dalek-cli -g

in your command line.
Verify that the installation worked by checking with

$ dalek -v

You should see something like this

$ DalekJS CLI Tools Version: 0.0.1
  Brought to you with love by: Sebastian Golasch (@asciidisco) 2013

Awesome, you're one step closer to the finish line, next up, you need to add a package.json file to your projects root directory, if you haven't one already. You can start with the bare minimum of that file, which should look something like this:

{
  "name": "myCssTardis",
  "description": "Is awesome",
  "version": "0.0.2"
}

Hah, you "nodyfied" project & I guess, now that you learned to love the command line, you would really like to go back & hack!? Great, then the next step is something for you, we install the Dalek base framework & all its dependencies with a one liner that looks like this:

$ npm install dalekjs --save-dev

Guess what?! That was it. You installed DalekJS you old command line hero, if you want to verify, that the local installation worked, you can, again, ask Dalek in which version it is running, because now, it will also tell you the version number of your local Dalek installation:

$ dalek -v

You should see something like this

$ DalekJS CLI Tools Version: 0.0.1
  DalekJS local install: 0.0.1
  Brought to you with love by: Sebastian Golasch (@asciidisco) 2013

Write your first test

Okay command line cowboys & cowgirls, it is time to write our first test!
And, because I don't know your pages & sites, I think we should test something we all know, yes it is time to use our old friend Google again! In this test, we will verify that the <title> element from Google’s homepage has the correct value.
The test we need to write, to make this happen, looks like this:

module.exports = {
'Page title is correct': function (test) {
  test
    .open('http://google.com')
    .assert.title().is('Google', 'It has title')
    .done();
}
};

Now, lets save this file as 'my_first_test.js' in a folder called 'test'. Everything wrapped in the object literal called `module.exports` is a test suite. It can contain hundreds of single test functions just like the one that we created. Each test function gets an argument, conventionally called `test`. This `test` variable is your interface to Dalek's functions.

So what does this test do? It's quite simple really!

It opens a browser (PhantomJS by default), points to Google, and after the browser has finished loading, we `assert` that the `title` of the page is `Google`. The second argument of the `is` method allows you to label your tests. This makes it easy to identify which are failing. Finally, to tell Dalek that we are done with this test, we call the `done` method. That is it, your first test is ready! Hurrah!

Run your tests

So far so good, we learned why Dalek is awesome, installed dalek, we wrote our first test & now it is time to really get some timey-wimey action started. Go back to our new friend, the command line, go back to your project folder & simply type:

$ dalek test/my_first_test.js

Awesome, now just hit return & experience the Dalek magic for the first time. It all worked well, if you end up with some output like this:

Running tests
Running Browser: Phantomjs
RUNNING TEST - "Page title is correct"
▶ OPEN http://google.com
✔ TITLE It has title
✔ 1 Assertions run
✔ TEST - "Page title is correct" SUCCEEDED
1/1 assertions passed. Elapsed Time: 2 sec

Add user interactions

Wow, we came that far in such a short amount of time. Isn't it awesome? I believe it is =)

This chapter adds some information on how to simulate a real user, in Daleks context, such method calls are called 'actions'. You already issued an action when telling the browser to `open` a page. One of the things you will be using most are the `click` & `type` actions.

Click simulates a user clicking on an element (most of the time, it will be a link, but you can select any element you want to click on it).
Type lets you enter data into a form field.

To explain this actions in more detail, we will write a little test that checks if the Amazons search field on the homepage is working as we expect:.

module.exports = {
'Amazon does its thing': function (test) {
  test
    .open('http://www.amazon.com/')
    .type('#twotabsearchtextbox', 'Blues Brothers VHS')
    .click('.nav-submit-input')
    .waitForElement('#result_0')
    .assert.text('#result_0 .newaps a span').is('The Blues Brothers')
    .done();
}
};

Cool, we just simulated a real user interacting with a webpage, now lets take this thing a step further & add a 'real' browser, that your regular users will use.

Add a "real" browser

After struggling with tons of blog posts & documentation on how to setup browsers for Selenium & Watir, I just wanted to have a really simple & sane way to add a browser to your testing suite:

$ npm install dalek-browser-chrome --save-dev

Yep, that was it, now you can call your testsuite with an additional parameter & you´re good to go.

$ dalek test/my_first_test.js -b chrome

Create a report

We are about to finish our little DalekJS crash course with this chapter, I´m very proud of you still reading the guide. In this last step we will install a reporter that will help you store the results of your test run. There are several reporters available, but we will use the HTML reporter here. This reporter will generate a set of static HTML pages & store that in a folder on your disk. Of course, the installation is as easy as always, just:

$ npm install dalek-reporter-html --save-dev

Cool, now just add another parameter to your `dalek` call

$ dalek test/my_first_test.js -r console,html

This will create a new folder for you, called "report/dalek", in there you will find an `index.html` with all the information from your test run.

You? Still here? You are my hero, now lets go ahead & write some useful tests for your application. Happy testing & when you still have some questions, check the Docs or ping me via IRC, Twitter, Github or mail.