Deferreds simply let you add multiple callback to long lasting operation calls like Ajax requests.

Long lasting operations without JQuery Deferred
If you haven’t used deferreds, this is probably how you had done long lasting actions like ajax calls.

$.get("/myservice/x/1",function(data,status){alert ('example')})

Long lasting operations like ajax require a callback function.
In this case the callback is given as a parameter to the caller.

This is fine, but there is a way to add a callback separately from the call.

var myPromise = $.get("/myservice/x/1");

myPromise.done(function(data,status){alert ('ok')})
myPromise.fail(function(data,status){alert ('failed')})

Try it

This is actually the simplest example of using Deferreds.
JQuery ajax methods (get,post,ajax…) return an object which you can add callback methods to it.

Why is it better?
Simply because it lets you keep the logic of execution and the logic of the result separated. This makes a more readable and maintainable code.

So what is a ‘Deferred’?
Deferred is an object which lets you add multiple callback methods to it.
It also triggering events which determine the state of the call, using it will determine which callback methods will be triggered.

In the Ajax example above the 2 callbacks are ‘done’ and ‘fail’ which are triggered according to the state of the Ajax call.

This list shows which events will trigger which callbacks.

What is a ‘Promise’?
A Promise is an object which is given from the Deferred and may be used just to add callbacks.

The 2 objects, Deferred and Promise, give us the separation in the logic of the caller and the logic of the result.

For example, in the ajax calls of JQuery, the ajax call creates a Deferred and also a Promise from that Deferred. The Deferred is used to trigger events and the Promise is returned to the user so he will add callback functions to it.

Create your own Deferreds functions
You also can use Deferreds in your function much like the ajax functions are using them.

These are the steps:
1. Create a Deffered inside your function.
2. Use the Deffered to trigger events.
3. Return the Promise object.

See this simple example:

myLongLastingOperation = function(time) {
  var myDeferred = $.Deferred();
  setTimeout(myDeferred.resolve, time);
  return myDeferred.promise();
}

myPromise = myLongLastingOperation(1000);
myPromise.done(function(){alert('ok')})
myPromise.fail(function(){alert('failed')})

Try it

In the example above I have created a function similar to the what ajax function is doing.
I have created a Deferred, used that Deferred to trigger an event by using the resovle() function once the operation was done, and returned the Promise which I created from that Deferred.
The returned promise is then used for adding callbacks.

Progress
resolve() and reject() are both events that determine the status of the result of the operation.
But there is another event you can trigger – notify().
This event which was added in version 1.7 can be triggered if you have a process and you want to trigger a callback while the process is still running.

myLongLastingOperation = function(time,numOfCount) {
 var  myDeferred = $.Deferred();
   
   function wait(counter){
        if(counter<numOfCount){
            myDeferred.notify();
            setTimeout(function(){wait(counter+1)}, time);   
        }   
        else{
             myDeferred.resolve();
        }
    }
   wait(0); 
  return myDeferred.promise();
}

myPromise = myLongLastingOperation(100, 3);
myPromise.progress(function(){document.write('tick')});
myPromise.done(function(){document.write('done')});

Try it

Not impressed yet? Meet ‘when’
We saw that you can add multiple callbacks to Deferreds and Promises.
‘when’ lets you do the same thing but it can do it for multiple Deferreds all at once.

myLongLastingOperation = function(time) {
 var  myDeferred = $.Deferred();
 setTimeout(function(){myDeferred.resolve();}, time);
 return myDeferred.promise();
}


myPromise = $.when( 
    myLongLastingOperation(500),
    myLongLastingOperation(1700));

myPromise.done(function(){document.write('done')});

Try it

In this case the done callback will be triggered only when the 2 processes are resolved.
This gives you the ability to synchronize between many long lasting processes, which can be useful for so many things.
For example, if you are loading many sources and you wish to do something when they are all done.

