terminus 0.3.0 → 0.4.0

data/README.rdoc

@@ -1,35 +1,41 @@
 = Terminus
 
-* http://terminus.jcoglan.com
-
-Terminus is an experimental Capybara driver implemented in client-side
-JavaScript. It lets you script your application in any browser on any device,
-without needing browser plugins. This allows several types of testing to be
-automated:
-
+{Terminus}[http://terminus.jcoglan.com] is a {Capybara}[https://github.com/jnicklas/capybara]
+driver for real browsers. It lets you control your application in any browser on
+any device (including {PhantomJS}[http://phantomjs.org/]), without needing
+browser plugins. This allows several types of testing to be automated:
+    
 * Cross-browser testing
+* Headless testing
 * Multi-browser interaction e.g. messaging apps
-* Testing on remote machines, phones, iPads etc.
+* Testing on remote machines, phones, iPads etc
+
+
+== Running the example
+
+Install the dependencies and boot the Terminus server, then open
+{http://localhost:70004/}[http://localhost:70004/] in your browser.
 
+    bundle install
+    bundle exec bin/terminus
 
-== Notes / to-do
+With your browser open, start an IRB session and begin controlling the app:
 
-* Support IE, which has no built-in XPath engine for querying the DOM. I'm
-  working on Pathology (see http://github.com/jcoglan/pathology) to try and fix
-  this but it's currently not fast enough.
-  
-* It's slow, especially at filling out forms. Use it to sanity-check your
-  cross-browser code and JavaScript, not to test your whole app.
-  
-* It can be a little brittle, and occasionally there seem to be race conditions
-  when running the Capybara specs.
+    $ irb -r ./example/app
+    >> extend Capybara::DSL
+    >> visit '/'
+    >> click_link 'Sign up!'
+    >> fill_in 'Username', :with => 'jcoglan'
+    >> fill_in 'Password', :with => 'hello'
+    >> choose 'Web scale'
+    >> click_button 'Go!'
 
 
 == License
 
 (The MIT License)
 
-Copyright (c) 2010-2011 James Coglan
+Copyright (c) 2010-2012 James Coglan
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the 'Software'), to deal in

data/bin/terminus

@@ -2,7 +2,7 @@
 
 require 'rubygems'
 require 'oyster'
-require File.expand_path(File.dirname(__FILE__) + '/../lib/terminus')
+require File.expand_path('../../lib/terminus', __FILE__)
 
 spec = Oyster.spec do
   name "terminus -- Control web browsers with Ruby"

data/lib/capybara/driver/terminus.rb

@@ -1,24 +1,35 @@
 class Capybara::Driver::Terminus < Capybara::Driver::Base
   attr_reader :options
   
+  NULL_APP = lambda do |env|
+    [200, {'Content-Type' => 'text/html'}, ['']]
+  end
+  
   def initialize(app = nil, options = {})
-    raise ArgumentError.new if app.nil?
-    
-    @app         = Terminus::Proxy[app]
+    @app         = Terminus::Proxy[app || NULL_APP]
     @options     = options
     @rack_server = Capybara::Server.new(@app)
     
     @rack_server.boot
+    sleep(0.1) until Terminus.server_running?(@rack_server)
   end
   
   def find(xpath)
     browser.find(xpath, self)
   end
   
+  def invalid_element_errors
+    [::Terminus::ObsoleteElementError]
+  end
+  
   def visit(path)
     browser.visit(@rack_server.url(path))
   end
   
+  def wait?
+    true
+  end
+  
   extend Forwardable
   def_delegators :browser, :body,
                            :current_url,
@@ -35,18 +46,7 @@ class Capybara::Driver::Terminus < Capybara::Driver::Base
     yield
     Terminus.browser = current_browser
   end
-  
-  def within_frame(name)
-    frame_src = browser.frame_src(name)
-    frame = browser.frames.find do |frame|
-      frame.current_url == frame_src or
-      frame.current_path == frame_src
-    end
-    current_browser = browser
-    Terminus.browser = frame
-    yield
-    Terminus.browser = current_browser
-  end
+  alias :within_frame :within_window
   
 private
   
@@ -56,11 +56,22 @@ private
   end
 end
 
-# Capybara 0.3.9 looks in the Capybara::Driver namespace for
-# appropriate drivers. 0.4 uses this registration API instead.
+# Capybara 0.3.9 looks in the Capybara::Driver namespace for appropriate
+# drivers. 0.4 uses this registration API instead.
 if Capybara.respond_to?(:register_driver)
   Capybara.register_driver :terminus do |app|
     Capybara::Driver::Terminus.new(app)
   end
 end
 
+# We use WEBrick to boot the test app, because if we use Thin (the default) the
+# slow response used to test Ajax resynchronization blocks the event loop. This
+# stops Terminus receiving messages and causes false positives: the client is
+# not really waiting for Ajax to complete, it's just having its messages blocked
+# because EventMachine is frozen.
+
+Capybara.server do |app, port|
+  handler = Rack::Handler.get('webrick')
+  handler.run(app, :Port => port, :AccessLog => [], :Logger => WEBrick::Log::new(nil, 0))
+end
+

data/lib/terminus.rb

@@ -1,17 +1,20 @@
+require 'erb'
 require 'forwardable'
+require 'http/parser'
+require 'net/http'
+require 'rbconfig'
+require 'socket'
+require 'stringio'
 require 'uri'
-require 'rack'
-require 'thin'
+
+require 'capybara'
+require 'childprocess'
+require 'cookiejar'
 require 'eventmachine'
 require 'faye'
-require 'sinatra'
-require 'packr'
-require 'capybara'
 require 'rack-proxy'
 require 'useragent'
 
-Thin::Logging.silent = true
-
 module Terminus
   FAYE_MOUNT   = '/messaging'
   DEFAULT_HOST = 'localhost'
@@ -19,9 +22,11 @@ module Terminus
   LOCALHOST    = /^(localhost|0\.0\.0\.0|127\.0\.0\.1)$/
   RETRY_LIMIT  = 3
   
-  ROOT = File.expand_path(File.dirname(__FILE__))
+  ROOT = File.expand_path('..', __FILE__)
   autoload :Application, ROOT + '/terminus/application'
   autoload :Browser,     ROOT + '/terminus/browser'
+  autoload :Client,      ROOT + '/terminus/client'
+  autoload :Connector,   ROOT + '/terminus/connector'
   autoload :Controller,  ROOT + '/terminus/controller'
   autoload :Host,        ROOT + '/terminus/host'
   autoload :Node,        ROOT + '/terminus/node'
@@ -31,24 +36,23 @@ module Terminus
   
   require ROOT + '/capybara/driver/terminus'
   
+  class ObsoleteElementError < StandardError
+  end
+  
   class << self
-    attr_accessor :debug
+    attr_accessor :debug, :sockets
     
     def create(options = {})
       Server.new(options)
     end
     
-    def driver_script(host = DEFAULT_HOST)
-      Application.driver_script(host)
-    end
-    
     def endpoint(host = DEFAULT_HOST)
       "http://#{host}:#{port}#{FAYE_MOUNT}"
     end
     
     def ensure_reactor_running
       Thread.new { EM.run unless EM.reactor_running? }
-      while not EM.reactor_running?; end
+      Thread.pass until EM.reactor_running?
     end
     
     def port
@@ -59,14 +63,24 @@ module Terminus
       @port = port.to_i
     end
     
+    def start_browser(options = {})
+      Client::Browser.start(options)
+    end
+    
+    def start_phantomjs(options = {})
+      Client::PhantomJS.start(options)
+    end
+    
     extend Forwardable
     def_delegators :controller, :browser,
                                 :browsers,
                                 :browser=,
+                                :cookies,
                                 :ensure_browsers,
                                 :return_to_dock,
                                 :rewrite_local,
-                                :rewrite_remote
+                                :rewrite_remote,
+                                :server_running?
     
   private
     

data/lib/terminus/application.rb

@@ -1,24 +1,18 @@
+require 'packr'
+require 'sinatra'
+
 module Terminus
   class Application < Sinatra::Base
     
-    ROOT = File.expand_path(File.dirname(__FILE__) + '/../')
+    ROOT = File.expand_path('../..', __FILE__)
     
     set :static, true
-    set :public, ROOT + '/terminus/public'
-    set :views,  ROOT + '/terminus/views'
-    
-    def self.driver_script(host)
-      %Q{<script type="text/javascript" src="http://#{host}:#{Terminus.port}/bootstrap.js"></script>}
-    end
+    set :root,   ROOT + '/terminus'
     
     helpers do
       def bootstrap
         Packr.pack(erb(:bootstrap), :shrink_vars => true)
       end
-      
-      def host
-        "http://#{ env['HTTP_HOST'] }"
-      end
     end
     
     get '/' do

data/lib/terminus/browser.rb

@@ -2,14 +2,15 @@ module Terminus
   class Browser
     
     include Timeouts
+    attr_reader :connector
+    attr_writer :sockets
     
     extend Forwardable
-    def_delegator  :@user_agent, :browser, :name
     def_delegators :@user_agent, :os, :version
     
-    def initialize(controller)
+    def initialize(controller, id)
       @controller = controller
-      @attributes = {}
+      @attributes = {'id' => id}
       @docked     = false
       @frames     = Set.new
       @namespace  = Faye::Namespace.new
@@ -25,20 +26,32 @@ module Terminus
       return false unless @user_agent
       
       params.all? do |name, value|
-        property = __send__(name).to_s
-        case value
-        when Regexp then property =~ value
-        when String then property == value
-        end
+        property = __send__(name)
+        value === property
       end
     end
     
     def ask(command, retries = RETRY_LIMIT)
-      id = tell(command)
-      result_hash = wait_with_timeout(:result) { result(id) }
-      result_hash[:value]
+      debug(:ask, id, command)
+      value = if @connector
+        message = Yajl::Encoder.encode('commandId' => '_', 'command' => command)
+        response = @connector.request(message)
+        if response.nil?
+          retries == false ? false : ask(command)
+        else
+          result_hash = Yajl::Parser.parse(response)
+          result_hash['value']
+        end
+      else
+        command_id = tell(command)
+        result_hash = wait_with_timeout(:result) { result(command_id) }
+        result_hash[:value]
+      end
+      debug(:val, id, command, value)
+      raise ObsoleteElementError if value.nil?
+      value
     rescue Timeouts::TimeoutError => e
-      raise e if retries.zero?
+      raise e if retries == 1
       ask(command, retries - 1)
     end
     
@@ -47,12 +60,18 @@ module Terminus
     end
     
     def current_path
-      return nil unless url = @attributes['url']
-      URI.parse(url).path
+      URI.parse(current_url).path
     end
     
     def current_url
-      @attributes['url'] || ''
+      url = @attributes['url']
+      return '' unless url
+      return url unless @connector
+      rewrite_local(ask([:current_url]))
+    end
+    
+    def debug(*args)
+      p args if Terminus.debug
     end
     
     def docked?
@@ -64,7 +83,7 @@ module Terminus
     end
     
     def execute_script(expression)
-      tell([:execute, expression])
+      @connector ? ask([:execute, expression]) : tell([:execute, expression])
       nil
     end
     
@@ -80,25 +99,32 @@ module Terminus
       @frames.to_a
     end
     
-    def frame_src(name)
-      ask([:frame_src, name])
-    end
-    
     def id
       @attributes['id']
     end
     
+    def infinite_redirect?
+      return @infinite_redirect unless @connector
+      evaluate_script('!!window.TERMINUS_INFINITE_REDIRECT')
+    end
+    
+    def name
+      return 'PhantomJS' if @user_agent.to_str =~ /\bPhantomJS\b/
+      @user_agent.browser
+    end
+    
     def page_id
       @attributes['page']
     end
     
     def ping!(message)
-      p message if Terminus.debug
+      debug(:ping, id)
+      debug(:recv, message)
+      
       remove_timeout(:dead)
       add_timeout(:dead, Timeouts::TIMEOUT) { drop_dead! }
       
-      uri = @controller.rewrite_local(message['url'], @dock_host)
-      message['url'] = uri.to_s
+      message['url'] = rewrite_local(message['url'])
       
       @attributes = @attributes.merge(message)
       @user_agent = UserAgent.parse(message['ua'])
@@ -106,18 +132,20 @@ module Terminus
       
       @infinite_redirect = message['infinite']
       
-      if parent = message['parent']
-        @parent = Terminus.browser(parent)
+      if id =~ /\//
+        @parent = Terminus.browser(id.gsub(/\/[^\/]+$/, ''))
         @parent.frame!(self) unless @parent == self
       end
       
+      start_connector if message['sockets'] and sockets?
+      
       @ping = true
     end
     
     def reset!
       if url = @attributes['url']
         uri = URI.parse(url)
-        visit("http://#{uri.host}:#{uri.port}")
+        visit("http://#{uri.host}:#{uri.port}/")
       end
       ask([:clear_cookies])
       @attributes.delete('url')
@@ -128,17 +156,22 @@ module Terminus
     end
     
     def result!(message)
-      p message if Terminus.debug
-      @results[message['commandId']] = message['result']
+      debug(:result, id, message['commandId'], message['result'])
+      @results[message['commandId']] = {:value => message['result']}
     end
     
     def result(id)
       return nil unless @results.has_key?(id)
-      {:value => @results.delete(id)}
+      @results.delete(id)
     end
     
     def return_to_dock
-      visit "http://#{@dock_host}:#{Terminus.port}/"
+      return unless @dock_host
+      visit("http://#{@dock_host}:#{Terminus.port}/")
+    end
+    
+    def sockets?
+      @sockets.nil? ? Terminus.sockets != false : @sockets
     end
     
     def source
@@ -150,20 +183,27 @@ module Terminus
     end
     
     def tell(command)
-      id = @namespace.generate
-      p [id, command] if Terminus.debug
-      messenger.publish(channel, 'command' => command, 'commandId' => id)
-      id
+      command_id = @namespace.generate
+      debug(:tell, id, command, command_id)
+      messenger.publish(command_channel, 'command' => command, 'commandId' => command_id)
+      command_id
     end
     
     def visit(url, retries = RETRY_LIMIT)
       close_frames!
       uri = @controller.rewrite_remote(url, @dock_host)
       uri.host = @dock_host if uri.host =~ LOCALHOST
-      tell([:visit, uri.to_s])
-      wait_for_ping
       
-      if @infinite_redirect
+      if @connector
+        ask([:visit, uri.to_s], false)
+        @connector.drain_socket
+        @attributes['url'] = rewrite_local(uri)
+      else
+        tell([:visit, uri.to_s])
+        wait_for_ping
+      end
+      
+      if infinite_redirect?
         @infinite_redirect = nil
         raise Capybara::InfiniteRedirectError
       end
@@ -188,16 +228,21 @@ module Terminus
     def drop_dead!
       remove_timeout(:dead)
       close_frames!
+      @connector.close if @connector
       @dead = true
       @controller.drop_browser(self)
     end
     
   private
     
-    def channel
+    def command_channel
       "/terminus/clients/#{id}"
     end
     
+    def socket_channel
+      "/terminus/sockets/#{id}"
+    end
+    
     def close_frames!
       @frames.each { |frame| frame.drop_dead! }
       @frames = Set.new
@@ -205,12 +250,20 @@ module Terminus
     
     def detect_dock_host
       uri = URI.parse(@attributes['url'])
-      if uri.port == Terminus.port
-        @docked = true
-        @dock_host = uri.host
-      else
-        @docked = false
-      end
+      @docked = (uri.port == Terminus.port)
+      @dock_host = @attributes['host']
+    end
+    
+    def rewrite_local(url)
+      @controller.rewrite_local(url.to_s, @dock_host).to_s
+    end
+    
+    def start_connector
+      return if @connector or @dock_host.nil? or Terminus.browser != self
+      @connector = Connector::Server.new(self)
+      url = "ws://#{@dock_host}:#{@connector.port}/"
+      debug(:connect, id, url)
+      messenger.publish(socket_channel, 'url' => url)
     end
     
     def messenger