Exorcise Poltergeist with Apparition

I have struggled with flaky Capybara tests. Often the problem came down to a bug/feature of the poltegeist gem.

At first I would hunt down the problems, but as development pressures grew, I would just use the magic 'x' to mark tests as pending. And once marked pending, the yellow dots in the rspec output would stay there, haunting me for years. I would occasionally have a go at the pending tests, but soon gave up, it was just too time consuming.

Well now there is a solution to this, you can exorcise poltergeist. The magic word you need for this exorcism is APPARITION or more prosaicly, Thomas Walpole's apparition gem.

The apparition gem is a drop-in replacement for poltergeist, but without the bugs and idiosyncrasies. It works pretty much as described in the Readme. Add to your Gemfile:

  
    gem 'apparition'
  

and to your test setup:

  
    require 'capybara/apparition'
    Capybara.javascript_driver = :apparition
  

The gem supports all the features of Capybara and some additional functionality, including handling cookies and extra headers. If you were using the :rack_test driver, then there are some special considerations identified in the Readme.

If you use the capybara-screenshot gem, you can see a deprecation warning:

  capybara-screenshot could not detect a screenshot driver for 'apparition'. Saving with default with unknown results.
  

The master branch of capybara-screenshot shows works on supporting apparition so a new release cannot be far away.

I tried apparation on a test suite that had about 200 feature specs. Of these feature specs, 15 had been marked pending due to flaky tests. When I made the switch all of the active tests passed straight away, this was definitely magic. So I decided to go for broke and make all my pending tests active. I ran the test suite again on these tests and 12 out of the 15 passed straight away.

When I examined two of the tests, I realized that they had simple non-poltergeist errors in them. The last one passed after some debugging.

A neat feature of the apparition gem is that you can run a test in non-headless mode. Just set the following configuration option in your test helper

  
    Capybara.register_driver :apparition do |app|
      Capybara::Apparition::Driver.new(app, { headless: false })
    end
  

and you can actually see the tests run in the chrome browser. By inserting a debug break point in the test, you can even inspect the browser page, and open the console. This makes it much easier to debug javascript problems with your test.

Author: Dr. Chris Drane
Stack Overflow: Obromios
Date: August 8, 2019
Feedback: We welcome feedback, please contact us.