Changing the result with ‘then’
I mentioned that you can’t trigger events on a Promise, you can only add events to a Promise.
However, you still have a way to control the result in another way; by adding filters to the Promise which will be able to alter the response from the caller.
Since jQuery 1.8 this is done using the ‘then‘ command:

var myPromise = $.get('non_exiting.php');

myPromise = myPromise.then(
    function(){return $.Deferred().resolve("ok")},
    function(){return $.Deferred().resolve("ajax failed but still we pass")});

myPromise.done(function(message){document.write('done: '+message);});
myPromise.fail(function(message){document.write('error: '+message);});

Try it

This example shows that even though the deferred(the ajax) failed, the filter changed the result to resolve, causing the ‘done’ callback to be triggered instead of ‘fail’.
Notice that ‘then’ returns also a promise, this makes it a chainable command, which means that you can chain a more than one filter one after the other.

*Notice, before version 1.8 you would do this using the pipe command, but since 1.8 it is done using ‘then‘.
‘then’ was originally added in version 1.5 as a callback which is triggered on every event.
But since version 1.8 it changed it’s purpose to be a filtering chainable method which can effect the state of the result.
This is why you can still see examples on the web that do it the old way.

Adding a callbacks after event was triggered
You should know that you can add callback functions to a promise even if the Deferred was already resolved or failed.
This means that if you add a callback method to an ajax call for example, that already returned, the callback would immediately be triggered.

This small and seemingly unimportant feature is actually quite useful, because you don’t have to worry that the Deferred is finished when adding callbacks. More over, it lets you add many callbacks whenever you like and by so, reuse deferreds.
A good example for this use would be a cache of ajax calls, this is infact something I have implemented in my workplace(convertro.com) quite successfully.

jQuery Deferred

Since I know JavaScript is considered an OO language, I decided to try to understand once and for all how to implement encapsulation in JavaScript correctly.

Let’s say we have a function with one private field and one public field:

function f1() {
	var x=3; //private	
	this.y=4; //public
}

//alert(x); // error - x is undefined
//alert(y);// error - y is undefined
alert(f1.x); //alert undefined
alert(f1.y); //alert undefined
//alert(f1().x); //error - f1() does not return an object with property x
//alert(f1().y); //error - f1() does not return an object with property y

Try It

The fields are of course undefined since we need to call f1() in order for them to have values.

Now let’s create an object from that function:

var i1 = new f1();

//alert(x); // error 
//alert(y);// error 
alert(i1.x);//alert undefined since it is private
alert(i1.y); //alert 4

Try It

After instancing, x and y both have values, but of course, only y is public.

Now lets encapsulate field x.

function f1() {
	var x=3; //private	
	this.y=4; //public

	this.getX = function(){
		return x;
	}
}

var i1 = new f1();

//alert(x); //error
alert(i1.x); //alert undefined
alert(i1.getX()); //alert 3

Try It

This is the most basic encapsulation and it works.
But this approach has a problem, f1() is in fact a kind of constructor. Whenever an instance will be created than the getter method will also be created.
This approach is not the preferred way to create methods in JavaScript.

The preferred approach in JavaScript is to create the methods attached to the prototype. In this way they will only be created once.

var f1 = function(){
	var x=3; //private	
	this.y=4; //public
}

f1.prototype.getY = function(){
	return y;
}

/* error
f1.prototype.getX = function(){
	return x; //x is not a public field
}
*/

But this approach also has a problem, we cannot use it for private fields.

Let’s consider using a module

f1 = (function (){
	var x=3;

	var module = function (){
		this.getX = function(){
			return x;
		}
	}

	return module;
})();

var i1 = new f1();
alert(i1.x); //undefined
alert(i1.getX()); //3

Try It

There is a function which creates a module with the getter.
But here we have the same problem as the first example, getX() is created for every instance.

The solution is in fact a combination of the previous 2 examples:

f1 = (function (){
	var x=3;

	var module = function (){}
	
	module.prototype.getX = function(){
		return x;
	}

	return module;
})();

