Sneferu - Web Integration Testing Library for CUBA

Add-ons
,
#1

Hi,

I developed a Library for web integration testing in CUBA: Sneferu.

Sneferu is a testing library to simplify web integration testing for a CUBA application. It consists of a couple of APIs that allows you to express interactions and verifications with UI screens via a dedicated high-level testing language.

The current version is 0.2.0 and it is available for CUBA 7.2.x

You can find out more about it here: GitHub - mariodavid/sneferu: CUBA Platform Web Integration Testing Library

If you have any feedback for me about this library, feel free to answer in the topic or just reach out to me :slight_smile:

Attached you’ll find a primer of the documentation:

Sneferu

Sneferu is a testing library to simplify web integration testing for a CUBA application.
It consists of a couple of APIs that allows you to express interactions and verifications with UI screens via a dedicated high-level testing language.

Overview

Instead of spending too much time and money maintaining a selenium test suite, Sneferu is the way
to have very good test coverage and quality assurance at a fraction of the cost.

Via its easy to read the language you can create integration tests that are optimized for readability,
because this is what matters most for keeping a test suite maintainable & cheap to operate.

Using Sneferu it enables you to:

  • verify any business logic in a Screen Controller
  • ensure the correct linking between Screen XML and its Controller counterpart
  • verify correct display of any programmatic creation of Screen Components / Dialogs
  • emulate & verify data loading
  • emulate & verify Service Interface interactions

As Sneferu is based on the web integration test facilities of CUBA, there is a certain limitation in what areas are not covered. In particular, Sneferu relies on the abstractions provided by the CUBA and Vaadin component interfaces. It assumes that behind this interface everything “works as expected”.

What does Sneferu not cover:

  • End-to-End data loading and displaying on a Screen
  • End-to-End Service execution (middleware)
  • Client-Side Vaadin UI logic that is executed only in the browser

Sneferu Landscape

sneferu-overview
sneferu-overview1384Ă—1584 150 KB

If you can live with those trade-offs feel free to join the lovely world of web integration testing in CUBA expressed though a beautiful API.

Motivation & Background

Testing of a CUBA application on the web layer previously consists of two extremes:

  1. write a unit test for the business logic in the screen controllers
  2. write a functional UI test that executes the application through the browser

Both of those extremes have their downsides.

The first one requires to mock out every programmatic interaction with the CUBA UI interfaces. Also, unit tests do not cover any of the screen layout definitions or the data binding of a Screen.

Selenium-based UI testing, on the other hand, is much more black-box, slower, more brittle and overall harder to maintain. It can achieve a higher degree of confidence that the application behaves as it is supposed to be, as it exercises the application almost as the user does. But this trade-off is a very expensive one.

To mitigate that problem CUBA 7.1 introduced web integration testing.

Sneferu is taking that new addition and brings it to the next level by making it accessible and very easy to use.

The documentation shows all test cases written in Spock, but Sneferu works with different testing frameworks like JUnit as well.

An example test case in Sneferu looks like this:

public class VisitBrowseToEditTest {

  @Test
  public void aVisitCanBeCreated_whenAllFieldsAreFilled(
      @StartScreen StandardLookupTestAPI<Visit,VisitBrowse> visitBrowse,
      @SubsequentScreen StandardEditorTestAPI<Visit, VisitEdit> visitEdit,
      @NewEntity Pet pikachu
  ) {

    // given:
    pikachu.setName("Pikachu");

    // and:
    visitBrowse.interact(click(button("createBtn")));

    // when:
    OperationResult outcome = (OperationResult) visitEdit
        .interact(enter(dateField("visitDateField"), new Date()))
        .interact(enter(textField("descriptionField"), "Regular Visit"))
        .interact(select(lookupField("petField"), pikachu))
        .andThenGet(closeEditor());

    // then:
    assertThat(outcome).isEqualTo(OperationResult.success());

    // and:
    assertThat(environment.getUiTestAPI().isActive(visitEdit))
      .isFalse();

  }
}

Getting Started

To use Sneferu, it is required to add the dependency to the CUBA project. In the build.gradle the following dependency has to add to the web-module:

configure(webModule) {
    // ...
    dependencies {
        testCompile('de.diedavids.sneferu:sneferu:**SNEFERU-VERSION**')
    }
}

…

Sneferu can be used with JUnit as well as Spock. Just add the corresponding dependencies into your CUBA project to use it with either of those frameworks.

Afterward, you can create your first web integration test:

import de.diedavids.sneferu.UiTestAPI

import static de.diedavids.sneferu.ComponentDescriptors.*
import static de.diedavids.sneferu.Interactions.*


class FirstSneferuSpec extends Specification {

    @Shared
    @ClassRule
    SneferuTestUiEnvironment environment =
            new SneferuTestUiEnvironment(TestImprovementsWebTestContainer.Common.INSTANCE)
                    .withScreenPackages(
                            "com.haulmont.cuba.web.app.main",
                            "com.rtcab.ddceti.web.screens.customer"
                    )
                    .withUserLogin("admin")
                    .withMainScreen(MainScreen)


    def "click a button, open a screen, enter some values and close the screen"() {

        given:
        def customerBrowse = environment.uiTestAPI.openStandardLookup(Customer, CustomerBrowse)

        when:
        customerBrowse
                .interact(click(button("createBtn")))

        and:
        environment.uiTestAPI.getOpenedEditorScreen(CustomerEdit)
                .interact(enter(textField("nameField"), "Bob Ross"))
                .andThenGet(closeEditor())

        then:
        environment.uiTestAPI.isActive(customerBrowse)
    }
}

Instead of using com.haulmont.cuba.web.testsupport.TestUiEnvironment a Sneferu specific environment is used: de.diedavids.sneferu.environment.SneferuTestUiEnvironment

This environment-class has an additional parameter, that needs to be provided: withMainScreen(), where the Main Screen of the application is configured.

Example Usage

A dedicated example of using Sneferu is shown via the CUBA Petclinic sample application: cuba-platform/cuba-petclinic-using-sneferu.

It contains a lot of example test cases that show the various usage options of Sneferu.

Documentation

All information can be found in the README of the project.

3 Likes