Drive System Tests with PhantomJS/Poltergeist

Workarea 3.3 changes the browser and driver for system tests from PhantomJS/Poltergeist to Chrome/Selenium. However, Workarea 3.3 continues to provide a Poltergeist driver, so if you have an existing suite of system tests written for PhantomJS/Poltergeist, you can continue to run some or all of those tests using Poltergeist rather than headless Chrome. To do so, complete the following 3 steps:

  1. Restore the Poltergeist Library as a Dependency
  2. Load the Capybara Poltergeist Library
  3. Declare Poltergeist as the Test Driver

Beware however, the Poltergeist driver is deprecated within the Workarea platform and is marked for removal in Workarea 4.

Example Test Files

The following examples are used to represent your existing test suite. The examples include a decorator which extends a platform test case, a test case that’s unique to the application, and the standard test helper that’s created by the app template. Unlike your real test suite, the example tests simply assert which driver is currently driving the test, which defaults to :headless_chrome in Workarea 3.3.

# test/system/workarea/storefront/products_system_test.decorator

require 'test_helper'

module Workarea
  decorate Storefront::ProductsSystemTest do
    def test_showing_a_product
      assert_equal(:headless_chrome, Capybara.current_driver)
    end

    def test_showing_a_product_with_inactive_skus
      assert_equal(:headless_chrome, Capybara.current_driver)
    end
  end
end

# test/system/workarea/storefront/warranties_system_test.rb

require 'test_helper'

module Workarea
  module Storefront
    class WarrantiesSystemTest < Workarea::SystemTest
      def test_adding_a_warranty
        assert_equal(:headless_chrome, Capybara.current_driver)
      end

      def test_removing_a_warranty
        assert_equal(:headless_chrome, Capybara.current_driver)
      end
    end
  end
end

# test/test_helper.rb

ENV['RAILS_ENV'] ||= 'test'
require File.expand_path('../../config/environment', __FILE__ )
require 'rails/test_help'
require 'workarea/test_help'

class ActiveSupport::TestCase
  # Add more helper methods to be used by all tests here...
end

1. Restore the Poltergeist Library as a Dependency

Since Workarea 3.3 no longer depends on Poltergeist, you must explicitly add it as a dependency of your application. To do so, run the following command from your application’s root directory (use a different Poltergeist version constraint if appropriate for your application).

$ bundle add poltergeist --version='~> 1.11.0' --group=test

This command results in changes to Gemfile and Gemfile.lock, as demonstrated below.

diff --git a/Gemfile b/Gemfile
index 521b066..0fc9684 100644
--- a/Gemfile
+++ b/Gemfile
@@ -46,3 +46,6 @@ end
 source 'https://gems.weblinc.com' do
   gem 'workarea', '3.3.0.beta.1'
 end
+
+# Added at 2018-05-23 17:23:57 -0400 by chriscressman:
+gem "poltergeist", "~> 1.11.0", :group => [:test]

diff --git a/Gemfile.lock b/Gemfile.lock
index 0f8e7f3..32853f5 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -79,6 +79,7 @@ GEM
     chromedriver-helper (1.2.0)
       archive-zip (~> 0.10)
       nokogiri (~> 1.8)
+ cliver (0.3.2)
     coffee-rails (4.2.2)
       coffee-script (>= 2.2.0)
       railties (>= 4.0.0)
@@ -248,6 +249,10 @@ GEM
     nokogiri (1.8.2)
       mini_portile2 (~> 2.3.0)
     normalize-rails (4.1.1)
+ poltergeist (1.11.0)
+ capybara (~> 2.1)
+ cliver (~> 0.3.1)
+ websocket-driver (>= 0.2.0)
     predictor (2.3.1)
       redis (>= 3.0.0)
     premailer (1.11.1)
@@ -517,6 +522,7 @@ DEPENDENCIES
   coffee-rails (~> 4.2)
   jbuilder (~> 2.5)
   listen (>= 3.0.5, < 3.2)
+ poltergeist (~> 1.11.0)
   puma (~> 3.7)
   rails (~> 5.1.5)
   selenium-webdriver

2. Load the Capybara Poltergeist Library

Next, load Capybara::Poltergeist, which provides the Capybara Poltergeist driver. This library depends on the Rails test help and is depended on by the Workarea test help. You must therefore load this library within your application’s test helper, between the Rails and Workarea help. Refer to the following patch.

diff --git a/test/test_helper.rb b/test/test_helper.rb
index f3220fa..5ffb447 100644
--- a/test/test_helper.rb
+++ b/test/test_helper.rb
@@ -1,6 +1,7 @@
 ENV['RAILS_ENV'] ||= 'test'
 require File.expand_path('../../config/environment', __FILE__ )
 require 'rails/test_help'
+require 'capybara/poltergeist'
 require 'workarea/test_help'

 class ActiveSupport::TestCase

3. Declare Poltergeist as the Test Driver

Now you can declare Poltergeist as the test driver for your system tests, either for specific tests and test cases, or for all system tests.

Tests

To drive specific tests with Poltergeist, wrap the body of each test in a Capybara.using_driver block, which declares Poltergeist as the driver for the duration of the block. The following examples modify one test from each of the example test cases.

diff --git a/test/system/workarea/storefront/products_system_test.decorator b/test/system/workarea/storefront/products_system_test.decorator
index aef8fe2..5412a08 100644
--- a/test/system/workarea/storefront/products_system_test.decorator
+++ b/test/system/workarea/storefront/products_system_test.decorator
@@ -3,7 +3,9 @@ require 'test_helper'
 module Workarea
   decorate Storefront::ProductsSystemTest do
     def test_showing_a_product