var i1 = new f1();

//alert(x); undefined
alert(f1.x); //undefined
alert(i1.getX()); //3

Try It

Here you have a strict encapsulation which is also efficient in memory.

That’s why I have created this Chrome Extension which works great for Hebrew and Arabic.

View on Github

 Download Source code

*Google Calendar is a trademark of Google Inc.

Here is the presentation:

Link to prezi

You can see a great example in github where you click on one of the files.

In this post I am going to explain how this is achieved step by step.

My Demo

Requirements:
For some reason, almost all of the examples I saw on the internet about this used jquery in one way or another.
This post is NOT using any third-party libraries except for history.js script for browsers which do not support the history.pushState feature. I took this script from github.

Step 1 – handle links
We want that pressing a link will trigger a JavaScript function.
You can do that in many ways.
I have done it like this:

	var elements = document.getElementsByTagName('a');
	var address;
	for(var i=0; i<elements.length;i++){
		element=elements[i];
		address=element.getAttribute('href');
		if(address.substring(0,2)=="./"){ //inner links only
			element.setAttribute('onclick','goto("'+address+'",event)');
		}
	}

It will go over all the links in the page and will attach a call to function goto(), but it will do it just for the links which points to inner pages.
The goto() function gets the address of the page and the click event.
In this way you write you link tags as usual.

Step 2 – prevent page redirection
We want that pressing on a link will not cause the web page to be redirected, so we need prevent the default behavior of the click event on the link.
This is how it is done:

theEvent.preventDefault();

Step 3 – load data in Ajax
We now need to get the data that will be refreshed from the server.
There are endless implementations for that.
Here is what I used.

function ajax(page){
	var xmlhttp;
	if (window.XMLHttpRequest)	  {// code for IE7+, Firefox, Chrome, Opera, Safari
	  xmlhttp=new XMLHttpRequest();
	}
	else{// code for IE6, IE5
	  xmlhttp=new ActiveXObject("Microsoft.XMLHTTP");
	}

	xmlhttp.onreadystatechange=function(){
		if (xmlhttp.readyState==4 && xmlhttp.status==200){
			updateText(xmlhttp.responseText); //the method to be called when the data is fetched
		}
	}
	xmlhttp.open("GET","test.php?page="+page,true);
	xmlhttp.send();
}

Of course you will have to put the data on the server. I have used in my example a simple php page which receives the page as a parameter, but you can also use static html files.

Step 4 – update page data in an inner div
After you got the the data from the server you need to print it on the screen.
You can so it simply like this:

document.getElementById('myDiv').innerHTML = theData;

In my example I used an animation which makes things a bit cooler, I will talk about that later on.

Step 5 – push the page to the history
In regular page switch, the new page address is updated in the browser address bar and it also enters the history stack of the browser.
We will imitate this behavior like this:

history.pushState('', pageTitle, pageAddress);

Step 6 – handle history back/forward actions
Now that we have pushed our new fake page to the history stack we also need to be prepared when this fake page is popped from the history.

window.onpopstate = function(event) {
	var currentPage = location.pathname;
	updateContent();
}

Step 7 – handle pages mapping in your server for direct links
You probably also should be prepared for the possibility that users will want to access the inner pages directly.
You can achieve this by simple mapping in your web server.

Optional – add animation
You may chose to add some kind of animation, for example a clock while the data is loaded or some kind of text effect like I have done.
This will make things even cooler.
I have used a typing animation. This is how I have implemented it:

function startAnimation(text){
	clearInterval(start);
	thediv.innerHTML="";
	thetext=text;

	if (document.getElementById||document.all){
		start=setInterval("animation()",20);
	}
	
}
	

function animation(){
	var oldLen = thediv.innerHTML.length;
	var finalLen = thetext.length;
	
	if(oldLen<finalLen){
		thediv.innerHTML=thetext.substring(0,oldLen+1);
	}
}

