Tutorial

Tutorial: the DuckDuckGo example

Subject

We’ll present a test for the DuckDuckGo search engine. If you don’t know it, it is like Google, but it doesn’t track you. The point here is that they also have a nice disambiguation feature: the “Zero Click Info” box.

Let’s imagine we are engineers at DuckDuckGo, and we want to test whether a Zero Click Info box comes up for an ambiguous request: “Toto”.

Are we looking for the band? The footballer? The African textile vendor? The result page should help the user narrow down his search.

Scenario

Based on the above requirements, we can formalize the following testing scenario:

1. Go to duckduckgo.com.
2. Type “Toto” in the search field.
3. Submit the research form.
4. Ensure that a box with “Meanings of Toto” is presented to the user.

Files

Download the DuckDuckGo example and open it in your file browser.

We see a config file, two Widget files, a Feature and a Data file. Those are all the components of a Watai test. This walkthrough will examine them in more details.

Configuration

The config file exports a hash with two mandatory key-value pairs:

• baseURL, that describes the URL at which the test should start.
• browser, that defines which browser should be used to run the test.

If your Firefox browser is stored in an unusual location, now might be a good time to specify its path in the firefox_binary key of the driverCapabilities hash, too :)

Widgets

DOM mapping: Elements

As we’ve seen earlier, DOM mapping is mandatory at some point… but it should be centralized. That’s mostly what a Widget is: the definition of a set of elements on web pages. A mapping from DOM elements, identified through selectors, to testing-environment attributes.

Open the ZeroClickWidget file: it is simply a hash containing another hash named elements. And here is our header definition, as an element. We will now be able to use it to retrieve the content of that header and check whether it matches the expected one.

Semantic behaviors: Actions

However, Widgets are a bit more than simple mapping repositories. Indeed, interface components in webapps are not only sets of elements. They can also offer complex actions to the user, that are triggered by combining basic actions (clicks, text input…) across their elements.

Widgets also abstract these behaviors and make them callable directly, with a meaningful name instead of repeating a series of basic actions that carry no meaning.

Open the SearchBarWidget file: there is once again the elements hash, but there’s also an action defined: the searchFor key is a Javascript function that takes a parameter and sequences different basic steps. With this action, we will be able to search for an ambiguous term, as our scenario needs.

Features

So, we have now defined all needed elements and actions for our scenario. However, we have not yet told how those pieces fit together, nor what exactly we are going to check. This is defined in Features. Let’s look at the 1 - ZeroClickFeature file.

Test definition: Description

Just like a Widget, a Feature is a hash, except that it has two mandatory keys instead of one.

To present what feature (expected behavior) you are testing exactly, associate a string to the description key. It is usually a good idea to write a sentence with “should” in it, or you can go all the way to BDD-style with a “Given-When-Then”.

Test sequence: Scenario

The second expected key in a Feature is scenario. Its value must be an array.

The first line is simply a call to the action we defined in the SearchBarWidget: we are going to searchFor a term, LookupTerm (we’ll explain a bit later where it comes from, consider it defined). The only potentially tricky thing to note is that the referenced function is not to be called directly (()), and that parameters are listed as array items.

You can define as many steps in a scenario as you want, a step being, like here, an action and its parameters, or a custom function, or a state definition.

Assertions: State definitions

So, with scenario steps, we know how to define sequences of actions that our widgets are to execute in a given order and with particular parameters. But we still don’t know how to actually assert something, and we’re going to need it if we want to check behavior!

Assertions in Watai are implicit. That is, you won’t have to assert anything (unless you want to): you’ll simply define an expected state, and the actual state of the current web page will be checked against it.

A state definition is simply a hash where keys reference some Widgets’ elements, and the corresponding values are expected content of the given element.

The only tricky thing is that you cannot have an actual reference as a key, only a string. So, remember to quote the keys when defining states.

Naming

You may have noticed the 1 - prefix of the feature filename. Such indices are needed for Watai to determine dependencies. Currently, there is no support for complex dependencies, so your test suite has to be a linear scenario. To make that scenario explicit, feature filenames have to be prefixed with their index.

This also means you can quickly exclude a feature from being evaluated by renaming it to something like x4 - MyFourthFeature.js, without anything else. Indices don't have to be continuous, i.e. you may have features 1, 2, 3 and 5 without any harm.

Data

You might have wondered where the lookupTerm variable comes from. Open the ZeroClickData file: here it is!

Using data files to store values is optional, but it is recommended as a way to decouple concerns even more. In our example, if we wanted to test another ambiguous term, there’s absolutely no hesitation where to go define it: simply open the data file, replace "Toto" with the new term, start the test.

Executing the suite

To run a test suite, simply use watai and pass it paths to folders containing your config, widgets, data, and features files.

The following assumes you have Firefox installed. If not, do it now. If you don’t want to install Firefox, read how to test with Chrome, for example.

watai path/to/downloaded/Watai-DuckDuckGo-example/

➥ If there’s any problem (did you start the Selenium server?), don’t despair and check the troubleshooting guide, there should be an easy fix :)

Conclusion

Ok, this was a small test suite, but it was enough to see all components of one with Watai!

You could try to create your own test suite, using the DuckDuckGo example and keeping the PDC example (download it) nearby to see more complex uses. You could also try to run the example with Chrome.

If you’re still not sure about Watai or where it should fit in your development process, check out the rationale.

If you found something wrong / frustrating / poorly written in this introduction, please fork and create a pull request or create an issue :)

Go back home.