Actions

Actions are a way to control your browsers, e.g. simulate user interactions like clicking elements, open urls, filling out input fields, etc.

.query

It can be really cumbersome to repeat selectors all over when performing multiple actions or assertions on the same element(s). When you use the query method (or its alias $), you're able to specify a selector once instead of repeating it all over the place.

So, instead of writing this:


 test.open('http://doctorwhotv.co.uk/')
     .assert.text('#nav').is('Navigation')
     .assert.visible('#nav')
     .assert.attr('#nav', 'data-nav', 'true')
     .click('#nav')
     .done();
 

you can write this:


 test.open('http://doctorwhotv.co.uk/')
     .query('#nav')
       .assert.text().is('Navigation')
       .assert.visible()
       .assert.attr('data-nav', 'true')
       .click()
     .end()
     .done();
 

Always make sure to terminate it with the end method!

.$

Alias of query

.toFrame

Switches to an iFrame context

Sometimes you encounter situations, where you need to drive/access an iFrame sitting in your page. You can access such frames with this method, but be aware of the fact, that the complete test context than switches to the iframe context, every action and assertion will be executed within the iFrame context. Btw.: The domain of the IFrame can be whatever you want, this method has no same origin policy restrictions.

If you wan't to get back to the parents context, you have to use the toParent method.


 <div>
   <iframe id="login" src="/login.html"/>
 </div>
 


  test.open('http://adomain.withiframe.com')
    .assert.title().is('Title of a page that embeds an iframe')
    .toFrame('#login')
      .assert.title().is('Title of a page that can be embedded as an iframe')
    .toParent()
    .done();
 

> NOTE: Buggy in Firefox

.toParent

Switches back to the parent page context when the test context has been switched to an iFrame context


 <div>
   <iframe id="login" src="/login.html"/>
 </div>
 


  test.open('http://adomain.withiframe.com')
    .assert.title().is('Title of a page that embeds an iframe')
    .toFrame('#login')
      .assert.title().is('Title of a page that can be embedded as an iframe')
    .toParent()
    .assert.title().is('Title of a page that embeds an iframe')
    .done();
 

> NOTE: Buggy in Firefox

.toWindow

Switches to a different window context

Sometimes you encounter situations, where you need to access a different window, like popup windows. You can access such windows with this method, but be aware of the fact, that the complete test context than switches to the window context, every action and assertion will be executed within the chosen window context. Btw.: The domain of the window can be whatever you want, this method has no same origin policy restrictions.

If you want to get back to the parents context, you have to use the toParentWindow method.


 <div>
   <a onclick="window.open('http://google.com','goog','width=480, height=300')">Open Google</a>
 </div>
 


  test.open('http://adomain.com')
    .assert.title().is('Title of a page that can open a popup window')
    .toWindow('goog')
      .assert.title().is('Google')
    .toParentWindow()
    .done();
 

> NOTE: Buggy in Firefox

.toParentWindow

Switches back to the parent window context when the test context has been switched to a different window context


 <div>
   <a onclick="window.open('http://google.com','goog','width=480, height=300')">Open Google</a>
 </div>
 


  test.open('http://adomain.com')
    .assert.title().is('Title of a page that can open a popup window')
    .toWindow('goog')
      .assert.title().is('Google')
    .toParentWindow()
    .assert.title().is('Title of a page that can open a popup window')
    .done();
 

> NOTE: Buggy in Firefox

.screenshot

Take a screenshot of the current page.