Existing implementations
You should know that if you wish you can just use one of the existing implemtations on the net.
Here is the very cool implementation by github.

Question: What will happen after executing the next JS code?

function outer(){
	var x=1;
	var inner = function(){
		alert(">"+x);
	}

	x=2;
	return inner;
}

outer();

1. Nothing
2. alert ‘>undefined’
3. alert ‘>1′
4. alert ‘>2′

Answer:
Nothing, because outer() returned a function but it wasn’t executed.

Question: What will happen after executing the next JS code?

function outer(){
	var x=1;
	var inner = function(){
		alert(">"+x);
	}
	x=2;
	return inner;
}

outer()();

1. Nothing
2. alert ‘>undefined’
3. alert ‘>1′
4. alert ‘>2′

Answer:
alert ‘>2′, because the x that inner() uses is the same x the outer() uses.

Question: What will happen after executing the next JS code?

function outer(){
	var x=1;
	var inner = function(x){
		alert(">"+x);
	}
	x=2;
	return inner;
}

outer()();

1. Nothing
2. alert ‘>undefined’
3. alert ‘>1′
4. alert ‘>2′

Answer:
alert ‘>undefined’. Inner uses a variable x which is different than the outer x. The inner x is never initialized

Question: What will happen after executing the next JS code?

function outer(){
	var x=1;
	var inner = function(x){
		alert(">"+x);
	}
	x=2;
	return inner;
}

outer()(3);

By now the answer should be obvious: alert ‘>3′ .

*Let me assured you that even though the directions bellow seems complicated and clumsy at first, after doing them once or twice it is really easy to repeat them.

Motivation
The default action of Clover is to gather code coverage information during build time or compile time. Therefore, This information includes just the coverage data created by unit tests.

If you are developing web applications, you probably use more technologies to test your applications beside unit tests. These technologies may include HTTPUnit/HTMLUnit or automation technologies (like Selenium). These technologies do not work at build time, they can only work during run time, where a web server is up and running and HTTP calls are made.
As a result, the code coverage made during build time is not reflecting the actual code coverage. We should be able to test the coverage while a server is running.

The idea
The idea is that we will first run clover regularly during build time. We will than take the clover artifacts, put them in our server and then run the integration tests.
While running the integration tests, the clover database will be updated and we would be able to generate reports from it which will reflect both unit and integration tests.

Step 1 – Preparation

• Make sure that you have a web/application server (Tomcat/JBoss/weblogic…) with your web application already deployed.
• Execute clover on your application as you would normally do (either by compiling the code on eclipse or by building with Maven or Ant, it doesn’t matter).
  
  The result of this action would be:
  1. Clover DB files.
     One of the outcome of executing the clover on your code are the DB files.
     The DB files hold all the information about your code and the coverage itself.

     The location of those files may change depending on the way you use clover and according to the way you configured clover in your environment.

     This is how the files looks like
     

     

     the .db file holds the information regarding your code (classes, methods and so on). All the other files hold all the coverage data.

     It is important that you will locate those files because we are going to use them in the next step.

  2. An instrumented code.
     Another outcome of clover is that it instruments your code. A clover call is injected into each method so it would be reported in the coverage calculation.
     We will need this code. we will use this instrumented code in runtime to update the coverage data.

     If you use Eclipse than the generated classes would be instrumented. If you use Maven or Ant than most chances are that a jar with all the instrumented code would be generated separately.
     Search the instrument code jar. Again, I can’t tell you exactly where it is located, but usually it generates a jar with a ‘clover’ postfix. Example: if your jar name is my_app.jar, than the generated instrumented code jar will probably be something like my_app-clover.jar.
     So you will need to do some detective work here to find the instrumented classes/jar. If you are not sure whether the classes are instrumented or not, just decompile one of them with Jad and search for the word clover inside of it.

  3. A code coverage report.
     This is a report with the unit test coverage. We don’t really need this, but it would be good so that we would be able to compare it with the report we will generate at the end.

