How much should interfaces of elements in Page Objects be abstracted?

Question

I have a page object called LineItemsPage

class LineItemsPage
  attr_accessor :add_line_item_button

  def initialize(test_env)
    @browser              = test_env[:browser]
    @action_bar           = @browser.div(:id => 'lineitems_win').div(:class => 'window-body').div(:class => 'actionbar')
    @add_line_item_button = @action_bar.img(:class => 'button add')
  end

  def method_missing(sym, *args, &block)
    @browser.send sym, *args, &block
  end

end

I use it like so:

When /^I click on Add Item and enter the following values:$/ do |table|
  @line_items_page = LineItemsPage.new(@test_env)
  @line_items_page.add_line_item_button.when_present.click
end

I'm wondering if I should be abstracting the click, by adding something like the following to my LineItemsPage class:

def add_item
  self.add_line_item_button.when_present.click
end

And then using it like so:

@line_items_page.add_item

I'm looking for best practices, either with regards to Page Object in particular or Ruby in general. I feel that encapsulating the interface by using add_item() is going a bit far, but I'm wondering if I'm unaware of issues I might run into down the road if I don't do that.

Answer 1

Personally, I try to make my page object methods be in the domain language with no reference to the implementation.

I used to do something like @line_items_page.add_line_item_button.when_present.click, however it has caused problems in the following scenarios:

1) The add line item was changed from a button to a link.

2) The process for adding a line item has changed - say its now done by a right-click or it has become a two step process (like open some dropdown and then click the add line).

In either case, you would have to locate all the places you add line items and update them. If you had all the logic in the add_item page object method, you would only have to update the one place.

From an implementation perspective, I have found that Cheezy's page object accessors work pretty well. However, for image buttons (or any of your app's custom controls), I would add additional methods to the PageObject::Accessors module. Or if they are one off controls, you can add the methods directly to the specific page object.

Update - Reply to Comment Regarding Some Starting Points:

I have not come across too much documentation, but here are a couple links that might help:

1) The Cheezy Page Object project wiki - Gives a simple example to get started

2) Cheezy's blog posts where the page object gem first started. Note that the content here might not be exactly how the gem is currently implemented, but I think it gives a good foundation to understanding what he is trying to achieve. This in turn makes it easier to understand what is happening when you have to open up and modify the gem to fit you needs.