- assert_equal(:headless_chrome, Capybara.current_driver)
+ Capybara.using_driver(:poltergeist) do
+ assert_equal(:poltergeist, Capybara.current_driver)
+ end
     end

     def test_showing_a_product_with_inactive_skus

diff --git a/test/system/workarea/storefront/warranties_system_test.rb b/test/system/workarea/storefront/warranties_system_test.rb
index b78adfb..0bfc07e 100644
--- a/test/system/workarea/storefront/warranties_system_test.rb
+++ b/test/system/workarea/storefront/warranties_system_test.rb
@@ -4,7 +4,9 @@ module Workarea
   module Storefront
     class WarrantiesSystemTest < Workarea::SystemTest
       def test_adding_a_warranty
- assert_equal(:headless_chrome, Capybara.current_driver)
+ Capybara.using_driver(:poltergeist) do
+ assert_equal(:poltergeist, Capybara.current_driver)
+ end
       end

       def test_removing_a_warranty

Test Cases

To drive an entire test case (that is, an entire test class/file) with Poltergeist, call the driven_by macro within the test case definition or decorator. In the instance of a decorator, be aware this changes the driver for all tests in the test case, even those you haven’t extended within your decorator. This approach is therefore best reserved for test cases unique to your application or for decorators in which you are extending all the tests.

diff --git a/test/system/workarea/storefront/products_system_test.decorator b/test/system/workarea/storefront/products_system_test.decorator
index aef8fe2..2028666 100644
--- a/test/system/workarea/storefront/products_system_test.decorator
+++ b/test/system/workarea/storefront/products_system_test.decorator
@@ -2,12 +2,16 @@ require 'test_helper'

 module Workarea
   decorate Storefront::ProductsSystemTest do
+ decorated do
+ driven_by :poltergeist
+ end
+
     def test_showing_a_product
- assert_equal(:headless_chrome, Capybara.current_driver)
+ assert_equal(:poltergeist, Capybara.current_driver)
     end

     def test_showing_a_product_with_inactive_skus
- assert_equal(:headless_chrome, Capybara.current_driver)
+ assert_equal(:poltergeist, Capybara.current_driver)
     end
   end
 end

diff --git a/test/system/workarea/storefront/warranties_system_test.rb b/test/system/workarea/storefront/warranties_system_test.rb
index b78adfb..7ccab66 100644
--- a/test/system/workarea/storefront/warranties_system_test.rb
+++ b/test/system/workarea/storefront/warranties_system_test.rb
@@ -3,12 +3,14 @@ require 'test_helper'
 module Workarea
   module Storefront
     class WarrantiesSystemTest < Workarea::SystemTest
+ driven_by :poltergeist
+
       def test_adding_a_warranty
- assert_equal(:headless_chrome, Capybara.current_driver)
+ assert_equal(:poltergeist, Capybara.current_driver)
       end

       def test_removing_a_warranty
- assert_equal(:headless_chrome, Capybara.current_driver)
+ assert_equal(:poltergeist, Capybara.current_driver)
       end
     end
   end

All System Tests

To drive all system tests with Poltergeist, call the driven_by macro within the Workarea::SystemTest definition. You can do this in your application test helper, as shown below. However, this approach will affect all system tests run from your application, so it will affect your ability to run platform tests from within your application (because they are written for headless Chrome). This approach is therefore not recommended for most applications.

diff --git a/test/test_helper.rb b/test/test_helper.rb
index 5ffb447..16603c2 100644
--- a/test/test_helper.rb
+++ b/test/test_helper.rb
@@ -7,3 +7,7 @@ require 'workarea/test_help'
 class ActiveSupport::TestCase
   # Add more helper methods to be used by all tests here...
 end
+
+class Workarea::SystemTest
+ driven_by :poltergeist
+end

diff --git a/test/system/workarea/storefront/products_system_test.decorator b/test/system/workarea/storefront/products_system_test.decorator
index aef8fe2..2a94657 100644
--- a/test/system/workarea/storefront/products_system_test.decorator
+++ b/test/system/workarea/storefront/products_system_test.decorator
@@ -3,11 +3,11 @@ require 'test_helper'
 module Workarea
   decorate Storefront::ProductsSystemTest do
     def test_showing_a_product
- assert_equal(:headless_chrome, Capybara.current_driver)
+ assert_equal(:poltergeist, Capybara.current_driver)
     end

     def test_showing_a_product_with_inactive_skus
- assert_equal(:headless_chrome, Capybara.current_driver)
+ assert_equal(:poltergeist, Capybara.current_driver)
     end
   end
 end

diff --git a/test/system/workarea/storefront/warranties_system_test.rb b/test/system/workarea/storefront/warranties_system_test.rb
index b78adfb..1174589 100644
--- a/test/system/workarea/storefront/warranties_system_test.rb
+++ b/test/system/workarea/storefront/warranties_system_test.rb
@@ -4,11 +4,11 @@ module Workarea
   module Storefront
     class WarrantiesSystemTest < Workarea::SystemTest
       def test_adding_a_warranty
- assert_equal(:headless_chrome, Capybara.current_driver)
+ assert_equal(:poltergeist, Capybara.current_driver)
       end

       def test_removing_a_warranty
- assert_equal(:headless_chrome, Capybara.current_driver)
+ assert_equal(:poltergeist, Capybara.current_driver)
       end
     end
   end