Step 2 – Updating the server
The next steps are very important, please make sure you do them properly.

• Replacing the existing application jar/classes with the instrumented jar/classes.
  Take the instrumented jar/classes that were created by the clover and add it to your server’s classpath instead of the original jar/classes.
  The instrumented code will cause the clover DB to be updated with the runtime data.




• Adding clover jars and license.
  Since we will use clover on runtime we will need also the clover jars in our server’s classpath.
  So add the clover own jars to your server’s classpath. If you are using clover with Eclipse than these jars are located in the plugin folder of Eclipse. If you are using Maven than they will be loacted in your repository.

  * Make sure you are using the same version of clover in your server as you used to generate the DB files and instrumented code, otherwise it will not work and you will get error messages.
  Also add the clover license file to the same location as the jars.




• Adding the clover java argument.
  Add the following java arg -Dclover.initstring.basedir={location of the db files that were created by the clover}.
  *Notice – the path you have entered above is the path of the folder which contains the DB files.
  Example:
  -Dclover.initstring.basedir=C:/workspace/MyWebApp/target/clover.
  This java argument is used by the clover to locate the DB files and update them.

Step 3 – Restarting the server and running the tests
Now that hopefully all is set properly all that you need to do now is to restart your server and than running your integration tests.
The tests should trigger the instrumented code which will call the clover API’s and will update the clover DB.

While running the tests:
1. Look at your log/console and search for error messages from clover.
2. Look at the folder which holds the clover DB files. If everything is going as it should, new files will be created in this folder while running the tests.

If not everything is going well the first time, don’t discourage, just go over each of the steps again.

Step 4 – Generating an updated report
If everything went well and new files were created in the DB folder than that means you just need to generate a new report.
If you are using clover with eclipse than you can simply push the reload button to reload the coverage data.
If you are using Maven or Ant you can execute just the task which generates the report.
Another way is to use the clover HtmlReporter to generate a report easily.

Now compare the new report to the old report. You should see that the new report coverage is much bigger than the old one since it contains also the integration tests coverage.

*Notice that not all the data is updated, even though the percentages are being updated, for some reason the calls counter does not.

To summarize. As mentioned; yes, these instructions seems a bit complicated but after you succeed the first time, it is very easy to repeat it. In the company I work for we even made this whole process automatic and we are able to generate a full coverage report with unit and integrated tests combined.

To create a customized animation you need to follow these 3 steps.
For the explanation, we will create a simple animation that changes the background of a button gradually from black to red.

Step 1 – Extend the Animation class and set the properties
Create a class which extends Android Animation class.
This class will hold the logic of your animation.
See my example:

public class BGColorAnimation extends Animation {
	
	private View view;
	private int currentRedColor;
	
	//The steps to skip between colors
	private static int STEP_SIZE=30;  
	private static int ANIMATION_DURATION=50;

	public BGColorAnimation(View view) {
		this.view=view;
		setDuration(ANIMATION_DURATION);
		setRepeatCount(255/STEP_SIZE);
		setFillAfter(true);
		setInterpolator(new AccelerateInterpolator());
		
		setAnimationListener(new MyAnimationListener());
	}
}

• As you see, there is not much in this class since my animation is not that complicated.
• Notice that I have made all the necessary animation parameters initialization from inside the constructor, but you can defiantly initialize them from outside the class.
• There are 2 important parameters which determines the behavior of the animation:
  1. RepeatCount – the number of steps this animation has.
  2. Duration – the sleep time between 2 steps.
• On each step, the animation listener will be triggered.

Step 2 – Implement AnimationListener interface
Create a class which implements Animation.AnimationListener.
As mentioned, it is triggered on each animation step.

class MyNumbersAnimationListener implements AnimationListener{
	    	private int index;

	    	@Override
		public void onAnimationEnd(Animation animation) {
			
		}

		@Override
		public void onAnimationRepeat(Animation animation) {
			// Change color of the view
			view.setBackgroundColor(
				Color.rgb(currentRedColor+=STEP_SIZE, 0, 0));
		}