The pathname argument takes some placeholders that will be replaced Placeholder:

  • :browser - The browser name (e.g. 'Chrome', 'Safari', 'Firefox', etc.)
  • :version - The browser version (e.g. '100', '2311_5', etc.)
  • :os - The operating system (e.g. OSX, Windows, Linux)
  • :osVersion - The operating system version (e.g XP, 7, 10_8, etc.)
  • :viewport - The current viewport in pixels (e.g. w1024_h768)
  • :timestamp - UNIX like timestapm (e.g. 637657345)
  • :date - Current date in format MMDDYYYY (e.g. 12_24_2013)
  • :datetime - Current datetime in format MMDDYYYYHHmm_ss (e.g. 12_24_2013_14_55_23)

    
    // creates 'my/folder/my_file.png'
    test.screenshot('my/folder/my_file');
    // creates 'my/page/in/safari/homepage.png'
    test.screenshot('my/page/in/:browser/homepage');
    // creates 'my/page/in/safari_6_0_1/homepage.png'
    test.screenshot('my/page/in/:browser_:version/homepage');
    // creates 'my/page/in/safari_6_0_1/on/osx/homepage.png'
    test.screenshot('my/page/in/:browser_:version/on/:os/homepage');
    // creates 'my/page/in/safari_6_0_1/on/osx_10_8/homepage.png'
    test.screenshot('my/page/in/:browser_:version/on/:os_:osVersion/homepage');
    // creates 'my/page/at/w1024_h768/homepage.png'
    test.screenshot('my/page/at/:viewport/homepage');
    // creates 'my/page/at/637657345/homepage.png'
    test.screenshot('my/page/in_time/:timestamp/homepage');
    // creates 'my/page/at/12_24_2013/homepage.png'
    test.screenshot('my/page/in_time/:date/homepage');
    // creates 'my/page/at/12_24_2013_14_55_23/homepage.png'
    test.screenshot('my/page/in_time/:datetime/homepage');
    

.wait

Pause steps suite execution for a given amount of time, and optionally execute a step on done.

This makes sense, if you have a ticker for example, tht scrolls like every ten seconds & you want to assure that the visible content changes every ten seconds


 test.open('http://myticker.org')
   .assert.visible('.ticker-element:first-child', 'First ticker element is visible')
   .wait(10000)
   .assert.visible('.ticker-element:nth-child(2)', 'Snd. ticker element is visible')
   .wait(10000)
   .assert.visible('.ticker-element:last-child', 'Third ticker element is visible')
   .done();
 
If no timeout argument is given, a default timeout of 5 seconds will be used


 test.open('http://myticker.org')
   .assert.visible('.ticker-element:first-child', 'First ticker element is visible')
   .wait()
   .assert.visible('.ticker-element:nth-child(2)', 'Snd. ticker element is visible')
   .wait()
   .assert.visible('.ticker-element:last-child', 'Third ticker element is visible')
   .done();
 

.reload

Reloads current page location.

This is basically the same as hitting F5/refresh in your browser


 test.open('http://google.com')
   .reload()
   .done();
 

.forward

Moves a step forward in browser's history.

This is basically the same as hitting the forward button in your browser


 test.open('http://google.com')
   .open('https://github.com')
   .assert.url.is('https://github.com/', 'We are at GitHub')
   .back()
   .assert.url.is('http://google.com', 'We are at Google!')
   .forward()
   .assert.url.is('https://github.com/', 'Back at GitHub! Timetravel FTW')
   .done();
 

.back

Moves back a step in browser's history.

This is basically the same as hitting the back button in your browser


 test.open('http://google.com')
   .open('https://github.com')
   .assert.url.is('https://github.com/', 'We are at GitHub')
   .back()
   .assert.url.is('http://google.com', 'We are at Google!')
   .forward()
   .assert.url.is('https://github.com/', 'Back at GitHub! Timetravel FTW');
   .done();
 

.click

Performs a click on the element matching the provided selector expression.

