Assertions API

We believe that the most valuable part of a test are its assertions. Clear and concise assertions makes your tests better and help to understand what is broken when, after some refactoring, a test written months ago turns red.

That's why gwt-test-utils has to provide an API to write understandable assertions on GWT component as easily as possible.

A fest-assert extension for Widgets

fest-assert is an amazing library to substitute JUnit or TestNG assertions. Once you start using it, you can't go back.
That's why we decided implement a GwtAssertions utilities class based on Assertions to provide the same comfort for writing and the same level of feedback whenever an assertion fails. See by yourself :

with JUnit assertions :

Assert.assertTrue(view.button.isAttached());
Assert.assertTrue(view.button.isVisible());
Assert.assertTrue(view.button.isEnabled());
Assert.assertEquals("my button", view.button.getText());

with gwt-test-utils assertions :

GwtAssertions.assertThat(view.button).isAttached().isVisible().isEnabled().textEquals("my button");

Quite a time saver, isn't it ? Moreover, the code completion offered by any Java IDE will remember you all the assertions available for the widget to verify so you could easily chain those which make sense for your test.

The default feedback message is also improved. For example, if it turns out the button is actually not attached, let's see what you'd get :

with JUnit assertions :

java.lang.AssertionError:

with gwt-test-utils assertions :

java.lang.AssertionError: [Button] should be attached

_**Note:** We strongly recommend importing the `com.googlecode.gwt.test.assertions.GwtAssertions.assertThat()` method statically (see [How to do this easily in Eclipse](http://piotrjagielski.com/blog/working-with-static-imports-in-eclipse/))._

Extending the Assertions API

You may want to write assertThat methods for your own custom widgets. The GwtAssertions API has been designed to be easily extended.

For each XxxAssert class in gwt-test-utils, you will find a corresponding BaseXxxAssert template class where every Xxx specific assertion methods are implemented.

Assuming you wrote a CustomTextBox which a some validation state to the standard TextBox:

public class CustomTextBox extends TextBox {

  private boolean valid;
  
  public boolean isValid() {
    return valid;
  }
  
  public void setValid(boolean valid) {
    this.valid = valid;
  }

}

You may want to add a isValid() method to the existing TextBoxAssert provided by gwt-test-utils. To do so,

1. Write a CustomTextBoxAssert that extends BaseTextBoxAssert :

public class CustomTextBoxAssert extends BaseTextBoxAssert<CustomTextBoxAssert, CustomTextBox> {

  protected CustomTextBoxAssert(CustomTextBox actual) {
    super(actual, CustomTextBoxAssert.class);
  }
  
  public CustomTextBoxAssert isNotValid() {
    if (!actual.isValid())
      return this;
    
    throw failWithMessage("should not be valid");
  }
  
  public CustomTextBoxAssert isValid() {
    if (actual.isValid())
      return this;
      
    throw failWithMessage("should be valid");
  }

}

2. XxxAssert should not be instanciable (constructor is declared protected). The best practice is to provide a custom Assertions class in the same package to act like an assertThat factory for each custom XxxAssert types :

public class CustomAssertions {
  
  public static CustomTextBoxAssert assertThat(CustomTextBox actual) {
    return new CustomTextBoxAssert(actual);
  }

}

Using this new assertThat method, you'll be able to chain the isValid() method with other assertion methods implemented in BaseTextBoxAssertand its super classes.

The base class for every XxxAssert type is GwtGenericAssert, where you'll find some uselfull helper methods to build assertion errors, like failWithMessage we used in the sample.