		@Override
		public void onAnimationStart(Animation animation) {
			view.setBackgroundColor(Color.BLACK);
			currentRedColor=0;
		}
		
	}
	  

In fact, I see no reason why not doing both steps in the same class:

public class BGColorAnimation extends Animation implements
		Animation.AnimationListener {

	private View view;
	private int currentRedColor;

	// The steps to skip between colors
	private static int STEP_SIZE= 30;
	private static int ANIMATION_DURATION = 50;

	public BGColorAnimation(View view) {
		this.view = view;
		setDuration(ANIMATION_DURATION);
		setRepeatCount(255 / STEP_SIZE);
		setFillAfter(true);
		setInterpolator(new AccelerateInterpolator());

		setAnimationListener(this);
	}

	@Override
	public void onAnimationEnd(Animation animation) {

	}

	@Override
	public void onAnimationRepeat(Animation animation) {
		view.setBackgroundColor(
			Color.rgb(currentRedColor += STEP_SIZE, 0, 0));
	}

	@Override
	public void onAnimationStart(Animation animation) {
		view.setBackgroundColor(Color.BLACK);
		currentRedColor = 0;
	}

}

Step 3 – Start the animation from a view
Animations are triggered from a view.
Example:

Button button = (Button)findViewById(R.id.b_colors);
button.setOnClickListener(new OnClickListener() {
				
				@Override
				public void onClick(View v) {
					button.startAnimation(new BGColorAnimation(button));
				}
			});

Download demo project

To answer these questions I have made a simple test and ran it as a java program on my PC and than as an Android activity.

Here is the test for the PC:

 private static final int SIZE_OF_ARRAY = 10000000;
	private static long time;

	
	public static void main(String[] args) {

		        Integer [] sourceArray = new Integer[SIZE_OF_ARRAY];
		        Integer [] destinationArray = new Integer[SIZE_OF_ARRAY];
		        fillArray(sourceArray);
		        
		        startBenchmark();
		        naiveCopy(sourceArray,destinationArray);
		        stopBenchmark();
		        
		        startBenchmark();
		        System.arraycopy(sourceArray, 0, destinationArray, 0,
						  sourceArray.length);
		        stopBenchmark();
		    }



			private static void naiveCopy(Integer [] src, Integer [] dst) {
				for (int i = 0; i < src.length; i++) {
					dst[i]=src[i];
				}
				
			}

			private static void fillArray(Integer [] src) {
				for (int i = 0; i < src.length; i++) {
					src[i]=i;
				}
				
			}
			
			private static void startBenchmark() {
				time = System.currentTimeMillis();
			}
			
			private static void stopBenchmark() {
				time = System.currentTimeMillis() - time;
				System.out.println( "time="+time);
				
			}

Here are the results while running it from my PC (java 7, 8GB memory, CPU intel i5):
Naive algorithm – 14 ms
System.arraycopy(); – 6 ms.

Arraycopy does the task in less than half of the time.

Now to use it on Android – here is the code:

public class ArrayCopyTestActivity extends Activity {
    private static final int SIZE_OF_ARRAY = 1000000;
	private long time;

