03 Writing custom steps

We've already looked at the Predefined steps which lets you interact with your application without doing any actual test-code programming.

Custom steps let you define your own steps like Then I login as "Rune". When you want to use a custom step you have to specify an implementation defining what that step is supposed to do. This is done by writing a little bit of Ruby code.

In Cucumber a step definition consist of two things: a regular expression (to matching the step text) and a block of Ruby code.

If you are not familiar with Cucumber and step definitions, you must find the appropriate information using the links: Cucumber step definition.

Custom step definitions

To write custom steps you must create a file named ..._steps.rb in the directory features/step_definitions. If you ran the command calabash-ios gen then that should have generated a file you can use:

krukow:~/github/calabash-ios-example$ ls features/step_definitions/
calabash_steps.rb	my_first_steps.rb

Take a look at the file my_first_steps.rb:

Given /^I am on the Welcome Screen$/ do
    element_exists("view")
    sleep(STEP_PAUSE)
end

This is an example step definition matching the step "Given I am on the Welcome Screen". The block of Ruby code contained in do ... end is the code that is executed when cucumber encounters "Given I am on the Welcome Screen". You can put any Ruby code in here. Let's do a simple example...

Macro steps

The simplest way of writing custom steps is to combine one or more existing steps. You do this using the macro function.

Then /^I log in$/ do
    macro 'I enter "ruk" into the "Login" text field'
    macro 'I enter "mypass" into the "Password" text field'
    macro 'I touch the "login" button'
end

The step I log in will perform three actions for the price of only one step.

Steps can take parameters:

USERS = {"Rune" => {:pass => "mypass", :user => "ruk"}}

Then /^I log in as "([^\"]*)"$/ do |user|
    macro %Q[I enter "#{USERS[user][:user]}" into the "Login" text field]
    macro %Q[I enter "#{USERS[user][:pass]}" into the "Password" text field]
    macro %Q[I touch the "login" button]
end

Three things to note:

You can write any Ruby code! In this case I define a global map USERS which has a key for each user, and :user and :pass entries for that user. The can be used inside the step definition.
You can use Ruby's string escape syntax %Q[...] to write a string where you can use both single quote ('), double quote (") and interpolation (e.g., asdf#{variable}dsa).
Step definitions can be parameterized. You can write regular expressions inside parentheses (...) - those are called groups. In our example we write a regular expresion that must start with I log in as then there must be a quote ". Then any text which doesn't contain quotes: the regular expression is written in parentheses as: [^\"]* meaning zero or more characters that are not " (for example Rune will match). After that there must be an end quote ".