Specalizr

An implementation and platform agnostic, human-readable visual test scenario definition DSL.

What problem does it solve ?

It enables Acceptance test automation.

1. You can now provide your developers with test scenarios at the beginning of a development cycle.

2. Developers can use the test scenarios at any time during the development cycle to verify acceptance. Since test scenarios are human readable, they also serve as documentation.

3. At the end of the cycle the developers deliver features as test scenarios are green.

4. Finally acceptance tests become non-regression tests for further development cycles.

How

• By providing a language that relies on visual description of elements rather than underlying implementation.

• By decoupling scenario description from scenario execution.

• By providing scenario players that understand and execute the language.

A simple example :

Here's a use case involving a unit conversion (using Google unit converter)

        final var leftField = field(leftOf(item(with(text("=")))), below(selector(with(text("Length")))));
        final var rightField = field(rightOf(leftField));
        final var actions = first(click(item(with(text("I agree")))))
                .then(write("unit converter").into(field(above(button(with(text("Google Search")))))))
                .then(press(ENTER))
                .then(select("Mile").from(selector(with(text("Meter")))))
                .then(select("kilometre").from(selector(with(text("Centimeter")))))
                .then(clear(leftField))
                .then(write("50").into(leftField))
                .andLastly(validate(that(rightField), containsText("80.4672")));

        play(actions, with(webPlayer));

Main concepts

Action

A command to be performed on a given element (i.e. press, select, write, clear, ...)

ActionChain

A list of chained actions representing a test scenario

Element

Represents a visual component (i.e. button, select, checkbox, link, text ...)

Query

Describes how to find an element (i.e. with(text("Length")) ... rightOf(item(with(text(...)))))

Player

A component that takes an Action chain and plays it against any given platform (web, mobile, desktop ...)

How to

Define a scenario

Start with the "first" keyword. It will instantiate an ActionChain and will act as a scenario builder.

You can then chain actions aka ActionDefinition by using "then" keyword.

      first(click(item(with(text("I agree")))))
        .then(write("unit converter").into(field(above(button(with(text("Google Search")))))))
        .then(press(ENTER))
        ...
        ...
        .andLastly(validate(that(rightField), containsText("80.4672")));

Execute a scenario

Once you have defined a scenario, you can play it using an ActionDefinitionPlayerRegistry. This registry is responsible for providing players for ActionDefinition instances.

        play(actions, with(seleniumPlayer));

see web/src/test/java/ch.qarts.specalizr.examples package for examples

Extend the framework

New command

In order to create a new command you need to implement ActionDefinition interface

Check api for examples

public class WriteActionDefinition<T extends Writable> implements ActionDefinition 

New element

In order to create a new element you need to extend ElementBase class

Check api for examples

public class Button extends ElementBase implements Clickable 

New query component

In order to create a new query component you need to extend ElementQueryComponent class

Check api for examples

public class TextQueryComponent extends ElementQueryComponent {

Implementations

There is currently a Web implementation available.

Dependencies

In order to make things happen you need to embed the following dependencies :

• API (contains DSL)

        <dependency>
            <groupId>ch.qarts.specalizr</groupId>
            <artifactId>api</artifactId>
            <version>VERSION_HERE</version>
        </dependency>

• Any player (here web player powered by selenium)

        <dependency>
            <groupId>ch.qarts.specalizr</groupId>
            <artifactId>web</artifactId>
            <version>VERSION_HERE</version>
        </dependency>

Credits

Inspired by taiko.dev

License

Specalizr is an open-source project distributed under the MIT license