	/** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
        
        Integer [] sourceArray = new Integer[SIZE_OF_ARRAY];
        Integer [] dst = new Integer[SIZE_OF_ARRAY];
        fillArray(sourceArray);
        
        startBenchmark();
        naiveCopy(sourceArray,dst);
        stopBenchmark();
        
        
       
        startBenchmark();
        System.arraycopy(sourceArray, 0, dst, 0, sourceArray.length);
        stopBenchmark();
    }



	private void naiveCopy(Integer [] src, Integer [] dst) {
		for (int i = 0; i < src.length; i++) {
			dst[i]=src[i];
		}
		
	}

	private void fillArray(Integer [] src) {
		for (int i = 0; i < src.length; i++) {
			src[i]=i;
		}
		
	}
	
	private void startBenchmark() {
		time = System.currentTimeMillis();
	}
	
	private void stopBenchmark() {
		time = System.currentTimeMillis() - time;
		Log.d("array copy test", "time="+time);
		
	}
}

* Notice I have reduced the size of the Array from 10 million to 1 million, this is due to restrictions on memory for applications in Android.

The results from running it on my device (nexus 1):
Naive algorithm – 182 ms
System.arraycopy(); – 12 ms.

This means that the fact that System.arraycopy() is better than the regular copy is even more true for Android.
In short than, always use System.arraycopy() especially on Android.

Test for PC
Test for Android

Simple Example

@Test
public void testGoogle(){
	WebClient webClient = new WebClient();
	HtmlPage currentPage = webClient.getPage("http://www.google.com/");
	assertEquals("Google", currentPage.getTitleText());
}

WebClient

• As you can see in the example, the WebClient is the starting point. It is the browser simulator.
• WebClient.getPage() is just like typing an address in the browser. It returns an HtmlPage object.

HtmlPage

• HtmlPage represents a single web page along with all of it’s client’s data (HTML, JavaScript, CSS …).
• The HtmlPage lets you access to many of a web page content:

Page source

• You can receive the page source as text or as XML.

HtmlPage currentPage = 
		webClient.getPage("http://www.google.com/");
String textSource = currentPage.asText();
String xmlSource = currentPage.asXml();

HTML Elements

• HtmlPage lets you ability to access any of the page HTML elements and all of their attributes and sub elements. This includes tables, images, input fields, divs or any other Html element you may imagine.
• Use the function getHtmlElementById() to get any of the page elements.

WebClient webClient = new WebClient();
HtmlPage currentPage = webClient.getPage("http://www.google.com/");
HtmlImage imgElement = (HtmlImage)currentPage.getHtmlElementById("logo");
System.out.println(imgElement.getAttribute("src"));

Anchors

• Anchor is the representation of the Html tag <a href=”…” >link</a>.
• Use the functions getAnchorByName(), getAnchorByHref() and getAnchorByText() to easily access any of the anchors in the page.

WebClient webClient = new WebClient();
HtmlPage currentPage = webClient.getPage("http://www.google.com/");
HtmlAnchor advancedSearchAn = 
		currentPage.getAnchorByText("Advanced Search");
currentPage = advancedSearchAn.click();
assertEquals("Google Advanced Search",currentPage.getTitleText());

Dom elements by XPath

• You can access any of the page elements by using XPath.

WebClient webClient = new WebClient();
HtmlPage currentPage = 
	webClient.getPage("http://www.google.com/search?q=avi");
 
//Using XPath to get the first result in Google query
HtmlElement element = (HtmlElement)currentPage.getByXPath("//h3").get(0);
DomNode result = element.getChildNodes().get(0);

Form control

• A large part of controlling your HTML page is to control the form elements:
  • HtmlForm
  • HtmlTextInput
  • HtmlSubmitInput
  • HtmlCheckBoxInput
  • HtmlHiddenInput
  • HtmlPasswordInput
  • HtmlRadioButtonInput
  • HtmlFileInput

WebClient webClient = new WebClient();
HtmlPage currentPage = webClient.getPage("http://www.google.com/");
 
//Get the query input text
HtmlInput queryInput = currentPage.getElementByName("q");
queryInput.setValueAttribute("aviyehuda");
 
//Submit the form by pressing the submit button
HtmlSubmitInput submitBtn = currentPage.getElementByName("btnG");
currentPage = submitBtn.click();

Tables

currentPage = webClient.getPage("http://www.google.com/search?q=htmlunit");
final HtmlTable table = currentPage.getHtmlElementById("nav");
for (final HtmlTableRow row : table.getRows()) {
System.out.println("Found row");
    for (final HtmlTableCell cell : row.getCells()) {
       System.out.println("   Found cell: " + cell.asText());
    }
}

JavaScript support

• HtmlUnit uses the Mozilla Rhino JavaScript engine.
• This lets you the ability to run pages with JavaScript or even run JavaScript code by command.

ScriptResult result = currentPage.executeJavaScript(JavaScriptCode);

• By default JavaScript exceptions will crash your tests. If you wish to ignore JavaScript exceptions use this:

webClient().setThrowExceptionOnScriptError(false);

• If you would like to turn off the JavaScript all together, use this:

currentPage.getWebClient().setJavaScriptEnabled(false);

HTTP elements

URL

WebClient webClient = new WebClient();
HtmlPage currentPage = 
	webClient.getPage("http://www.google.co.uk/search?q=htmlunit");
URL url = currentPage.getWebResponse().getRequestSettings().getUrl()

Response status

WebClient webClient = new WebClient();
HtmlPage currentPage = webClient.getPage("http://www.google.com/");
assertEquals(200,currentPage.getWebResponse().getStatusCode());
assertEquals("OK",currentPage.getWebResponse().getStatusMessage());

Cookies

Set<Cookie> cookies = webClient.getCookieManager().getCookies();
for (Cookie cookie : cookies) {
	System.out.println(cookie.getName() + " = " + cookie.getValue());
}

Response headers

WebClient webClient = new WebClient();
HtmlPage currentPage = 
	webClient.getPage("http://www.google.com/search?q=htmlunit");

List<NameValuePair> headers = 
	currentPage.getWebResponse().getResponseHeaders();
for (NameValuePair header : headers) {
	System.out.println(header.getName() + " = " + header.getValue());
}

Request parameters

List<NameValuePair> parameters = 
	currentPage.getWebResponse().getRequestSettings().getRequestParameters();
for (NameValuePair parameter : parameters) {
	System.out.println(parameter.getName() + " = " + parameter.getValue());
}

Making assertions

• HtmlUnit comes with a set of assetions:

   assertTitleEquals(HtmlPage, String)
   assertTitleContains(HtmlPage, String)
   assertTitleMatches(HtmlPage, String)
   assertElementPresent(HtmlPage, String)
   assertElementPresentByXPath(HtmlPage, String)
   assertElementNotPresent(HtmlPage, String)
   assertElementNotPresentByXPath(HtmlPage, String)
   assertTextPresent(HtmlPage, String)
   assertTextPresentInElement(HtmlPage, String, String)
   assertTextNotPresent(HtmlPage, String)
   assertTextNotPresentInElement(HtmlPage, String, String)
   assertLinkPresent(HtmlPage, String)
   assertLinkNotPresent(HtmlPage, String)
   assertLinkPresentWithText(HtmlPage, String)
   assertLinkNotPresentWithText(HtmlPage, String)
   assertFormPresent(HtmlPage, String)
   assertFormNotPresent(HtmlPage, String)
   assertInputPresent(HtmlPage, String)
   assertInputNotPresent(HtmlPage, String)
   assertInputContainsValue(HtmlPage, String, String)
   assertInputDoesNotContainValue(HtmlPage, String, String)

• You can still of course use the framework’s assertions. For example, if you are using JUnit, you can still use assertTrue() and so on.
• Here are a few examples:

WebClient webClient = new WebClient();
HtmlPage currentPage = 
      webClient.getPage("http://www.google.com/search?q=htmlunit");
 
assertEquals(200,currentPage.getWebResponse().getStatusCode());
assertEquals("OK",currentPage.getWebResponse().getStatusMessage());
WebAssert.assertTextPresent(currentPage, "htmlunit");
WebAssert.assertTitleContains(currentPage, "htmlunit");
WebAssert.assertLinkPresentWithText(currentPage, "Advanced search");
assertTrue(currentPage.getByXPath("//h3").size()>0); //result number
assertNotNull(webClient.getCookieManager().getCookie("NID"));

See also

• Product main page
• Download page
• Jar dependencies

 Download example