How do I turn off logging? It’s killing me!

Either instantiate the Browser with

browser = Celerity::Browser.new(:log_level => :off)

or set it later

browser.log_level = :off

See also the full list of supported options.

Finding elements by :index is not doing what I expect.

To stay compatible with Watir, locating elements by :index or fetching elements from ElementCollection subclasses is 1-indexed.
To change this to zero-index, versions >= 0.0.6.10 lets you set

Celerity.index_offset = 0

How can I find elements that use non-ASCII characters?

Celerity encodes all strings as UTF-8, so if you save your test scripts as UTF-8 everything should work fine.
To make Watir use UTF-8, add this line to your test suite (WTR-219):

WIN32OLE.codepage = WIN32OLE::CP_UTF8 

Can I watch my tests execute?

See Viewers.

How do I deal with pages that make Ajax calls?

See Ajax.

How do I deal with popups?

Use ClickableElement#click_and_attach. This method returns a new browser instance with the page returned when clicking the element.

Example:

popup_browser = browser.link(:id, 'popup').click_and_attach
# do something with popup_browser
popup_browser.close
# continue working with browser

How do I deal with JavaScript dialogs or alerts?

HtmlUnit provides a listener interface for alert() and confirm() calls.
To access this with Celerity, you can use:

browser.add_listener(:alert) { |page, message| ... }

browser.add_listener(:confirm) { |page, message| ... }

If the value returned from the :confirm block is false, the “Cancel” button will be clicked.
You can also use Browser#confirm for easier interaction:

browser.confirm(false) do
   # trigger confirm() call 
end

How do I download files?

If you have a link or button that returns a document you normally wouldn’t view in a browser, you can use ClickableElement#download to get an IO object instead.

browser.link(:id, 'pdf').download #=> #<IO:0x11ce78c>

How do I visit a list of links from a single page?

This is a common mistake made when visiting a list of links:

links = browser.links.select { |link| link.href =~ /some_string/ }
links.each do |link|
  link.click
  # do some work
end

The «links» variable contains a list of Link objects, and each link was located on the page when Link#href was called. When the page is changed, the Link object might be in an invalid state.
Even though the above code might work fine in some situations, the safest way of iterating over links is storing a way of locating the link rather than the Link object itself, and call Browser#back before clicking the next link in the list:

hrefs = browser.links.map { |link| link.href if link.href =~ /some_string/ }.compact
hrefs.each do |href|
  browser.link(:url, href).click
  # do some work
  browser.back
end

How do I specify to ignore SSL errors while testing?

You need to specify this with HtmlUnit:

@b = Celerity::Browser.new
@b.webclient.setUseInsecureSSL true

Troubleshooting

Celerity doesn’t work with Test::Unit’s autorun

This is caused by a JRuby bug in versions pre-1.2.
Update to JRuby >= 1.2 to get rid of this problem.

I’m getting an error from DRb

This is caused by a JRuby bug, and only appears when running off jruby-complete.jar on Celerity version <= 0.0.6.15. Until the bug is fixed, you can solve the problem by doing a proper install of JRuby, updating Celerity or adding this:

require "thread.rb"