If we take Daleks homepage (the one you're probably visiting right now), the HTML looks something like this (it does not really, but hey, lets assume this for a second)


 <nav>
   <ul>
     <li><a id="homeapge" href="/index.html">DalekJS</a></li>
     <li><a id="docs" href="/docs.html">Documentation</a></li>
     <li><a id="faq" href="/faq.html">F.A.Q</a></li>
   </ul>
 </nav>
 


 test.open('http://dalekjs.com')
     .click('#faq')
     .assert.title().is('DalekJS - Frequently asked questions', 'What the F.A.Q.')
     .done();
 

By default, this performs a left click. In the future it might become the ability to also execute a "right button" click.

> Note: Does not work correctly in Firefox when used on <select> & <option> elements

.submit

Submits a form.


 <form id="skaaro" action="skaaro.php" method="GET">
   <input type="hidden" name="intheshadows" value="itis"/>
   <input type="text" name="truth" id="truth" value=""/>
 </form>
 


 test.open('http://home.dalek.com')
     .type('#truth', 'out there is')
     .submit('#skaaro')
     .done();
 

> Note: Does not work in Firefox yet

.open

Performs an HTTP request for opening a given location. You can forge GET, POST, PUT, DELETE and HEAD requests.

Basically the same as typing a location into your browsers URL bar and hitting return.


 test.open('http://dalekjs.com')
     .assert.url().is('http://dalekjs.com', 'DalekJS I\'m in you')
     .done();
 

.type

Types a text into an input field or text area. And yes, it really types, character for character, like you would do when using your keyboard.


 <form id="skaaro" action="skaaro.php" method="GET">
   <input type="hidden" name="intheshadows" value="itis"/>
   <input type="text" name="truth" id="truth" value=""/>
 </form>
 


 test.open('http://home.dalek.com')
     .type('#truth', 'out there is')
     .assert.val('#truth', 'out there is', 'Text has been set')
     .done();
 

You can also send special keys using unicode.

  • 
    test.open('http://home.dalek.com')
     .type('#truth', 'out \uE008there\uE008 is')
     .assert.val('#truth', 'out THERE is', 'Text has been set')
     .done();
    
    You can go here to read up on special keys and unicodes for them (note that a code of U+EXXX is actually written in code as \uEXXX).

    > Note: Does not work correctly in Firefox with special keys

.sendKeys

This acts just like .type() with a key difference. This action can be used on non-input elements (useful for test site wide keyboard shortcuts and the like). So assumeing we have a keyboard shortcut that display an alert box, we could test that with something like this:


 test.open('http://home.dalek.com')
     .sendKeys('body', '\uE00C')
     .assert.dialogText('press the escape key give this alert text')
     .done();
 

> Note: Does not work correctly in Firefox with special keys

.answer

Types a text into the text input field of a prompt dialog. Like you would do when using your keyboard.


 <div>
   <a id="aquestion" onclick="this.innerText = window.prompt('Your favourite companion:')">????</a>
 </div>
 


  test.open('http://adomain.com')
     .click('#aquestion')
     .answer('Rose')
     .assert.text('#aquestion').is('Rose', 'Awesome she was!')
     .done();
 

> Note: Does not work in Firefox & PhantomJS

.execute

Executes a JavaScript function within the browser context


  test.open('http://adomain.com')
     .execute(function () {
       window.myFramework.addRow('foo');
       window.myFramework.addRow('bar');
     })
     .done();
 

You can also apply arguments to the function


  test.open('http://adomain.com')
     .execute(function (paramFoo, aBar) {
       window.myFramework.addRow(paramFoo);
       window.myFramework.addRow(aBar);
     }, 'foo', 'bar')
     .done();
 

> Note: Buggy in Firefox

.waitFor

Waits until a function returns true to process any next step.

You can also set a callback on timeout using the onTimeout argument, and set the timeout using the timeout one, in milliseconds. The default timeout is set to 5000ms.


  test.open('http://adomain.com')
     .waitFor(function () {
       return window.myCheck === true;
     })
     .done();
 

You can also apply arguments to the function, as well as a timeout


  test.open('http://adomain.com')
     .waitFor(function (aCheck) {
       return window.myThing === aCheck;
     }, ['arg1', 'arg2'], 10000)
     .done();
 

> Note: Buggy in Firefox

.accept

Accepts an alert/prompt/confirm dialog. This is basically the same actions as when you are clicking okay or hitting return in one of that dialogs.


 <div>
   <a id="attentione" onclick="window.alert('Alonsy!')">ALERT!ALERT!</a>
 </div>
 


  test.open('http://adomain.com')
     // alert appears
     .click('#attentione')
     // alert is gone
     .accept()
     .done();
 

> Note: Does not work in Firefox & PhantomJS

.dismiss

Dismisses an prompt/confirm dialog. This is basically the same actions as when you are clicking cancel in one of that dialogs.


 <div>
   <a id="nonono" onclick="(this.innerText = window.confirm('No classic doctors in the 50th?') ? 'Buh!' : ':(') ">What!</a>
 </div>
 


  test.open('http://adomain.com')
     // prompt appears
     .click('#nonono')
     // prompt is gone
     .dismiss()
     .assert.text('#nonono').is(':(', 'So sad')
     .done();
 

> Note: Does not work in Firefox & PhantomJS

.resize

Resizes the browser window to a set of given dimensions (in px). The default configuration of dalek opening pages is a width of 1280px and a height of 1024px. You can specify your own default in the configuration.


 <div>
   <span id="magicspan">The span in the fireplace</span>
 </div>
 

`css #magicspan { display: inline; }

// @media all and (max-width: 500px) and (min-width: 300px) #magicspan { display: none; } `


  test.open('http://adomain.com')
     .assert.visible('#magicspan', 'Big screen, visible span')
     .resize({width: 400, height: 500})
     .assert.notVisible('#magicspan', 'Small screen, no visible span magic!')
     .done();
 

> Note: Does not work in Firefox

.maximize

Maximizes the browser window.


 <div>
   <span id="magicspan">The span in the fireplace</span>
 </div>
 

`css #magicspan { display: inline; }

#magicspan { display: none; } } `


  test.open('http://adomain.com')
     .resize({width: 400, height: 500})
     .assert.notVisible('#magicspan', 'Small screen, no visible span magic!')
     .maximize()
     .assert.visible('#magicspan', 'Big screen, visible span')
     .done();
 

> Note: Does not work in Firefox and PhantomJS

.setCookie

Sets a cookie. More configuration options will be implemented in the future, by now, you can only set a cookie with a specific name and contents. This will be a domain wide set cookie.


  test.open('http://adomain.com')
      .setCookie('my_cookie_name', 'my=content')
      .done();
 

.waitForElement

Waits until an element matching the provided selector expression exists in remote DOM to process any next step.

Lets assume we have a ticker that loads its contents via AJAX, and appends new elements, when the call has been successfully answered:


 test.open('http://myticker.org')
   .assert.text('.ticker-element:first-child', 'First!', 'First ticker element is visible')
   // now we load the next ticker element, defsult timeout is 5 seconds
   .waitForElement('.ticker-element:nth-child(2)')
   .assert.text('.ticker-element:nth-child(2)', 'Me snd. one', 'Snd. ticker element is visible')
   // Lets assume that this AJAX call can take longer, so we raise the default timeout to 10 seconds
   .waitForElement('.ticker-element:last-child', 10000)
   .assert.text('.ticker-element:last-child', 'Me, third one!', 'Third ticker element is visible')
   .done();
 

.setValue

Fills the fields of a form with given values.


 <input type="hidden" value="not really a value" id="ijustwannahaveavalue"/>
 


 test.open('http://dalekjs.com')
     .setValue('#ijustwannahaveavalue', 'a value')
     .title().is('DalekJS - Frequently asked questions', 'What the F.A.Q.');
 

.log.dom

Logs a part of the remote dom


 <body>
   <div id="smth">
     <input type="hidden" value="not really a value" id="ijustwannahaveavalue"/>
   </div>
 </body>
 


 test.open('http://dalekjs.com/guineapig')
     .log.dom('#smth')
     .done();
 

Will output this:


  DOM: #smth <input type="hidden" value="not really a value" id="ijustwannahaveavalue"/>
 

.log.message

Logs a user defined message


 test.open('http://dalekjs.com/guineapig')
     .execute(function () {
       this.data('aKey', 'aValue');
     })
     .log.message(function () {
       return test.data('aKey'); // outputs MESSAGE: 'aValue'
     })
     .done();
 

'Normal' messages can be logged too:


 test.open('http://dalekjs.com/guineapig')
     .log.message('FooBar') // outputs MESSAGE: FooBar
     .done();