How to upgrade your tests from Watai 0.5 to 0.6
===============================================

Widgets
-------

We'll start with the following widget with 0.5.2 deprecated syntax, and walk step by step to convert it to the 0.6 syntax:

```javascript
// RegistrationWidget.js with Watai v0.5
{
	elements: {
		nameField:    { css             : '.register input[name=surname]' },
		submitButton: { partialLinkText : 'register' }
	},

	addUser: function addUser(name) {
		this.nameField = name;
		return this.submit();
	}
}
```


### WD API in actions

A very important change in Watai 0.6 is the switch to [`wd`](https://github.com/admc/wd) as the underlying WebDriver control library.
This means your actions have to be updated to use `wd`'s API.

- The deprecated assignation syntax to set fields is now completely removed, in order to bring full [Promises](http://wiki.commonjs.org/wiki/Promises/A) compatibility. You will need to use setters: `this.field = value` → `this.setField(value)().then(function(field) { … })`. Note the double call on `setField`.
- **The first action call in a promises chain has to be called twice.**
- **You need to `return` from all actions**, as they are all promises and need to be chained for proper ordering.
- Magically-generated actions, which you should have most of anyway, already comply with all these prerequisites and can be used directly in a promises chain.

The widget above now looks like:

```javascript
{
	elements: {
		nameField:    { css             : '.register input[name=surname]' },
		submitButton: { partialLinkText : 'register' }
	},

	addUser: function addUser(name) {
		return this.setNameField(name)()   // note the double call
		           .then(this.submit());   // magically-generated action: clicks on `submitButton`
		                                   // simply call it in the promise chain
	}
}
```

> Switching to `wd` improves reliability, tests speed and provides a [much larger API](https://github.com/admc/wd#readme) for you to use in actions.


### Enclosing curly braces

The enclosing curly braces have been removed. They are not optional, they **have to** be removed.

[This gist](https://gist.github.com/MattiSG/6462784) automates enclosing curly braces removal, so you don't have to update this part of your suites manually  :)
[Download it](https://gist.github.com/MattiSG/6462784/download) and execute it, passing it the path to your test suite. Only Widget and Feature files will be modified.

```javascript
elements: {	// no more indentation needed!
	nameField:    { css             : '.register input[name=surname]' },
	submitButton: { partialLinkText : 'register' }
},

addUser: function addUser(name) {
	return this.setNameField(name)()
	           .then(this.submit());
}
```

_A test that is not properly updated would throw `SyntaxError: Unexpected token {`._

> This change, along with the following ones, will make writing new widgets much shorter.


### `elements` hash

The `elements` hash does not exist anymore, all element definitions are flattened and mixed with the actions definitions.

```javascript
nameField:    { css             : '.register input[name=surname]' },	// list elements at root
submitButton: { partialLinkText : 'register' },

addUser: function addUser(name) {
	return this.setNameField(name)()
	           .then(this.submit());
}
```

_A test that is not properly updated would throw `SyntaxError: Unexpected identifier`._

> This will both save some nesting and ensure you don't inadvertently clash names.


### `partialLinkText` locator type

The `partialLinkText` locator type has been renamed to the much shorter `a`.

```javascript
nameField:    { css : '.register input[name=surname]' },
submitButton: { a   : 'register' },	// shorter

addUser: function addUser(name) {
	return this.setNameField(name)()
	           .then(this.submit());
}
```

> You may also use the full `partial link text` type if you prefer being explicit.


### Locators default to `css` type _(optional)_

Since CSS selectors are so common, you can now skip mentioning `css` altogether, and simply write a string to locate an element.

```javascript
nameField:    '.register input[name=surname]',	// only a string
submitButton: { a: 'register' }

addUser: function addUser(name) {
	return this.setNameField(name)()
	           .then(this.submit());
}
```

> The previous syntax is still working, so you can definitely stop refactoring your widgets at the previous step.


Features
--------

We'll start with the following feature with 0.5.2 deprecated syntax, and walk step by step to convert it to the 0.6 syntax:

```javascript
// RegistrationFeature.js with Watai v0.5
{
	description: 'A user can create her new username',

	scenario: [
		{
			'LoginField.userName': false
		},
		RegistrationWidget.addUser(username),
		{
			'LoginField.userName': username,
			'StatsWidget.userCount': 1
		},
	]
}
```


### Enclosing curly braces

The enclosing curly braces have been removed. They are not optional, they **have to** be removed.

[This gist](https://gist.github.com/MattiSG/6462784) automates enclosing curly braces removal, so you don't have to update this part of your suites manually  :)
[Download it](https://gist.github.com/MattiSG/6462784/download) and execute it, passing it the path to your test suite. Only Widget and Feature files will be modified.

```javascript
description: 'A user can create her new username',	// list at root

scenario: [
	{
		'LoginField.userName': false
	},
	RegistrationWidget.addUser(username),
	{
		'LoginField.userName': username,
		'StatsWidget.userCount': 1
	},
]
```

_A test that is not properly updated would throw `SyntaxError: Unexpected token {`._

> This uniforms Features with Widgets and simplifies their syntax.


### Content matchers are triggered by strings only

In state assertions, content matchers have to be strings. Notably, numbers have to be enclosed in strings.

```javascript
description: 'A user can create her new username',

scenario: [
	{
		'LoginField.userName': false
	},
	RegistrationWidget.addUser(username),
	{
		'LoginField.userName': username,
		'StatsWidget.userCount': '1'	// look out for numbers from data files too
	},
]
```

_A string that is not properly updated would throw a `TypeError: No matcher found for the given value type`._
