Add Navigator Actions.

[jhugman]

This PR does two things:

1. Absorbs some common wait methods in to navigator.
2. Adds a new concept of "navigator actions".

The shortcut actions are closures which can be added to the map. The closures take a navigator.

They are invoked with navigator.perfomAction.

They can be used in two ways:

• as a shortcut action to invoke one or more high level tasks.
• use an app object and navigator.nowAt to decide which screen state the app is in.
• as a post action trigger (via transitionTo:) to decide which screen state the app is in.

This is especially helpful when an app is stateful or relies on a server: mappamundi can look at the app and decide where on the graph it is meant to be in.

This is added in service of Lockbox testing.

[garvankeeley]

The shortcut actions term is confusing to me because it collides with the concept of shortcut actions that also exists in UI (as in keyboard shortcuts). What makes these actions ‘shorter’ than adding using other methods? It is because they aren’t added on a per-tap basis (bypassing the UI)?

Maybe 'JumpAction' or 'GotoAction'? Or 'UIBypassAction' ?

[jhugman]

The shortcut actions term is confusing to me because it collides with the concept of shortcut actions that also exists in UI (as in keyboard shortcuts)

Hmm, yes I see what you mean.

The intention is to have an action encapsulates some imperative code that performs one or more navigator methods.

map.addShortcutAction(Actions.SetExactlyOneItem) { navigator in
    switch navigator.userState.numItems {
    case 0:
      break
    case 1:
      return
    default:
      navigator.performAction(Actions.DeleteAll)
    }
    navigator.performAction(Actions.AddItem)
}

However, their utility is increased by allowing them to be chained from existing simpler actions in the app.

From within a login screen state node:

    screenState.tap(app.buttons["Sign in"], forAction: Actions.FxALoginButton, transitionTo: Actions.PostLogin)

Then later, when the navigator is not sure if the app needs to be an email confirmation or not:

map.addShortcutAction(Actions.PostLogin) { navigator in
    if app.staticTexts["Confirm by email"].exists {
        navigator.nowAt(Screens.FxAEmailConfirmation)
    } else {
        navigator.nowAt(Screens.SettingsScreen)
    }        
}

So perhaps this should be called a "navigator action", since it uses a MMNavigator and is has multiple uses. What you say, @garvankeeley ?

[garvankeeley]

I like Navigator Action as a term, it has no conflict with UI terms, and is clear that it is different from screenState actions.

[jhugman]

Thanks @garvankeeley !